Bulk assigning custom monitors in Management API

Prerequisites

• Use a Connect API key with the following permissions:

  • Monitor: Read-only (monitor:read) to discover and list custom monitors.

  • Monitor: Write (monitor:write) to assign or unassign custom monitors.

  Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

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

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

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:

   Scroll horizontally to see the full table.

   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.

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.

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}}"]'