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. 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.

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. 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.

Contents