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 ActiveGate | https://{your-activegate-domain}/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 | Add | 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 | Add | 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 | Added | Success |
Response body objects
The AddedEntityTags
object
A list of custom tags added to monitored entities.
Element | Type | Description |
---|---|---|
appliedTags | M | 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