Tagging datastreams in Management API

This guide explains how to create datastream tags, add them to and remove them from datastreams in bulk, read them back, and filter datastreams by tag using the Management API.

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. For the conventions all v1 endpoints share, such as UUIDs, pagination, and errors, see Working with v1 endpoints.

Introduction

What is a datastream tag?

A tag is a short label, such as prod or daily, that you attach to datastreams to group them, for example to select them in an external orchestrator.

Which workspace does a tag belong to?

Every tag belongs to exactly one workspace. Its name is unique within that workspace, ignoring case. The same name in another workspace, including a parent or child workspace, is a separate tag.

Which tags can a datastream carry?

A datastream only carries tags of its own workspace. Anyone who can see the datastream can see its tags.

What happens when a datastream is copied or moved?

Its tags follow it. In another workspace, each tag is matched by name to a tag of that workspace, and created there if it does not exist yet.

Where do tag changes appear?

Adding, removing, and deleting tags appears in the History tab of each affected datastream, with the tag names before and after the change.

Prerequisites

Obtain a Management API key with the appropriate scope:

• datastream: read to list tags, read the tags of datastreams, and filter datastreams by tag.

• datastream: write to create, rename, and delete tags, and to add them to or remove them from datastreams.

An existing key may not have these scopes, even if it works with the legacy endpoints. For how to check a key and what to do if it lacks them, see Authentication and scopes in v1.

The key can only see and change tags of the workspaces it has access to. For more information, see Authorizing to Management API.

Limitations

What	Limit
Tag name	25 characters
Tags per datastream	50
Tags per bulk request	50
datastreams per bulk request	500, whether they are listed in datastream_ids or matched by query parameters

Requests that exceed the per-request list limits return an HTTP 422 error. A bulk request that matches more than 500 datastreams through its query parameters returns an HTTP 400 error.

Creating a tag

To create a tag, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/
   

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 following parameters:

   Parameter	Required	Description
   workspace_id	Yes	The UUID of the workspace that owns the tag.
   name	Yes	The tag name. Up to 25 characters. Leading and trailing spaces are removed.

5. Send the request.

As a result, Adverity creates the tag and returns it with HTTP 201. If the workspace already has a tag with the same name, ignoring case, the response is HTTP 409 and contains the existing tag in tag.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/datastream-tags/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"workspace_id": "{{WORKSPACE_ID}}", "name": "prod"}'

A tag in the response contains the following fields:

Field	Description
id	The UUID of the tag.
name	The tag name.
workspace	The id and name of the workspace that owns the tag.
created	When the tag was created.

The response to a create request also contains same_name_in_ancestor_workspaces: the parent workspaces, among those the key can see, that already have a tag with this name. Those are separate tags.

Listing tags

To list tags, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/
   

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

3. (Optional) To list the tags of specific workspaces, add the workspace_id query parameter. Repeat it for each workspace.

4. (Optional) To find a tag by its exact name, ignoring case, add the name query parameter.

5. Send the request.

As a result, you obtain the tags of the workspaces the key can see, sorted by name and paginated with the page and page_size query parameters.

To retrieve one tag, create a GET request to https://{{INSTANCE}}/api/v1/datastream-tags/{{TAG_ID}}/.

Renaming a tag

To rename a tag, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/{{TAG_ID}}/
   

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 name with the new tag name.

5. Send the request.

As a result, every datastream that carries the tag shows the new name. Earlier entries in the History tab keep the old name. If another tag of the same workspace has the new name, the response is HTTP 409. Changing only the case of the name is allowed. The workspace of a tag cannot change.

Deleting a tag

To delete a tag, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/{{TAG_ID}}/
   

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

3. Send the request.

As a result, Adverity deletes the tag and removes it from every datastream that carried it. The response field removed_from_datastreams contains the number of datastreams the tag was removed from.

Warning

Deleting a tag cannot be undone. To restore it, create the tag again and add it to the datastreams again.

Adding tags to datastreams

To add tags to up to 500 datastreams in one request, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastreams/tags/
   

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 following parameters:

   Parameter	Required	Description
   tags	Yes	Up to 50 tag names or tag UUIDs. A name is looked up in the workspace of each datastream, ignoring case. A UUID applies only to the datastreams of its own workspace.
   datastream_ids	No	Up to 500 datastream UUIDs.

5. (Optional) To target datastreams by their properties, add the query parameters of the datastream list, such as workspace_id or tag. For all of them, see Listing datastreams in Management API. They are combined with datastream_ids. A request needs datastream_ids, a query parameter, or both.

6. (Optional) To create tag names that a workspace does not have yet, add the create_missing=true query parameter.

7. Send the request.

As a result, each targeted datastream gets every tag that applies to it. The response contains the following fields:

Field	Description
assigned_datastream_ids	The datastreams that now carry every tag that applies to them.
skipped	The datastreams left unchanged, each with a reason and a detail. See the table below.
created_tags	The tags created because of create_missing=true.

If one of the tag UUIDs does not exist or the key cannot see it, for example because the tag was deleted, the whole request fails with HTTP 400 and no datastream is changed.

A datastream gets either all of the tags that apply to it or none of them. It is skipped for one of the following reasons, and the other datastreams are still tagged:

reason	Meaning
not_found	The datastream does not exist, the key cannot see it, or the query parameters exclude it.
tag_not_in_workspace	None of the given tag UUIDs belongs to the workspace of the datastream, and no tag names were given.
unknown_tag_name	The workspace of the datastream has no tag with one of the given names, and create_missing is not set.
tag_limit_exceeded	The datastream would carry more than 50 tags.

Sending the same request again changes nothing.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/datastreams/tags/?create_missing=true' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"tags": ["prod", "daily"], "datastream_ids": ["{{DATASTREAM_ID_1}}", "{{DATASTREAM_ID_2}}"]}'

Note

To tag every datastream of a workspace that has up to 500 datastreams, use the workspace_id query parameter without datastream_ids. For a larger workspace, list its datastreams with GET https://{{INSTANCE}}/api/v1/datastreams/?workspace_id={{WORKSPACE_ID}} and send their UUIDs in batches of 500.

Removing tags from datastreams

To remove tags from up to 500 datastreams in one request, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastreams/tags/
   

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 tags and datastream_ids as described in Adding tags to datastreams. The same query parameters apply.

5. Send the request.

As a result, the tags are removed from the targeted datastreams that carry them. The response field unassigned_datastream_ids lists the targeted datastreams, and skipped lists the ones that were not_found. As with adding, a tag UUID that does not exist or that the key cannot see fails the whole request with HTTP 400. A remove request never creates tags, and sending it again changes nothing.

Reading the tags of datastreams

To read the tags of up to 500 datastreams in one request, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastreams/tags/query/
   

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 datastream_ids with up to 500 datastream UUIDs.

5. Send the request.

As a result, you obtain one item per datastream the key can see, in the order of the request, each with its datastream_id and a tags list. Unknown UUIDs are left out. This request only reads; it uses POST because the list of UUIDs does not fit into a URL.

Filtering datastreams by tag

Each item of GET https://{{INSTANCE}}/api/v1/datastreams/ contains a tags list with the id and name of each tag. To list only datastreams with certain tags, add the following query parameters:

Parameter	Description
tag	A tag name, ignoring case. Repeat it for several names. It matches the name in every workspace the key can see. To match the tag of one workspace only, add workspace_id.
tag_match	any (default) to list datastreams with at least one of the given tags, or all to list datastreams with every given tag.

You can combine them with the other query parameters of the list. For all of them, see Listing datastreams in Management API.

The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/datastreams/?tag=prod&tag=daily&tag_match=all' \
--header 'Authorization: Bearer {{KEY}}'

The same query parameters also target the bulk datastream update, the smart schedule update, and the custom monitor assignment requests. For more information, see Managing pulling mode and smart schedule in Management API and Bulk assigning custom monitors in Management API.