openapi: 3.0.1
info:
  title: Miro Developer Platform AI Interaction Logs Code widget items (experimental) 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: Code widget items (experimental)
paths:
  /v2-experimental/boards/{board_id}/code_widgets:
    get:
      description: 'Retrieves a list of code widget items for a specific board.


        This method returns results using a cursor-based approach. A cursor-paginated method returns a portion of the total set of results based on the limit specified and a cursor that points to the next portion of the results. To retrieve the next portion of the collection, on your next call to the same method, set the `cursor` parameter equal to the `cursor` value you received in the response of the previous request.<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 2</a><br/>'
      operationId: get-code-widget-items
      parameters:
      - in: query
        name: limit
        schema:
          type: string
          default: '10'
          description: The maximum number of results to return per call. If the number of items in the response is greater than the limit specified, the response returns the cursor parameter with a value.
          maximum: 50
          minimum: 10
      - in: query
        name: cursor
        schema:
          type: string
          description: A cursor-paginated method returns a portion of the total set of results based on the limit specified and a `cursor` that points to the next portion of the results. To retrieve the next portion of the collection, set the `cursor` parameter equal to the `cursor` value you received in the response of the previous request.
      - description: Unique identifier (ID) of the board for which you want to retrieve the list of code widget items.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeWidgetCursorPaged'
          description: Code widget items retrieved
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error obj
                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
                description: Test error obj
                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
                description: Test error obj
                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 code widget items
      tags:
      - Code widget items (experimental)
    post:
      description: Adds a code widget item to 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: create-code-widget-item
      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/CodeWidgetCreateRequest'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeWidgetItem'
          description: Code widget item created
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error obj
                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
                description: Test error obj
                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
                description: Test error obj
                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 code widget item
      tags:
      - Code widget items (experimental)
  /v2-experimental/boards/{board_id}/code_widgets/{item_id}:
    get:
      description: Retrieves information for a specific code widget 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-code-widget-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/CodeWidgetItem'
          description: Code widget item retrieved
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error obj
                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
                description: Test error obj
                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
                description: Test error obj
                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 code widget item
      tags:
      - Code widget items (experimental)
    patch:
      description: Updates a code widget item on a board based on the data properties provided in the request body.<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-code-widget-item
      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/CodeWidgetUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeWidgetItem'
          description: Code widget item updated
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error obj
                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
                description: Test error obj
                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
                description: Test error obj
                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 code widget item
      tags:
      - Code widget items (experimental)
    delete:
      description: Deletes a code widget 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-code-widget-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: Code widget item deleted
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error obj
                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
                description: Test error obj
                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
                description: Test error obj
                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 code widget item
      tags:
      - Code widget items (experimental)
  /v2-experimental/boards/{board_id}/code_widgets/{item_id}/position:
    patch:
      description: Updates the position of a code widget 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: move-code-widget-item
      parameters:
      - description: Unique identifier (ID) of the board where you want to move the item.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      - description: Unique identifier (ID) of the item that you want to move.
        in: path
        name: item_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PositionChange'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeWidgetItem'
          description: Code widget item moved
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error obj
                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
                description: Test error obj
                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
                description: Test error obj
                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: Move code widget item
      tags:
      - Code widget items (experimental)
components:
  schemas:
    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
    CodeWidgetCreateRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CodeWidgetData'
        position:
          $ref: '#/components/schemas/PositionChange'
        geometry:
          $ref: '#/components/schemas/Geometry'
        parent:
          $ref: '#/components/schemas/Parent'
    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'
    CodeWidgetUpdateRequest:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CodeWidgetData'
        position:
          $ref: '#/components/schemas/PositionChange'
        geometry:
          $ref: '#/components/schemas/Geometry'
        parent:
          $ref: '#/components/schemas/Parent'
    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
    PageLinks:
      type: object
      description: Contains pagination links for the collection.
      properties:
        first:
          type: string
          description: Link to retrieve information in the first page of the collection.
          example: http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1ODc2NaSDN&#RDMDA3MzYyOX==
        last:
          type: string
          description: Link to the retrieve information in the last page of the collection.
          example: http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1ODc2NDUyNDUyMDA3MzYyOX==
        next:
          type: string
          description: Link to retrieve information in the next page of the collection.
          example: http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1ODc2NDUyNDsdgsFEwfFJCw==
        prev:
          type: string
          description: Link to retrieve information in the previous page of the collection.
          example: http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=
        self:
          type: string
          description: Link to retrieve information in the current page of the collection.
          example: http://api.miro.com/v2/boards/o9J_lJWSHdg=/items?limit=10&cursor=MzQ1OD1245643FWUyMDA3MzYyOX==
    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
    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
    CodeWidgetItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier (ID) of an item.
          example: '3458764517517819000'
        data:
          $ref: '#/components/schemas/CodeWidgetData'
        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'
        links:
          $ref: '#/components/schemas/WidgetLinks'
        type:
          type: string
          description: Type of item that is returned.
          example: code
      required:
      - id
      - type
    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
    CodeWidgetCursorPaged:
      type: object
      properties:
        data:
          type: array
          description: Contains the result data.
          items:
            $ref: '#/components/schemas/CodeWidgetItem'
        total:
          type: integer
          format: int64
          description: Total number of results available. If the value of the `total` parameter is higher than the value of the `size` parameter, this means that there are more results that you can retrieve. To retrieve more results, you can make another request and set the `offset` value accordingly.
        size:
          type: integer
          format: int32
          description: Number of results returned in the response considering the `cursor` and the `limit` values sent in the request.
          example: 1
        cursor:
          type: string
          description: A cursor-paginated method returns a portion of the total set of results based on the `limit` specified and a `cursor` that points to the next portion of the results. To retrieve the next set of results of the collection, set the `cursor` parameter in your next request to the value returned in this parameter.
          example: MzQ1ODc2NDUyMjQ5MDA4Mjg5NX4=
        limit:
          type: integer
          format: int32
          description: Maximum number of results returned based on the `limit` specified in the request.
          example: 10
        links:
          $ref: '#/components/schemas/PageLinks'
    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
    CodeWidgetData:
      type: object
      description: Contains the data properties of a code widget item, such as the code content, programming language, and display settings.
      properties:
        code:
          type: string
          description: The code content of the widget.
          maxLength: 6000
          example: console.log("Hello, World!");
        language:
          type: string
          description: The programming language of the code content. Used for syntax highlighting.
          example: javascript
        lineNumbersVisible:
          type: boolean
          description: Indicates whether line numbers are visible in the code widget.
          example: true
        title:
          type: string
          description: The title of the code widget.
          maxLength: 100
          example: My Code Snippet
  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