Bulk assigning custom monitors in Management API

Bulk assigning custom monitors in Management API#

This guide explains how to discover, assign, and unassign custom monitors for datastreams in bulk using the Management API. It also explains how to list custom monitors and manage the datastreams of a single monitor. For more information on custom monitors, see Working with custom monitors.

Note

These endpoints are part of the v1 Management API surface and only accept an API key generated in the Adverity user interface (Bearer). Keys generated with user credentials (Token) are not supported here.

Note

The request body of a bulk assign or unassign request can include at most 50 datastream or monitor IDs. Requests that exceed this limit return an HTTP 422 error.

Note

The bulk assign and unassign requests accept the same datastream query parameters as the OPTIONS request described in Discovering available custom monitors, including scheduled_deletion.

Prerequisites#

  • Obtain a Management API key with the appropriate scope:

    • monitor: read to discover available monitors.

    • monitor: write to assign or unassign monitors.

    For more information, see Authorizing to Management API.

  • A custom monitor and a datastream can only be assigned to each other if they share the same workspace, or if the monitor is defined in a parent workspace of the datastream (workspace inheritance).

Discovering available custom monitors#

To list the custom monitors available for assignment, follow these steps:

  1. Create an OPTIONS request to the following endpoint:

    https://{{INSTANCE}}/api/v1/datastreams/custom-monitors/

  2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

  3. (Optional) To limit the results to monitors eligible for one or more specific datastreams, add the datastream_id query parameter. Repeat the parameter to find the monitors eligible for every listed datastream at once (the intersection of eligible monitors across all specified datastreams):

    https://{{INSTANCE}}/api/v1/datastreams/custom-monitors/?datastream_id={{DATASTREAM_ID_1}}&datastream_id={{DATASTREAM_ID_2}}

  4. (Optional) To limit the results to monitors eligible for the datastreams in a specific scheduled deletion state, add the scheduled_deletion query parameter. Use true to consider only the datastreams that are scheduled for deletion, or false to exclude them. Omit the parameter to consider both.

  5. Send the request.

As a result, you obtain the list of custom monitors available for assignment, taking workspace inheritance into account.

The cURL request example is the following:

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/v1/datastreams/custom-monitors/' \
--header 'Authorization: Bearer {{KEY}}'

Bulk assigning custom monitors#

To assign one or more custom monitors to one or more datastreams in a single request, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/v1/datastreams/custom-monitors/

  2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the monitors and datastreams to assign. Use the OPTIONS response described in Discovering available custom monitors to confirm the exact field names and accepted value formats before sending this request.

  5. Send the request.

As a result, the monitors are assigned to the eligible datastreams. This operation supports partial success: the response indicates which datastreams were assigned (assigned_datastream_ids) and which were skipped (skipped_datastream_ids) because they do not share a workspace with the monitor (and do not inherit access to it). Assigning a monitor that is already assigned to a datastream has no additional effect.

Warning

If the request references a monitor ID that does not exist, the entire request is rejected with a 400 response and no datastream is updated. This atomic failure only applies to invalid monitor IDs — an ineligible datastream in an otherwise valid request is skipped, not rejected.

Bulk unassigning custom monitors#

To unassign one or more custom monitors from one or more datastreams in a single request, follow these steps:

  1. Create a DELETE request to the following endpoint:

    https://{{INSTANCE}}/api/v1/datastreams/custom-monitors/

  2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the monitors and datastreams to unassign. Use the OPTIONS response described in Discovering available custom monitors to confirm the exact field names and accepted value formats before sending this request.

  5. Send the request.

As a result, the monitors are unassigned from the specified datastreams. Unassigning a monitor that is not currently assigned to a datastream has no additional effect (idempotent).

Warning

If the request references a monitor ID that does not exist, the entire request is rejected with a 400 response and no existing assignment is changed. An ineligible datastream in an otherwise valid request is skipped, not rejected.

Listing custom monitors#

To list the custom monitors the API key can see, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/v1/custom-monitors/

  2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

  3. (Optional) To narrow the list, add any of the following query parameters:

    Parameter

    Description

    name__icontains

    Part of the monitor name, ignoring case.

    severity

    error or warning.

    workspace_id

    A workspace UUID. Repeat it for several workspaces, up to 50.

  4. Send the request.

As a result, you obtain the custom monitors of the API key’s workspace and the workspaces below it, paginated with the page and page_size query parameters. Each item contains the monitor’s id (UUID), name, severity, and the id and name of its workspace. This request requires the monitor: read scope.

The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/custom-monitors/?severity=error' \
--header 'Authorization: Bearer {{KEY}}'

Managing the datastreams of one custom monitor#

The following requests work on a single custom monitor, identified by its UUID in the URL. Use the list described in Listing custom monitors to find the UUID. A monitor the API key cannot see returns an HTTP 404 error.

Request

What it does

Scope

GET https://{{INSTANCE}}/api/v1/custom-monitors/{{MONITOR_ID}}/datastreams/

Lists the datastreams assigned to the monitor, paginated. Each item contains the datastream’s id (UUID), name, and workspace.

monitor: read

OPTIONS https://{{INSTANCE}}/api/v1/custom-monitors/{{MONITOR_ID}}/datastreams/

Lists the datastreams that can be assigned to the monitor: the ones in the monitor’s workspace family that are not assigned yet.

monitor: read

POST https://{{INSTANCE}}/api/v1/custom-monitors/{{MONITOR_ID}}/datastreams/

Assigns the datastreams in the request body to the monitor. Existing assignments are kept.

monitor: write

DELETE https://{{INSTANCE}}/api/v1/custom-monitors/{{MONITOR_ID}}/datastreams/

Unassigns the datastreams in the request body from the monitor.

monitor: write

For POST and DELETE, include the parameter Content-Type with value application/json in the HTTP request header, and send a JSON list of up to 50 datastream UUIDs, without duplicates, as the request body. The response is the same list.

Warning

If any datastream in the request body cannot be assigned, the entire request is rejected with a 400 response and no assignment is changed. For POST, every datastream must be in the monitor’s workspace family and visible to the API key. For DELETE, every datastream must be visible to the API key.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/custom-monitors/{{MONITOR_ID}}/datastreams/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '["{{DATASTREAM_ID_1}}", "{{DATASTREAM_ID_2}}"]'
Contents