Learn about the REST API for managing Tanzu Observability by Wavefront.

The Wavefront REST API enables you to write scripts to perform management tasks, such as defining alerts and creating events. You can use the REST API to perform any task that is supported by the Tanzu Observability GUI. The REST API is based on Swagger, so you can generate the API client of your choice (including a CLI client).

REST API Overview

All interactions between the UI and your Wavefront instance occur through the Wavefront API. You can perform those actions using REST - or you can create an API client using Swagger, discussed below.

The current version of the REST API is v2. You can access the API at <your_instance>/api/v2. The v1 API (<your_instance>/api/) was deprecated in 2017 and is no longer supported.

API Documentation (Wavefront Instance)

Each Wavefront instance includes Swagger-generated documentation for the REST API. In our blog post Did You Know that Our API Docs Are Alive we explain how you can experiment with our API directly from this in-product documentation.

To access the REST API documentation :

  1. Log in to your Wavefront instance.
  2. Display the doc from the UI or using a URL:
    • In the UI, click the gear icon at the top right of the toolbar and select API Documentation.
    • Type https://<your_instance>.com/api-docs/ui/

REST API in a Wavefront instance

API Documentation (VMware code)

If you don’t have access to a Wavefront instance, you can have a look at our API doc on the VMware code site.

We include an overview and a Swagger-generated API Reference. We update the reference with each release.

REST API in VMware code

The VMware code website also includes some samples, for example, for getting data into Tanzu Observability. We’re providing these samples as is - some are from our team, others will come from the community.

Managing API Tokens

Before you can invoke the Wavefront API using curl or from an API client, you must have an API token.

An API token is a string of hexadecimal characters and dashes. For example:

a411c16b-3cf7-4f03-bf11-8ca05aab898d

Tanzu Observability by Wavefront allows user accounts and service accounts to use the Wavefront REST API.

Generate and Manage the API Tokens for Your User Account

  1. Log in to your Wavefront instance.
  2. Click the gear icon at the top right of the toolbar and select your user name.
  3. On the API Access tab, click Generate.

    You can have up to 20 tokens at any given time. If you want to generate a new token but already have 20 tokens, then you must revoke one of the existing tokens.

  4. To revoke a token, click the Revoke button for the token.

    If you run a script that uses a revoked token, the script returns an authorization error.

  5. To add a name or rename an API token, click the Edit icon for the token, enter the name, and press Enter.

Generate API Token

Generate and Manage the API Tokens for a Service Account

As a user with the Accounts permission, you can generate API tokens for service accounts upon creation or at a later stage. To generate an API token for an existing service account:

  1. Log in to your Wavefront instance as a user with the Accounts permission.
  2. Click the gear icon at the top right of the toolbar and select Accounts.
  3. On the Service Accounts tab, click the ellipsis icon next to the service account for which you want to generate an API token, and select Edit.
  4. To generate a new token, in the Tokens section, click Generate.

    You can have up to 20 tokens per service account at any given time. If you want to generate a new token but already have 20 tokens, then you must revoke one of the existing tokens.

  5. To revoke a token, click the Revoke button for the token.

    Revoking a token cannot be undone.

  6. To rename an API token, click the Edit icon for the token, enter the name, and press Enter.
  7. Select the appropriate permissions for the service account and click Update.

View and Manage the API Tokens in Your Organization

As a user with the Accounts permission, you can view and revoke the API token of any user or service account in your organization.

  1. Log in to your Wavefront instance as a user with the Accounts permission.
  2. Click the gear icon at the top right of the toolbar and select Accounts.
  3. Click the API Tokens tab.

You see the API tokens for all user and service accounts in a paginated table format.

The API Tokens page shows the tokens table, the search field above the table, and the preconfigured filters and the saved searches in the left panel

On the API Tokens page, you can:

  • Sort the API tokens table by column.
  • Search and, optionally, save and share your search.
  • Filter the API tokens by account type, usage, particular accounts, or your saved search.
  • Revoke an API token from the vertical ellipsis icon for the token.

Invoking the API

You can invoke the Wavefront API using curl or from an API client. In either case, you must pass in an API token.

Example: Invoke the API Using curl

With curl, you specify the API token in the Authorization: Bearer header. For example, to return all alerts, run the following command:

curl 'https://<your_instance>/api/v2/alert' --header 'Authorization: Bearer <your_api_token>'

Generate an API Client Using Swagger

Because we expose the Wavefront REST API via Swagger, you can generate a working implementation of the API for the programming language or CLI you want to use.

Here’s an example for generating a Java client:

  1. Create a file swagger-config.json. Here’s an example:
    {
    "modelPackage": "com.wavefront.rest.models",
    "apiPackage": "com.wavefront.rest.api.client",
    "groupId": "com.wavefront.rest.api.client",
    "artifactId": "wavefront-java-sdk",
    "artifactVersion": "19.10",
    "sourceFolder": "src/main/java",
    "java8": true,
    "dateLibrary": "java8"
    }
    
  2. Generate the client, for example:

swagger-codegen generate -i https://mydomain.wavefront.com/api/v2/swagger.json -c swagger-config.json -l java

Wavefront REST API Categories

The REST API supports the following objects corresponding to different categories of management tasks:

  • Access Policy - Lets you allow or deny access to embedded charts. For information, see Allow or Deny Access to Embedded Charts.
  • Access - Provides information on the access level of an entity. See Notes on the Access Category below.
  • Account (User and Service Account) - Allows users with Accounts permission to retrieve a list of all accounts, create, update, and delete accounts and manage permissions and groups associated with accounts.
  • Alert - Retrieve active, snoozed, in-maintenance, and invalid alerts. Users with Alerts permission can create and update alerts.
  • ApiToken - Allows users with Accounts permission to retrieve, create, and manage API tokens. Used primarily in conjunction with service accounts.
  • Cloud Integration - Retrieve cloud integration data types such as those available with the AWS integration. Users with Proxies permission can add and remove cloud integration data types.
  • Dashboard - Retrieve data about dashboards, list dashboards, and return version history. Users with Dashboards permission can save, create, delete, clone, undelete dashboards.
  • Derived Metric - Manage derived metrics.
  • Direct Ingestion - Perform direct ingestion instead of using a proxy.
  • Event - Retrieve events and tags associated with a specific event. Users with Events permission can create, update, and delete events. Deleting events is limited to non-system events. System events include events based on alert firings, error events, and maintenance windows.
  • External Link - Navigate external links. Users with External Links permission can create, update, and delete external links.
  • Integration - Retrieve integrations. Users with Integrations permission can install and uninstall integration dashboards.
  • Maintenance Window - Retrieve a complete or filtered list of existing maintenance windows. Users with Alerts permission can create, close, update, and delete maintenance windows.
  • Message - Retrieve messages and mark messages read.
  • Metric - Retrieve details on a metric.
  • Notificant - Allows users with Users with Alerts permission to create, delete, update, or test alert notification targets.
  • Proxy - Retrieve information about Wavefront proxies. Users with Proxies permission can add and remove Wavefront proxies.
  • Query - Perform queries.
  • Role - Retrieve information about a role and manage roles and role assignees.
  • Saved Search - Retrieve, add, and remove saved searches.
  • Search - Search agents, alerts, integrations, dashboards, external links, maintenance windows, sources, and webhook alert targets.
  • Source - Retrieve sources and tags associated with a source. Users with Source Tags permission can add and remove source tags and set descriptions.
  • Usage - Retrieve information about usage associated with ingestion policies and manage policies.
  • User - Deprecated API. Use Account (User and Service Account) instead.
  • UserGroup - Allows users with Accounts permission to retrieve a list of all groups, create, update, and delete groups, and manage the users and roles associated with a group.
  • Webhook - Retrieve webhooks. Users with Alerts permission can create, update, and delete webhooks.

Notes on the Access Category

The /api/access/{entity} endpoint provides information on how often an entity has been accessed. Supported entities are metric, histogram, span.

This GET endpoint has the following parameters:

ParameterDescription
name Entity name, e.g, cpu.usage (for a metric).
hostPrefix Prefix of the host name, e.g. you can use test-2a-app67 if the whole host name is test-2a-app67-id-12345
Warning:hostPrefix must be somewhat specific. There's a limit on how many hosts Tanzu Observability scans.
usageThresholdDays How many days to look back. 7 days by default.
includeDailyDetail Whether to provide additional data on daily usage. False by default.
  • If includeDailyDetail is false, GET returns true if the data has been accessed in the past usageThresholdDays, and false otherwise.
  • If includeDailyDetail is true, GET returns daily access details.