Miro tags API

openapi: 3.0.1
info:
  title: Miro Developer Platform AI Interaction Logs tags API
  version: v2.0
  description: '<img src="https://content.pstmn.io/47449ea6-0ef7-4af2-bac1-e58a70e61c58/aW1hZ2UucG5n" width="1685" height="593">


    ### Miro Developer Platform concepts


    - New to the Miro Developer Platform? Interested in learning more about platform concepts??

    [Read our introduction page](https://beta.developers.miro.com/docs/introduction) and familiarize yourself with the Miro Developer Platform capabilities in a few minutes.



    ### Getting started with the Miro REST API


    - [Quickstart (video):](https://beta.developers.miro.com/docs/try-out-the-rest-api-in-less-than-3-minutes) try the REST API in less than 3 minutes.

    - [Quickstart (article):](https://beta.developers.miro.com/docs/build-your-first-hello-world-app-1) get started and try the REST API in less than 3 minutes.



    ### Miro REST API tutorials


    Check out our how-to articles with step-by-step instructions and code examples so you can:


    - [Get started with OAuth 2.0 and Miro](https://beta.developers.miro.com/docs/getting-started-with-oauth)



    ### Miro App Examples


    Clone our [Miro App Examples repository](https://github.com/miroapp/app-examples) to get inspiration, customize, and explore apps built on top of Miro''s Developer Platform 2.0.

    '
servers:
- url: https://api.miro.com/
tags:
- name: tags
paths:
  /v2/boards/{board_id}/items/{item_id}/tags:
    get:
      description: Retrieves all the tags from the specified item.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:read</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>
      operationId: get-tags-from-item
      parameters:
      - description: Unique identifier (ID) of the board with the item whose tags you want to retrieve.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the item whose tags you want to retrieve.
        in: path
        name: item_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTagsResponse'
          description: Get tags from an item
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Get tags from item
      tags:
      - tags
  /v2/boards/{board_id}/tags:
    post:
      description: Creates a tag on a board.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>
      operationId: create-tag
      parameters:
      - description: Unique identifier (ID) of the board where you want to create the tag.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagWithLinks'
          description: Tag created
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Create tag
      tags:
      - tags
    get:
      description: Retrieves all the tags from the specified board.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:read</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>
      operationId: get-tags-from-board
      parameters:
      - in: query
        name: limit
        schema:
          type: string
          description: 'The maximum number of items that can be returned for a single request.

            Default: `20`.'
          maximum: 50
          minimum: 1
      - in: query
        name: offset
        schema:
          type: string
          description: 'The displacement of the first item in the collection to return.

            Default: `0`.'
      - description: Unique identifier (ID) of the board whose tags you want to retrieve.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsPagedResponse'
          description: Board tags retrieved
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Get tags from board
      tags:
      - tags
  /v2/boards/{board_id}/tags/{tag_id}:
    get:
      description: Retrieves information for a specific tag.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>
      operationId: get-tag
      parameters:
      - description: Unique identifier (ID) of the board where you want to retrieve a specific tag.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the tag that you want to retrieve.
        in: path
        name: tag_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagWithLinks'
          description: Tag retrieved by id
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Get tag
      tags:
      - tags
    patch:
      description: 'Updates a tag based on the data properties provided in the request body. <br><blockquote><strong>Note:</strong> Updates to tags made via the REST API  will not be reflected on the board in realtime. To see REST API updates to tags on a board,  you need to refresh the board. This applies to the following endpoints:  [Attach tag to item](https://developers.miro.com/reference/attach-tag-to-item),  [Remove tag from item](https://developers.miro.com/reference/remove-tag-from-item),   [Delete tag](https://developers.miro.com/reference/delete-tag).</blockquote><br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>'
      operationId: update-tag
      parameters:
      - description: Unique identifier (ID) of the board where you want to update a specific tag.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the tag that you want to update.
        in: path
        name: tag_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagWithLinks'
          description: Tag updated
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Update tag
      tags:
      - tags
    delete:
      description: 'Deletes the specified tag from the board. The tag is also removed from all cards and sticky notes on the board. <br><blockquote><strong>Note:</strong> Updates to tags made via the REST API  will not be reflected on the board in realtime. To see REST API updates to tags on a board,  you need to refresh the board. This applies to the following endpoints:  [Attach tag to item](https://developers.miro.com/reference/attach-tag-to-item),  [Remove tag from item](https://developers.miro.com/reference/remove-tag-from-item),  [Update tag](https://developers.miro.com/reference/update-tag).</blockquote><br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>'
      operationId: delete-tag
      parameters:
      - description: Unique identifier (ID) of the board where you want to delete a specific tag.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the tag that you want to delete.
        in: path
        name: tag_id
        required: true
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
          description: Tag deleted
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Delete tag
      tags:
      - tags
  /v2/boards/{board_id_PlatformTags}/items:
    get:
      description: Retrieves all the items that have the specified tag.<br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:read</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>
      operationId: get-items-by-tag
      parameters:
      - in: query
        name: limit
        schema:
          type: string
          description: 'The maximum number of items that can be returned for a single request.

            Default: `20`.'
          maximum: 50
          minimum: 1
      - in: query
        name: offset
        schema:
          type: string
          description: 'The displacement of the first item in the collection to return.

            Default: `0`.'
      - description: Unique identifier (ID) of the board where you want to retrieve a specific tag.
        in: path
        name: board_id_PlatformTags
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the tag that you want to retrieve.
        in: query
        name: tag_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemPagedResponse'
          description: Item with certain tag
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Get items by tag
      tags:
      - tags
  /v2/boards/{board_id_PlatformTags}/items/{item_id}:
    post:
      description: 'Attach an existing tag to the specified item. Card and sticky note items can have up to 8 tags. <br><blockquote><strong>Note:</strong> Updates to tags made via the REST API  will not be reflected on the board in realtime. To see REST API updates to tags on a board,  you need to refresh the board. This applies to the following endpoints:   [Remove tag from item](https://developers.miro.com/reference/remove-tag-from-item),  [Update tag](https://developers.miro.com/reference/update-tag),  [Delete tag](https://developers.miro.com/reference/delete-tag).</blockquote><br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>'
      operationId: attach-tag-to-item
      parameters:
      - description: Unique identifier (ID) of the board with the item that you want to add a tag to.
        in: path
        name: board_id_PlatformTags
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the item to which you want to add a tag.
        in: path
        name: item_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the tag you want to add to the item.
        in: query
        name: tag_id
        required: true
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
          description: Add a tag to an item
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Malformed request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Code of the error
                    example: error
                  message:
                    type: string
                    description: Description of the error
                    example: Error message
                  status:
                    type: integer
                    format: int32
                    description: Status code of the error
                    example: 400
                  type:
                    type: string
                    description: Type of the error
                    example: error
          description: Too many requests
      summary: Attach tag to item
      tags:
      - tags
    delete:
      description: 'Removes the specified tag from the specified item. The tag still exists on the board. <br><blockquote><strong>Note:</strong> Updates to tags made via the REST API  will not be reflected on the board in realtime. To see REST API updates to tags on a board,  you need to refresh the board. This applies to the following endpoints:  [Attach tag to item](https://developers.miro.com/reference/attach-tag-to-item),   [Update tag](https://developers.miro.com/reference/update-tag),  [Delete tag](https://developers.miro.com/reference/delete-tag).</blockquote><br/><h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>boards:write</a> <br/><h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/>'
      operationId: remove-tag-from-item
      parameters:
      - description: Unique identifier (ID) of the board with the item that you want to remove a tag from.
        in: path
        name: board_id_PlatformTags
        required: true
        schema:
          type: string
  

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/miro/refs/heads/main/openapi/miro-tags-api-openapi.yml