Miro groups API

openapi: 3.0.1
info:
  title: Miro Developer Platform AI Interaction Logs groups 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: groups
paths:
  /v2/boards/{board_id}/groups:
    post:
      description: Creates a group of items on a board. The group is created with the items that are passed 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: createGroup
      summary: Create group
      parameters:
      - in: path
        name: board_id
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponseShort'
          description: Group 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: 404
                  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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
    get:
      description: Returns all the groups and the items of the respective groups within a specific board.<br/> 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/> For example, if you set the `limit` query parameter to `10` and the board  contains 20 items that are a part of a group, the first call will return information about the first 10 items 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-all-groups
      summary: Get all groups on a board
      parameters:
      - in: path
        name: board_id
        description: Unique identifier (ID) of the board.
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      - in: query
        name: limit
        description: The maximum number of items to return at one time, default is 10, maximum is 50.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 50
          minimum: 10
      - in: query
        name: cursor
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  limit:
                    type: integer
                    format: int32
                    description: Limit of items.
                    example: 10
                  size:
                    type: integer
                    format: int32
                    description: Size of the items.
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupResponseShort'
          description: Groups 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: 404
                  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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
  /v2/boards/{board_id}/groups/items:
    get:
      description: Returns a list of items that are a part of any group, within a specific board.<br/> 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/> For example, if you set the `limit` query parameter to `10` and the board  contains 20 items that are a part of a group, the first call will return information about the first 10 items (not 10 groups) 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: getItemsByGroupId
      summary: Get items of a group by ID
      parameters:
      - in: path
        name: board_id
        description: Unique identifier (ID) of the board.
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      - in: query
        name: limit
        description: The maximum number of items to return at one time, default is 10, maximum is 50.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 50
          minimum: 10
      - in: query
        name: cursor
        required: false
        schema:
          type: string
      - in: query
        name: group_item_id
        description: The ID of the group item to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  limit:
                    type: integer
                    format: int32
                    description: Limit of items.
                    example: 10
                  size:
                    type: integer
                    format: int32
                    description: Size of the items.
                    example: 1
                  total:
                    type: integer
                    format: int32
                    description: total items that are part of any group
                    example: 1
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier (ID) of the group.
                        example: '3258764517517852419'
                      type:
                        type: string
                        description: Indicates the type of object returned. In this case, `type` returns `group`.
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ItemPagedResponse'
          description: Items 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: 404
                  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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
  /v2/boards/{board_id}/groups/{group_id}:
    get:
      description: 'Returns a list of items in a specific group. <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> per item ID'
      operationId: getGroupById
      summary: Get a group by its ID
      parameters:
      - in: path
        name: board_id
        description: Unique identifier (ID) of the board.
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      - in: path
        name: group_id
        description: Unique identifier (ID) of the group.
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponseShort'
          description: Group 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: 404
                  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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
    delete:
      description: Ungroups items from a group.<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: unGroup
      summary: Ungroup items
      parameters:
      - in: path
        name: board_id
        description: Unique identifier (ID) of the board.
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      - in: path
        name: group_id
        description: Unique identifier (ID) of the group.
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      - in: query
        name: delete_items
        required: false
        description: Indicates whether the items should be removed. By default, false.
        schema:
          type: boolean
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
          description: Ungrouped
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error 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
                description: Test error 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: 404
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                description: Test error 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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
    put:
      description: This endpoint updates an existing group by replacing it entirely with a new group.  When the update is made, the original group is completely replaced, and a new group ID is assigned. <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: updateGroup
      summary: Updates a group with new items
      parameters:
      - in: path
        name: board_id
        description: Unique identifier (ID) of the board.
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      - in: path
        name: group_id
        description: Unique identifier (ID) of the group.
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponseShort'
          description: update group response
        '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: 404
                  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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
  /v2/boards/{board_id}/groups/{group_id}?:
    delete:
      description: Deletes a group from a board. All the items in the group are deleted along with the group.  <b>Note - this endpoint will delete items which are locked as well. </b> <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: deleteGroup
      summary: Deletes the group
      parameters:
      - in: path
        name: board_id
        description: Unique identifier (ID) of the board.
        required: true
        schema:
          $ref: '#/components/schemas/BoardId'
      - in: path
        name: group_id
        description: Unique identifier (ID) of the group.
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      - in: query
        name: delete_items
        required: true
        description: Indicates whether the items should be removed. Set to `true` to delete items in the group.
        schema:
          type: boolean
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
          description: Group deleted
        '400':
          content:
            application/json:
              schema:
                type: object
                description: Test error 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
                description: Test error 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: 404
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                description: Test error 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: 429
                  type:
                    type: string
                    description: Type of the error.
                    example: error
          description: Too many requests
      tags:
      - groups
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 sho

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