Upsert a tag Experimental; added in 9.5.0

PUT /api/tags/{id}
Api key auth Basic auth

Spaces method and path for this operation:

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

Refer to Spaces for more information.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The tag ID, as returned by the create or search endpoints.

application/json

Body

  • color string

    The tag color as a hex value (e.g. #772299). If omitted, a random color is generated.

  • description string

    Optional description of the tag.

  • name string Required

    The display name of the tag.

Responses

  • 200 application/json

    updated

    Hide response attributes Show response attributes object
    • data object Required

      Additional properties are NOT allowed.

      Hide data attributes Show data attributes object
      • color string Required

        The tag color as a hex value (e.g. #772299). If omitted, a random color is generated.

      • description string

        Optional description of the tag.

      • name string Required

        The display name of the tag.

    • id string Required

      The tag ID.

    • meta object Required

      Additional properties are NOT allowed.

      Hide meta attributes Show meta attributes object
      • created_at string

        Timestamp when the object was created (ISO 8601).

      • created_by string

        User profile ID of the user who created the object.

      • managed boolean

        When true, the object is managed by Kibana and cannot be edited by users.

      • owner string

        Identifier of the plugin or team that owns this object.

      • updated_at string

        Timestamp when the object was last updated (ISO 8601).

      • updated_by string

        User profile ID of the user who last updated the object.

      • version string

        Internal version identifier for optimistic concurrency control.
  • 201 application/json

    created

    Hide response attributes Show response attributes object
    • data object Required

      Additional properties are NOT allowed.

      Hide data attributes Show data attributes object
      • color string Required

        The tag color as a hex value (e.g. #772299). If omitted, a random color is generated.

      • description string

        Optional description of the tag.

      • name string Required

        The display name of the tag.

    • id string Required

      The tag ID.

    • meta object Required

      Additional properties are NOT allowed.

      Hide meta attributes Show meta attributes object
      • created_at string

        Timestamp when the object was created (ISO 8601).

      • created_by string

        User profile ID of the user who created the object.

      • managed boolean

        When true, the object is managed by Kibana and cannot be edited by users.

      • owner string

        Identifier of the plugin or team that owns this object.

      • updated_at string

        Timestamp when the object was last updated (ISO 8601).

      • updated_by string

        User profile ID of the user who last updated the object.

      • version string

        Internal version identifier for optimistic concurrency control.
  • 400

    invalid request

  • 403

    forbidden

  • 409

    conflict

PUT /api/tags/{id} 
curl \
 --request PUT 'https://localhost:5601/api/tags/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"color":"#006BB4","description":"Dashboards and visualizations owned by engineering teams.","name":"Engineering"}'
Request example 
{
  "color": "#006BB4",
  "description": "Dashboards and visualizations owned by engineering teams.",
  "name": "Engineering"
}
Response examples (200) 
{
  "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="
  }
}
Response examples (201) 
{
  "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="
  }
}