openapi: 3.0.1
info:
  title: Miro Developer Platform AI Interaction Logs Document items 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: Document items
paths:
  /v2/boards/{board_id}/documents:
    post:
      description: Adds a document item to a board by specifying the URL where the document is hosted.<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 2</a><br/>
      operationId: create-document-item-using-url
      parameters:
      - description: Unique identifier (ID) of the board where you want to create the item.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentItem'
          description: Document item created
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      summary: Create document item using URL
      tags:
      - Document items
  /v2/boards/{board_id}/documents/{item_id}:
    get:
      description: Retrieves information for a specific document item on a 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-document-item
      parameters:
      - description: Unique identifier (ID) of the board from which you want to retrieve a specific item.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the item that you want to retrieve.
        in: path
        name: item_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentItem'
          description: Document item retrieved
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      summary: Get document item
      tags:
      - Document items
    patch:
      description: Updates a document item 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 2</a><br/>
      operationId: update-document-item-using-url
      parameters:
      - description: Unique identifier (ID) of the board where you want to update the item.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the item that you want to update.
        in: path
        name: item_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentItem'
          description: Document item updated
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
      summary: Update document item using URL
      tags:
      - Document items
    delete:
      description: Deletes a document item from the 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 3</a><br/>
      operationId: delete-document-item
      parameters:
      - description: Unique identifier (ID) of the board from which you want to delete the item.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the item that you want to delete.
        in: path
        name: item_id
        required: true
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
          description: Document item deleted
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      summary: Delete document item
      tags:
      - Document items
components:
  schemas:
    DocumentUpdateRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DocumentUrlDataChanges'
        position:
          $ref: '#/components/schemas/PositionChange'
        geometry:
          $ref: '#/components/schemas/FixedRatioGeometry'
        parent:
          $ref: '#/components/schemas/Parent'
    Geometry:
      type: object
      description: Contains geometrical information about the item, such as its width or height.
      properties:
        height:
          type: number
          format: double
          description: Height of the item, in pixels.
          example: 60
        rotation:
          type: number
          format: double
          description: Rotation angle of an item, in degrees, relative to the board. You can rotate items clockwise (right) and counterclockwise (left) by specifying positive and negative values, respectively.
        width:
          type: number
          format: double
          description: Width of the item, in pixels.
          example: 320
    DocumentUrlDataChanges:
      type: object
      description: Contains information about the document URL.
      properties:
        title:
          type: string
          description: A short text header to identify the document.
        url:
          type: string
          description: URL where the document is hosted.
          example: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
    DocumentItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier (ID) of an item.
          example: '3458764517517819000'
        data:
          $ref: '#/components/schemas/DocumentData'
        position:
          $ref: '#/components/schemas/Position'
        geometry:
          $ref: '#/components/schemas/Geometry'
        createdAt:
          type: string
          format: date-time
          description: 'Date and time when the item was created. <br>Format: UTC, adheres to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), includes a [trailing Z offset](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)).'
          example: '2022-03-30T17:26:50.000Z'
        createdBy:
          $ref: '#/components/schemas/createdBy'
        modifiedAt:
          type: string
          format: date-time
          description: 'Date and time when the item was last modified. <br>Format: UTC, adheres to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), includes a [trailing Z offset](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)).'
          example: '2022-03-30T17:26:50.000Z'
        modifiedBy:
          $ref: '#/components/schemas/modifiedBy'
        parent:
          $ref: '#/components/schemas/ParentLinksEnvelope'
        links:
          $ref: '#/components/schemas/WidgetLinks'
        type:
          type: string
          description: Type of item that is returned.
          example: document
      required:
      - id
      - type
    DocumentCreateRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DocumentUrlData'
        position:
          $ref: '#/components/schemas/PositionChange'
        parent:
          $ref: '#/components/schemas/Parent'
      required:
      - data
    Parent:
      type: object
      description: Contains information about the parent frame for the item.
      properties:
        id:
          type: string
          format: int64
          description: Unique identifier (ID) of the parent frame for the item.
          example: '3074457362577955300'
    DocumentUrlData:
      type: object
      description: Contains information about the document URL.
      properties:
        title:
          type: string
          description: A short text header to identify the document.
          example: Sample document title
        url:
          type: string
          default: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
          description: URL where the document is hosted.
          example: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
      required:
      - url
    DocumentData:
      type: object
      properties:
        documentUrl:
          type: string
          description: 'The URL to download the resource. You must use your access token to access the URL. The URL contains the `redirect` parameter to control the request execution.

            `redirect`: By default, the `redirect` parameter is set to `false` and the resource object containing the URL and the resource type is returned with a 200 OK HTTP code. This URL is valid for 60 seconds. You can use this URL to retrieve the resource file.

            If the `redirect` parameter is set to `true`, a 307 TEMPORARY_REDIRECT HTTP response is returned. If you follow HTTP 3xx responses as redirects, you will automatically be redirected to the resource file and the content type returned is `application/octet-stream`.'
          example: https://api.miro.com/v2/boards/uXjVOfjkmAk=/resources/98765467890987654?redirect=false
        title:
          type: string
          description: A short text header to identify the document.
          example: Sample document title
    SelfLink:
      type: object
      description: Contains applicable links for the current object.
      properties:
        self:
          type: string
          description: Link to obtain more information about the current object.
          example: http://api.miro.com/v2/boards/o9J_koQspF4=/object_type/3074457349143649487
    PositionChange:
      type: object
      description: Contains information about the item's position on the board, such as its `x` coordinate, `y` coordinate, and the origin of the `x` and `y` coordinates.
      properties:
        x:
          type: number
          format: double
          description: 'X-axis coordinate of the location of the item on the board.

            By default, all items have absolute positioning to the board, not the current viewport. Default: `0`.

            The center point of the board has `x: 0` and `y: 0` coordinates.'
          default: 0
          example: 100
        y:
          type: number
          format: double
          description: 'Y-axis coordinate of the location of the item on the board.

            By default, all items have absolute positioning to the board, not the current viewport. Default: `0`.

            The center point of the board has `x: 0` and `y: 0` coordinates.'
          default: 0
          example: 100
    Position:
      type: object
      description: Contains location information about the item, such as its x coordinate, y coordinate, and the origin of the x and y coordinates.
      properties:
        origin:
          type: string
          default: center
          description: 'Area of the item that is referenced by its x and y coordinates. For example, an item with a center origin will have its x and y coordinates point to its center. The center point of the board has x: 0 and y: 0 coordinates.

            Currently, only one option is supported.'
          enum:
          - center
        relativeTo:
          type: string
          enum:
          - canvas_center
          - parent_top_left
        x:
          type: number
          format: double
          description: 'X-axis coordinate of the location of the item on the board.

            By default, all items have absolute positioning to the board, not the current viewport. Default: 0.

            The center point of the board has `x: 0` and `y: 0` coordinates.'
          example: 100
        y:
          type: number
          format: double
          description: 'Y-axis coordinate of the location of the item on the board.

            By default, all items have absolute positioning to the board, not the current viewport. Default: 0.

            The center point of the board has `x: 0` and `y: 0` coordinates.'
          example: 100
    FixedRatioGeometry:
      type: object
      description: Contains geometrical information about the item, such as its width or rotation. You can set either the width or height, you cannot set both the width and height at the same time.
      properties:
        height:
          type: number
          format: double
          description: Height of the item, in pixels.
        width:
          type: number
          format: double
          description: Width of the item, in pixels.
        rotation:
          type: number
          format: double
          description: Rotation angle of an item, in degrees, relative to the board. You can rotate items clockwise (right) and counterclockwise (left) by specifying positive and negative values, respectively.
    WidgetLinks:
      type: object
      description: Contains applicable links for the item.
      properties:
        related:
          type: string
          description: Link to obtain information about the child items related to the frame.
          example: http://api.miro.com/v2/boards/o9J_koQspF4=/items?parent_item_id=307445734914369434&limit=10&cursor=
        self:
          type: string
          description: Link to obtain information about the current item.
          example: http://api.miro.com/v2/boards/o9J_koQspF4=/item/3074457349143649487
    createdBy:
      type: object
      description: Contains information about the user who created the item.
      properties:
        id:
          type: string
          description: Unique identifier (ID) of the user.
          example: '3458764517517852417'
        type:
          type: string
          description: Indicates the type of object returned. In this case, `type` returns `user`.
          example: user
    ParentLinksEnvelope:
      type: object
      description: Contains information about the parent frame for the item.
      properties:
        id:
          type: string
          format: int64
          description: Unique identifier (ID) of the parent frame for the item.
          example: '3074457362577955300'
        links:
          $ref: '#/components/schemas/SelfLink'
    modifiedBy:
      type: object
      description: Contains information about the user who last modified the item.
      properties:
        id:
          type: string
          description: Unique identifier (ID) of the user.
          example: '3458764517517852417'
        type:
          type: string
          description: Indicates the type of object returned. In this case, `type` returns `user`.
          example: user
  securitySchemes:
    oAuth2AuthCode:
      type: oauth2
      description: For more information, see https://developers.miro.com/reference/authorization-flow-for-expiring-tokens
      flows:
        authorizationCode:
          authorizationUrl: https://miro.com/oauth/authorize
          tokenUrl: https://api.miro.com/v1/oauth/token
          scopes:
            boards:read: Retrieve information about boards, board members, or items
            boards:write: Create, update, or delete boards, board members, or items
            microphone:listen: Access a user's microphone to record audio in an iFrame
            screen:record: Access a user's screen to record it in an iFrame
            webcam:record: Allows an iFrame to access a user's camera to record video
            organizations:read: Read information about the organization, such as name, plan, number of licenses, organization settings, or organization members.
            organizations:teams:read: Read team information, such as the list of teams, team settings, team members, for an organization.
            organizations:teams:write: Create or delete teams, update team information, team settings, team members, for an organization.
x-settings:
  publish: true