Upsert a tag

Base URL: https://{kibana_url}

PUT /api/tags/{id}
PUT /s/{space_id}/api/tags/{id}

Auth

Updates a tag if it exists, or creates it at the provided ID.

Path parameters

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.

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

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.

Responses

updated

application/json

data object required
id string required: The tag ID.
meta object required

created

application/json

400

invalid request

403

forbidden

409

conflict

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/tags/ID
{
  "color": "#006BB4",
  "description": "Dashboards and visualizations owned by engineering teams.",
  "name": "Engineering"
}

Generated from the API spec

curl Shell

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

{
  "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="
  }
}

{
  "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="
  }
}