Miro Flowchart shapes (experimental) API

openapi: 3.0.1
info:
  title: Miro Developer Platform AI Interaction Logs Flowchart shapes (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: Flowchart shapes (experimental)
paths:
  /v2-experimental/boards/{board_id}/items:
    get:
      description: 'Retrieves a list of items for a specific board. You can retrieve all items on the board, a list of child items inside a parent item, or a list of specific types of items by specifying URL query parameter values.


        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. For example, if you set the `limit` query parameter to `10` and the board contains 20 objects, the first call will return information about the first 10 objects in the response along with a cursor parameter and value. In this example, let''s say the cursor parameter value returned in the response is `foo`. If you want to retrieve the next set of objects, on your next call to the same method, set the cursor parameter value to `foo`.<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-items-experimental
      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: type
        schema:
          type: string
          enum:
          - shape
      - 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 available items.
        in: path
        name: board_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericItemCursorPaged'
          description: 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 items on board
      tags:
      - Flowchart shapes (experimental)
  /v2-experimental/boards/{board_id}/items/{item_id}:
    get:
      description: Retrieves information for a specific 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-specific-item-experimental
      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/GenericItem'
          description: 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 specific item on board
      tags:
      - Flowchart shapes (experimental)
  /v2-experimental/boards/{board_id}/shapes:
    post:
      description: Adds a flowchart shape 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-shape-item-flowchart
      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/ShapeCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeItem'
          description: Shape 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 shape item
      tags:
      - Flowchart shapes (experimental)
  /v2-experimental/boards/{board_id}/shapes/{item_id}:
    get:
      description: Retrieves information for a specific shape 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-shape-item-flowchart
      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/ShapeItem'
          description: Shape 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 shape item
      tags:
      - Flowchart shapes (experimental)
    patch:
      description: Updates a flowchart shape item on a board based on the data and style 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-shape-item-flowchart
      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/ShapeUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeItem'
          description: Shape 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 shape item
      tags:
      - Flowchart shapes (experimental)
    delete:
      description: Deletes a flowchart shape 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-shape-item-flowchart
      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: Shape 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 shape item
      tags:
      - Flowchart shapes (experimental)
components:
  schemas:
    FrameData:
      type: object
      description: Contains frame item data, such as the title, frame type, or frame format.
      properties:
        format:
          type: string
          default: custom
          description: Only custom frames are supported at the moment.
          enum:
          - custom
          - desktop
          - phone
          - tablet
          - a4
          - letter
          - ratio_1x1
          - ratio_4x3
          - ratio_16x9
        title:
          type: string
          description: Title of the frame. This title appears at the top of the frame.
          example: Sample frame title
        type:
          type: string
          default: freeform
          description: Only free form frames are supported at the moment.
          enum:
          - freeform
          - heap
          - grid
          - rows
          - columns
    AppCardData:
      type: object
      description: Contains app card item data, such as the title, description, or fields.
      properties:
        description:
          type: string
          description: A short text description to add context about the app card.
          example: Sample app card description
        fields:
          type: array
          description: Array where each object represents a custom preview field. Preview fields are displayed on the bottom half of the app card in the compact view.
          items:
            $ref: '#/components/schemas/CustomField'
        owned:
          type: boolean
          description: Defines whether the card is owned by the application making the call.
        status:
          type: string
          description: Status indicating whether an app card is connected and in sync with the source. When the source for the app card is deleted, the status returns `disabled`.
          enum:
          - disconnected
          - connected
          - disabled
        title:
          type: string
          description: A short text header to identify the app card.
          example: sample app card item
    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
    ShapeDataForCreate:
      type: object
      description: Contains shape item data, such as the content or the type of the shape.
      properties:
        content:
          type: string
          description: "The text you want to display on the shape.\n<br>**Not supported for shapes:**\n<ul>\n  <li>flow_chart_or</li>\n  <li>flow_chart_summing_junction</li>\n</ul>"
          example: Hello
        shape:
          type: string
          default: rectangle
          description: "Defines the geometric shape of the item when it is rendered on the board. <details>\n  <summary>Basic shapes</summary>\n  <ul>\n    <li>rectangle</li>\n    <li>round_rectangle</li>\n    <li>circle</li>\n    <li>triangle</li>\n    <li>rhombus</li>\n    <li>parallelogram</li>\n    <li>trapezoid</li>\n    <li>pentagon</li>\n    <li>hexagon</li>\n    <li>octagon</li>\n    <li>wedge_round_rectangle_callout</li>\n    <li>star</li>\n    <li>flow_chart_predefined_process</li>\n    <li>cloud</li>\n    <li>cross</li>\n    <li>can</li>\n    <li>right_arrow</li>\n    <li>left_arrow</li>\n    <li>left_right_arrow</li>\n    <li>left_brace</li>\n    <li>right_brace</li>\n  </ul>\n</details>\n<details>\n  <summary>Flowchart shapes</summary>\n  <ul>\n    <li>flow_chart_connector</li>\n    <li>flow_chart_magnetic_disk</li>\n    <li>flow_chart_input_output</li>\n    <li>flow_chart_decision</li>\n    <li>flow_chart_delay</li>\n    <li>flow_chart_display</li>\n    <li>flow_chart_document</li>\n    <li>flow_chart_magnetic_drum</li>\n    <li>flow_chart_internal_storage</li>\n    <li>flow_chart_manual_input</li>\n    <li>flow_chart_manual_operation</li>\n    <li>flow_chart_merge</li>\n    <li>flow_chart_multidocuments</li>\n    <li>flow_chart_note_curly_left</li>\n    <li>flow_chart_note_curly_right</li>\n    <li>flow_chart_note_square</li>\n    <li>flow_chart_offpage_connector</li>\n    <li>flow_chart_or</li>\n    <li>flow_chart_predefined_process_2</li>\n    <li>flow_chart_preparation</li>\n    <li>flow_chart_process</li>\n    <li>flow_chart_online_storage</li>\n    <li>flow_chart_summing_junction</li>\n    <li>flow_chart_terminator</li>\n  </ul>\n</details>"
    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
    ShapeStyleForCreate:
      type: object
      description: "Contains information about the shape style, such as the border color or opacity. <br> All properties in style object are supported for shape types aren't listed below. <br> <table>\n  <tr>\n    <th align=\"left\">Shape type</th>\n    <th align=\"left\">Unsupported properties</th>\n  </tr>\n  <tr>\n    <td>flow_chart_or</td>\n    <td>fontSize, fontFamily, color, textAlign, textAlignVertical</td>\n  </tr>\n  <tr>\n    <td>flow_chart_summing_junction</td>\n    <td>fontSize, fontFamily, color, textAlign, textAlignVertical</td>\n  </tr>\n  <tr>\n    <td>flow_chart_note_curly_left</td>\n    <td>fillColor, fillOpacity</td>\n  </tr>\n  <tr>\n    <td>flow_chart_note_curly_right</td>\n    <td>fillColor, fillOpacity</td>\n  </tr>\n  <tr>\n    <td>flow_chart_note_square</td>\n    <td>fillColor, fillOpacity</td>\n  </tr>\n</table>"
      properties:
        borderColor:
          type: string
          description: 'Defines the color of the border of the shape.

            Default: `#1a1a1a` (dark gray).'
        borderOpacity:
          type: string
          description: 'Defines the opacity level of the shape border.

            Possible values: any number between `0.0` and `1.0`, where:

            `0.0`: the background color is completely transparent or invisible

            `1.0`: the background color is completely opaque or solid

            Default: `1.0` (solid color).'
          maximum: 1
          minimum: 0
        borderStyle:
          type: string
          description: 'Defines the style used to represent the border of the shape.

            Default: `normal`.'
          enum:
          - normal
          - dotted
          - dashed
        borderWidth:
          type: string
          description: 'Defines the thickness of the shap

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