Elastic Stack (ELK Stack) Tags API

openapi: 3.2.0
info:
  contact:
    name: Kibana Team
  description: The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
  title: Kibana Tags API
  version: ''
  x-doc-license:
    name: Attribution-NonCommercial-NoDerivatives 4.0 International
    url: https://creativecommons.org/licenses/by-nc-nd/4.0/
  x-feedbackLink:
    label: Feedback
    url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
  variables:
    kibana_url:
      default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: Tags
paths:
  /api/tags:
    get:
      description: '**Spaces method and path for this operation:**


        get /s/{space_id}/api/tags


        Refer to Spaces for more information.


        Returns a paginated list of tags matching the optional `query` text.'
      operationId: get-tags
      parameters:
      - description: Filters results by `name` and `description` using Elasticsearch [`simple_query_string`](https://www.elastic.co/docs/reference/query-languages/query-dsl/simple-query-string-query) syntax. Multi-word terms require all words to match.
        in: query
        name: query
        required: false
        schema:
          maxLength: 2048
          type: string
      - description: The page of results to return.
        in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          type: number
      - description: The number of results to return per page.
        in: query
        name: per_page
        required: false
        schema:
          default: 20
          maximum: 1000
          minimum: 1
          type: number
      responses:
        '200':
          content:
            application/json:
              examples:
                searchTagsResponse:
                  summary: Tags matching a search query
                  value:
                    data:
                    - data:
                        color: '#1BA9F5'
                        description: Dashboards owned by engineering teams.
                        name: Engineering
                      id: tag-engineering
                      meta:
                        created_at: '2026-06-01T12:00:00.000Z'
                        managed: false
                        updated_at: '2026-06-01T12:00:00.000Z'
                        version: WzEsMV0=
                    - data:
                        color: '#54B399'
                        description: Content used by operations teams.
                        name: Operations
                      id: tag-operations
                      meta:
                        created_at: '2026-06-02T09:30:00.000Z'
                        managed: false
                        updated_at: '2026-06-02T09:30:00.000Z'
                        version: WzIsMV0=
                    meta:
                      page: 1
                      per_page: 20
                      total: 2
              schema:
                additionalProperties: false
                type: object
                properties:
                  data:
                    description: List of tags matching the query.
                    items:
                      additionalProperties: false
                      type: object
                      properties:
                        data:
                          $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-attributes'
                        id:
                          description: The tag ID.
                          type: string
                        meta:
                          $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-as-code-meta'
                      required:
                      - id
                      - data
                      - meta
                    maxItems: 1000
                    minItems: 0
                    type: array
                  meta:
                    additionalProperties: false
                    type: object
                    properties:
                      page:
                        default: 1
                        description: The returned page of results.
                        minimum: 1
                        type: number
                      per_page:
                        default: 20
                        description: The number of results returned per page.
                        maximum: 1000
                        minimum: 1
                        type: number
                      total:
                        description: The total number of results matching the query.
                        type: number
                    required:
                    - total
                required:
                - data
                - meta
          description: success
        '403':
          description: forbidden
      summary: Search tags
      tags:
      - Tags
      x-state: Experimental; added in 9.5.0
      x-metaTags:
      - content: Kibana
        name: product_name
    post:
      description: '**Spaces method and path for this operation:**


        post /s/{space_id}/api/tags


        Refer to Spaces for more information.


        Creates a new tag and returns it.'
      operationId: post-tags
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      requestBody:
        content:
          application/json:
            examples:
              createTagRequest:
                summary: Create a tag
                value:
                  color: '#F04E98'
                  description: Content related to security investigations.
                  name: Security
            schema:
              $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-request-attributes'
      responses:
        '201':
          content:
            application/json:
              examples:
                createTagResponse:
                  summary: The created tag
                  value:
                    data:
                      color: '#F04E98'
                      description: Content related to security investigations.
                      name: Security
                    id: tag-security
                    meta:
                      created_at: '2026-06-03T14:15:00.000Z'
                      managed: false
                      updated_at: '2026-06-03T14:15:00.000Z'
                      version: WzMsMV0=
              schema:
                additionalProperties: false
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-attributes'
                  id:
                    description: The tag ID.
                    type: string
                  meta:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-as-code-meta'
                required:
                - id
                - data
                - meta
          description: created
        '400':
          description: invalid request
        '403':
          description: forbidden
        '409':
          description: conflict
      summary: Create a tag
      tags:
      - Tags
      x-state: Experimental; added in 9.5.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/tags/{id}:
    delete:
      description: '**Spaces method and path for this operation:**


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


        Refer to Spaces for more information.


        Permanently deletes a tag by ID.'
      operationId: delete-tags-id
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The tag ID, as returned by the create or search endpoints.
        in: path
        name: id
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      responses:
        '204':
          description: deleted
        '403':
          description: forbidden
        '404':
          description: not found
      summary: Delete a tag
      tags:
      - Tags
      x-state: Experimental; added in 9.5.0
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: '**Spaces method and path for this operation:**


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


        Refer to Spaces for more information.


        Returns a tag by ID.'
      operationId: get-tags-id
      parameters:
      - description: The tag ID, as returned by the create or search endpoints.
        in: path
        name: id
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                readTagResponse:
                  summary: The requested tag
                  value:
                    data:
                      color: '#1BA9F5'
                      description: Dashboards owned by engineering teams.
                      name: Engineering
                    id: tag-engineering
                    meta:
                      created_at: '2026-06-01T12:00:00.000Z'
                      managed: false
                      updated_at: '2026-06-01T12:00:00.000Z'
                      version: WzEsMV0=
              schema:
                additionalProperties: false
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-attributes'
                  id:
                    description: The tag ID.
                    type: string
                  meta:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-as-code-meta'
                required:
                - id
                - data
                - meta
          description: success
        '403':
          description: forbidden
        '404':
          description: not found
      summary: Get a tag
      tags:
      - Tags
      x-state: Experimental; added in 9.5.0
      x-metaTags:
      - content: Kibana
        name: product_name
    put:
      description: '**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.'
      operationId: put-tags-id
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The tag ID, as returned by the create or search endpoints.
        in: path
        name: id
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      requestBody:
        content:
          application/json:
            examples:
              upsertTagRequest:
                summary: Update or create a tag
                value:
                  color: '#006BB4'
                  description: Dashboards and visualizations owned by engineering teams.
                  name: Engineering
            schema:
              $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-request-attributes'
      responses:
        '200':
          content:
            application/json:
              examples:
                updateTagResponse:
                  summary: The updated tag
                  value:
                    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=
              schema:
                additionalProperties: false
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-attributes'
                  id:
                    description: The tag ID.
                    type: string
                  meta:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-as-code-meta'
                required:
                - id
                - data
                - meta
          description: updated
        '201':
          content:
            application/json:
              examples:
                upsertTagCreatedResponse:
                  summary: The created tag
                  value:
                    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=
              schema:
                additionalProperties: false
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-tags-attributes'
                  id:
                    description: The tag ID.
                    type: string
                  meta:
                    $ref: '#/components/schemas/Kibana_HTTP_APIs_kbn-as-code-meta'
                required:
                - id
                - data
                - meta
          description: created
        '400':
          description: invalid request
        '403':
          description: forbidden
        '409':
          description: conflict
      summary: Upsert a tag
      tags:
      - Tags
      x-state: Experimental; added in 9.5.0
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  schemas:
    Kibana_HTTP_APIs_kbn-as-code-meta:
      additionalProperties: false
      type: object
      properties:
        created_at:
          description: Timestamp when the object was created (ISO 8601).
          type: string
        created_by:
          description: User profile ID of the user who created the object.
          type: string
        managed:
          description: When `true`, the object is managed by Kibana and cannot be edited by users.
          type: boolean
        owner:
          description: Identifier of the plugin or team that owns this object.
          type: string
        updated_at:
          description: Timestamp when the object was last updated (ISO 8601).
          type: string
        updated_by:
          description: User profile ID of the user who last updated the object.
          type: string
        version:
          description: Internal version identifier for optimistic concurrency control.
          type: string
    Kibana_HTTP_APIs_kbn-tags-request-attributes:
      additionalProperties: false
      type: object
      properties:
        color:
          description: The tag color as a hex value (e.g. `#772299`). If omitted, a random color is generated.
          maxLength: 256
          minLength: 1
          type: string
        description:
          description: Optional description of the tag.
          maxLength: 2048
          type: string
        name:
          description: The display name of the tag.
          maxLength: 256
          minLength: 1
          type: string
      required:
      - name
    Kibana_HTTP_APIs_kbn-tags-attributes:
      additionalProperties: false
      type: object
      properties:
        color:
          description: The tag color as a hex value (e.g. `#772299`). If omitted, a random color is generated.
          maxLength: 256
          minLength: 1
          type: string
        description:
          description: Optional description of the tag.
          maxLength: 2048
          type: string
        name:
          description: The display name of the tag.
          maxLength: 256
          minLength: 1
          type: string
      required:
      - name
      - color
  securitySchemes:
    apiKeyAuth:
      description: 'These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`

        '
      in: header
      name: Authorization
      type: apiKey
    basicAuth:
      scheme: basic
      type: http
x-topics:
- title: Kibana spaces
  content: "Spaces enable you to organize your dashboards and other saved objects into meaningful categories.\nYou can use the default space or create your own spaces.\n\nTo run APIs in non-default spaces, you must add `s/{space_id}/` to the path.\nFor example:\n\n```bash\ncurl -X GET \"http://${KIBANA_URL}/s/marketing/api/data_views\" \\\n  -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nIf you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.\n\nTo learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).\n"