---
type: api
title: Upsert a tag
description: Updates a tag if it exists, or creates it at the provided ID.
url: https://www.elastic.co/docs/api/doc/kibana/operation/operation-put-tags-id
resource: https://www.elastic.co/docs/api/doc/kibana/operation/operation-put-tags-id
products:
  - Kibana
---

# Upsert a tag

Authentication: required

Availability: Experimental since 9.5

- Server: `https://{kibana_url}`

## Paths

- `PUT` `/api/tags/{id}`
- `PUT` `/s/{space_id}/api/tags/{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](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- `id` (string · min length: 1 · max length: 256) — required
  The tag ID, as returned by the create or search endpoints.

## Description

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

## Header parameters

- `kbn-xsrf` (string) — required
  A required header to protect against CSRF attacks

## Request body

`application/json`

- `color` (string · min length: 1 · max length: 256) — optional
  The tag color as a hex value (e.g. `#772299`). If omitted, a random color is generated.
- `description` (string · max length: 2048) — optional
  Optional description of the tag.
- `name` (string · min length: 1 · max length: 256) — required
  The display name of the tag.

## Responses

#### `200`

updated

`application/json`

- `data` (object)
  - `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)
    The display name of the tag.
- `id` (string)
  The tag ID.
- `meta` (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`

created

`application/json`

- `data` (object)
  - `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)
    The display name of the tag.
- `id` (string)
  The tag ID.
- `meta` (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

## Code examples

#### Console

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

#### curl

```curl
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"
  }'
```

## Response examples

#### The updated tag

`application/json`

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

#### The created tag

`application/json`

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