Getting started with the Management API

Authorizing requests

Authorize requests to the Management API with a Connect API key, sent in the Authorization header as Bearer {{KEY}}. For more information, see Authorizing to Management API.

API reference

The API reference lists every operation, with the API key permission it needs and request samples. Your Adverity instance also serves it as interactive documentation at https://{{INSTANCE}}/api/docs/, where you can try requests. Replace {{INSTANCE}} with your Adverity instance.

Code

This documentation provides examples of requests you can make to the Management API and responses as code blocks. You can copy them and edit them. For example:

curl --location --request GET 'https://{{INSTANCE}}/api/datastreams/' \
--header 'Authorization: Bearer {{KEY}}'

You can import this code as raw text to Postman or to other HTTP clients.

List of endpoints

The following list provides information about all available endpoints of the Management API.

API versions

The Management API has two sets of endpoints:

• Legacy endpoints (/api/) — the first and broadest API surface. They remain fully supported, and existing integrations keep working as they are. However, their feature set is frozen, meaning no new features will be added here.

• v1 endpoints (/api/v1/) — the actively developed API surface. This is where we add new features; existing capabilities are brought over and improved over time. v1 endpoints follow their own conventions for keys, identifiers, pagination, and errors. For more information, see Working with v1 endpoints.

v1 does not cover every task yet. Where a task has no v1 endpoint, the legacy endpoint is the right choice. When you build something new, we recommend v1 for the tasks it covers.

The following table shows which endpoints to use for each task:

General workflow note

Often, you can work with the endpoints in the following manner:

1. Request initial IDs or basic information with a GET request.

2. Request available configuration options with an OPTIONS request.

3. Edit the configuration options or create a particular object with a POST or PATCH request.

Rate limits

Adverity’s Management API has no rate limits. However, each Management API call uses resources, so we recommend that you only perform one Management API task at a time. This avoids overloading your resources and will prevent performance issues. Wait for one Management API call to finish before performing another task.

Timestamps

Use UTC time zone in all timestamps in the Management API and use the following format:

%Y-%m-%dT%H:%M:%SZ

For example, this translates to the following:

2022-02-01T12:00:22Z

Using filters and ordering data

All the GET call responses can be filtered by specific parameters. Filter all GET call responses by including the id or date parameters.

To limit the number of results, use the page_size parameter.

https://{{INSTANCE}}/api/jobs/?stack=4&ordering=id&page_size=10

Error responses

Requests to the legacy endpoints (/api/) that fail with a client error status code, such as 400 or 404, return a response body in the following form:

{
  "detail": "Validation failed",
  "errors": {
    "name": ["This field may not be blank."]
  },
  "name": ["This field may not be blank."]
}

The response body contains the following fields:

• detail — a summary of the error as a single string. This field is always present.

• errors — the individual field errors, where the Adverity field name is the key. This field is only present when the request failed validation.

Adverity also keeps the original error fields at the top level of the response body, as shown by the name field in the example above. Use detail and errors in new integrations.

Server error status codes, such as 500, and the v1 (/api/v1/) endpoints are not affected. For the error responses of the v1 endpoints, see Errors in v1 endpoints.

Authentication and scopes in v1

v1 endpoints accept a Connect API key, sent as Authorization: Bearer {{KEY}}. For more information, see Authorizing to Management API.

Each key carries scopes, and each endpoint requires one. The following table shows the scope each area of v1 requires:

A key sees the workspace it was created for and all workspaces below it. Objects in other workspaces are not visible to the key.

To see which permissions a key has, open the Connect API keys page and open the key. For more information, see Authorizing to Management API.

Identifiers in v1

v1 endpoints identify datastreams, workspaces, tags, and custom monitors by UUID, for example 6f0c2a3e-7d5b-4b8e-9a51-2a8d3f0c9e11, not by the numeric ID that the legacy endpoints use. The uuid field of legacy responses holds the same UUID, so you can map numeric IDs to v1 identifiers. To find workspace UUIDs, use GET /api/v1/workspaces/.

A few v1 endpoints still take a numeric ID where their guide says so, for example the datastream_id filter of GET /api/v1/bindings/.

Pagination in v1

v1 list endpoints are paginated with the following query parameters:

The response body has the following form:

{
  "items": [],
  "count": 123
}

count is the total number of items across all pages. To read every item, increase page until you have read count items. Unlike the legacy endpoints, the response contains no next or previous links.

Filters in v1

To pass several values for one filter, repeat the query parameter, for example ?workspace_id={{WORKSPACE_ID_1}}&workspace_id={{WORKSPACE_ID_2}}. Most list filters accept up to 50 values.

Many v1 list endpoints also accept the following workspace filters:

The guide of each endpoint lists the filters it supports.

Errors in v1 endpoints

v1 endpoints return errors with a detail field:

{
  "detail": "Missing scopes: datastream:write."
}

The following status codes are common to all v1 endpoints:

Some endpoints add fields to an error response, such as the existing tag in a 409 response from POST /api/v1/datastream-tags/. Their guides describe these fields.