Upsert a tag
Base URL
https://{kibana_url}
Auth
Stack
Experimental
The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.
Availability
Experimental
This functionality is experimental and is not ready for production usage. Experimental features may change or be removed at any time. Elastic will work to fix any issues, but experimental features are not subject to the support SLA of official GA features. Specific Support terms apply.
Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.
This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
Updates a tag if it exists, or creates it at the provided ID.
Expand all
space_id
string optional
An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
id
string · min length: 1 · max length: 256 required
The tag ID, as returned by the create or search endpoints.
A required header to protect against CSRF attacks
{
}
color
string · min length: 1 · max length: 256
The tag color as a hex value (e.g. #772299). If omitted, a random color is generated.
description
string · max length: 2048
Optional description of the tag.
name
string · min length: 1 · max length: 256 required
The display name of the tag.
data
object required
−
Hide 3 properties
color
string · min length: 1 · max length: 256 required
The tag color as a hex value (e.g. #772299). If omitted, a random color is generated.
description
string · max length: 2048
Optional description of the tag.
name
string · min length: 1 · max length: 256 required
The display name of the tag.
id
string required
The tag ID.
meta
object required
−
Hide 7 properties
data
object required
−
Hide 3 properties
color
string · min length: 1 · max length: 256 required
The tag color as a hex value (e.g. #772299). If omitted, a random color is generated.
description
string · max length: 2048
Optional description of the tag.
name
string · min length: 1 · max length: 256 required
The display name of the tag.
id
string required
The tag ID.
meta
object required
−
Hide 7 properties
Thank you for your feedback.
Base URL
https://{kibana_url}
Examples
Request
Console
1 / 2 languages
‹
›
1
2
3
4
5
6
PUT kbn:/api/tags/ID
{
"color": "#006BB4",
"description": "Dashboards and visualizations owned by engineering teams.",
"name": "Engineering"
}
Generated from the API spec
1
2
3
4
5
6
7
8
9
curl -X PUT "${KIBANA_URL}/api/tags/${ID}" \
-H "kbn-xsrf: true" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"color": "#006BB4",
"description": "Dashboards and visualizations owned by engineering teams.",
"name": "Engineering"
}'
Generated from the API spec
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"data": {
"color": "#006BB4",
"description": "Dashboards and visualizations owned by engineering teams.",
"name": "Engineering"
},
"id": "tag-engineering",
"meta": {
"created_at": "2026-06-01T12:00:00.000Z",
"managed": false,
"updated_at": "2026-06-05T16:45:00.000Z",
"version": "WzEsMl0="
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"data": {
"color": "#9170B8",
"description": "Content used for compliance reporting.",
"name": "Compliance"
},
"id": "tag-compliance",
"meta": {
"created_at": "2026-06-06T10:20:00.000Z",
"managed": false,
"updated_at": "2026-06-06T10:20:00.000Z",
"version": "WzQsMV0="
}
}