Custom tags API - POST tags
Add custom tags to the specified monitored entities.
The request consumes and produces an application/json
payload.
POST | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/v2/tags |
SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/tags | |
Environment and Cluster ActiveGate (default port 9999) | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/tags |
Authentication
To execute this request, you need an access token with entities.write
scope.
To learn how to obtain and use it, see Tokens and authentication.
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
entitySelector | string | Specifies the entities where you want to update tags. You must set one of these criteria:
You can add one or more of the following criteria. Values are case-sensitive and the
For more information, see Entity selector in Dynatrace Documentation. To set several criteria, separate them with a comma ( The maximum string length is 2,000 characters. | query | required |
from | string | The start of the requested timeframe. You can use one of the following formats:
If not set, the relative timeframe of 24 hours is used ( | query | optional |
to | string | The end of the requested timeframe. You can use one of the following formats:
If not set, the current timestamp is used. | query | optional |
body | AddEntityTags | The JSON body of the request. Contains tags to be added to the matching entities. | body | optional |
Request body objects
The AddEntityTags
object
A list of tags to be added to monitored entities.
Element | Type | Description | Required |
---|---|---|---|
tags | AddEntityTag[] | A list of tags to be added to monitored entities. | required |
The AddEntityTag
object
The custom tag to be added to monitored entities.
Element | Type | Description | Required |
---|---|---|---|
key | string | The key of the custom tag to be added to monitored entities. | required |
value | string | The value of the custom tag to be added to monitored entities. May be null | optional |
Request body JSON model
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{"tags": [{"key": "mainApp"},{"key": "bookings","value": "42"}]}
Response
Response codes
Code | Type | Description |
---|---|---|
200 | AddedEntityTags | Success |
4XX | ErrorEnvelope | Client side error. |
5XX | ErrorEnvelope | Server side error. |
Response body objects
The AddedEntityTags
object
A list of custom tags added to monitored entities.
Element | Type | Description |
---|---|---|
appliedTags | METag[] | A list of added custom tags. |
matchedEntitiesCount | integer | The number of monitored entities where the tags have been added. |
The METag
object
The tag of a monitored entity.
Element | Type | Description |
---|---|---|
context | string | The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the |
key | string | The key of the tag. |
stringRepresentation | string | The string representation of the tag. |
value | string | The value of the tag. |
Response body JSON model
{"appliedTags": [{"context": "CONTEXTLESS","key": "mainApp","stringRepresentation": "mainApp"},{"context": "CONTEXTLESS","key": "booking","stringRepresentation": "booking"}],"matchedEntitiesCount": 2}
Example
In this example, the request adds the REST-test and RESTexample custom tags to hosts that already have the easyTravel tag. To achieve that, the entitySelector query parameter is set to type("HOST"),tag("easyTravel")
.
The API token is passed in the Authorization header.
Curl
curl -L -X POST 'https://mySampleEnv.live.dynatrace.com/api/v2/tags?entitySelector=type(%22HOST%22),tag(%22easyTravel%22)' \-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \-H 'Content-Type: application/json' \--data-raw '{"tags": [{"key": "REST-test"},{"key": "RESTexample"}]}'
Request URL
https://mySampleEnv.live.dynatrace.com/api/v2/tags?entitySelector=type(%22HOST%22),tag(%22easyTravel%22)
Request body
{"tags": [{"key": "REST-test"},{"key": "RESTexample"}]}
Response body
{"matchedEntitiesCount": 3,"appliedTags": [{"context": "CONTEXTLESS","key": "REST-test","stringRepresentation": "REST-test"},{"context": "CONTEXTLESS","key": "RESTexample","stringRepresentation": "RESTexample"}]}
Response code
200