openapi: 3.0.1
info:
  title: Miro Developer Platform AI Interaction Logs User group members 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: User group members
paths:
  /v2/orgs/{org_id}/groups/{group_id}/members:
    get:
      description: Retrieves the list of members who are part of a team in an existing organization.<br/> <h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>organizations:groups:read</a><br/> <h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/> <h3>Enterprise only</h3> <p>This API is available only for <a target=_blank href="/reference/api-reference#enterprise-plan">Enterprise plan</a> users. You can only use this endpoint if you have the role of a Company Admin. You can request temporary access to Enterprise APIs using <a target=_blank href="https://q2oeb0jrhgi.typeform.com/to/BVPTNWJ9">this form</a>.</p>
      operationId: enterprise-get-group-members
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathGroupId'
      - $ref: '#/components/parameters/queryLimitGroupMembers'
      - $ref: '#/components/parameters/queryCursorGroupMembers'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembersPage'
          description: Page of user group members
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
      summary: List of user group members
      tags:
      - User group members
    post:
      description: Adds a member to a user group in an organization.<br/> <h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>organizations:groups:write</a><br/> <h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/> <h3>Enterprise only</h3> <p>This API is available only for <a target=_blank href="/reference/api-reference#enterprise-plan">Enterprise plan</a> users. You can only use this endpoint if you have the role of a Company Admin. You can request temporary access to Enterprise APIs using <a target=_blank href="https://q2oeb0jrhgi.typeform.com/to/BVPTNWJ9">this form</a>.</p>
      operationId: enterprise-create-group-member
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupMemberRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
          description: User group member
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
      summary: Create user group member
      tags:
      - User group members
    patch:
      description: Add and remove members in one request. For example, remove user A and add user B. You can add or remove up to 500 users at a time.<br/> <h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>organizations:groups:write</a><br/> <h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a> per item. For example, if you want to add 10 users and remove 5, the rate limiting applicable will be 750 credits. This is because each user addition or deletion takes Level 1 rate limiting of 50 credits, so 15 * 50 = 750.<br/> <h3>Enterprise only</h3> <p>This API is available only for <a target=_blank href="/reference/api-reference#enterprise-plan">Enterprise plan</a> users. You can only use this endpoint if you have the role of a Company Admin. You can request temporary access to Enterprise APIs using <a target=_blank href="https://q2oeb0jrhgi.typeform.com/to/BVPTNWJ9">this form</a>.</p>
      operationId: enterprise-update-group-members
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGroupMembersRequest'
        required: true
      responses:
        '207':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUserGroupMembersResult'
          description: 'Results for adding or removing members of a user group. <br/> <small>Note that adding users might succeed partially. In this case, the array of responses contains two objects with operation set to "addMembers": one for the successfully added members, and one explaining why the operation failed for the remaining members.</small>'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '413':
          $ref: '#/components/responses/413'
        '429':
          $ref: '#/components/responses/429'
      summary: Bulk edit of membership in user group
      tags:
      - User group members
  /v2/orgs/{org_id}/groups/{group_id}/members/{member_id}:
    get:
      description: Retrieves information about a user group member in an organization.<br/> <h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>organizations:groups:read</a><br/> <h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 1</a><br/> <h3>Enterprise only</h3> <p>This API is available only for <a target=_blank href="/reference/api-reference#enterprise-plan">Enterprise plan</a> users. You can only use this endpoint if you have the role of a Company Admin. You can request temporary access to Enterprise APIs using <a target=_blank href="https://q2oeb0jrhgi.typeform.com/to/BVPTNWJ9">this form</a>.</p>
      operationId: enterprise-get-group-member
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathGroupId'
      - $ref: '#/components/parameters/pathGroupMemberId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
          description: User group member
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      summary: Get user group member
      tags:
      - User group members
    delete:
      description: Removes a member from a user group in an organization.<br/> <h3>Required scope</h3> <a target=_blank href=https://developers.miro.com/reference/scopes>organizations:groups:write</a><br/> <h3>Rate limiting</h3> <a target=_blank href="/reference/rate-limiting#rate-limit-tiers">Level 4</a><br/> <h3>Enterprise only</h3> <p>This API is available only for <a target=_blank href="/reference/api-reference#enterprise-plan">Enterprise plan</a> users. You can only use this endpoint if you have the role of a Company Admin. You can request temporary access to Enterprise APIs using <a target=_blank href="https://q2oeb0jrhgi.typeform.com/to/BVPTNWJ9">this form</a>.</p>
      operationId: enterprise-delete-group-member
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathGroupId'
      - $ref: '#/components/parameters/pathGroupMemberId'
      responses:
        '204':
          description: User group member object deleted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
      summary: Delete user group member
      tags:
      - User group members
components:
  schemas:
    QueryLimit:
      type: integer
      format: int32
      minimum: 1
      maximum: 100
      default: 100
      example: 100
    CreateGroupMemberRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          description: User email
          example: user@mail.com
    PageSize:
      type: integer
      format: int32
      minimum: 0
      maximum: 100
      default: 100
      example: 87
      description: Number of results returned in the response considering the cursor and the limit values sent in the request. For example, if there are 20 results, the request does not have a cursor value, and the limit set to 10, the size of the results will be 10. In this example, the response will also return a cursor value that can be used to retrieve the next set of 10 remaining results in the collection.
    QueryCursor:
      type: string
      example: '3055557345821140500'
    GroupMember:
      type: object
      required:
      - id
      - email
      - type
      properties:
        id:
          type: string
          description: User ID
          example: '3074457345618265000'
        email:
          type: string
          description: User email
          example: user@mail.com
        type:
          type: string
          description: Object type
          default: user-group-member
    UpdateUserGroupMembersResultOperation:
      type: string
      description: The name of the operation that was performed.
      enum:
      - addMembers
      - removeMembers
    BasicError:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code.
        code:
          type: string
          description: Description of the status code.
        message:
          type: string
          description: Explanation for the error.
        type:
          type: string
          default: error
    PageCursor:
      type: string
      description: Indicator of the position of the next page of the result. To retrieve the next page, make another query setting its cursor field to the value returned by the current query. If the value is empty, there are no more pages to fetch.
      example: '3074457345821140946'
    UpdateUserGroupMembersResultError:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/UpdateUserGroupMembersResultOperation'
        status:
          type: integer
          description: The HTTP status code for an unsuccessful operation.
          example: 400
        error:
          allOf:
          - $ref: '#/components/schemas/BasicError'
          - type: object
            properties:
              status:
                default: 400
              code:
                default: invalidParameters
    UpdateUserGroupMembersResultSuccess:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/UpdateUserGroupMembersResultOperation'
        status:
          type: integer
          description: The HTTP status code for a successful operation.
          example: 200
        affectedUsers:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
    UpdateUserGroupMembersResult:
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/UpdateUserGroupMembersResultSuccess'
        - $ref: '#/components/schemas/UpdateUserGroupMembersResultError'
    PageLimit:
      type: integer
      format: int32
      minimum: 1
      maximum: 100
      default: 100
      example: 100
      description: The maximum number of results to return per call. If the number of project in the response is greater than the limit specified, the response returns the cursor parameter with a value.
    GroupMembersPage:
      type: object
      description: Page of members that match the search query.
      required:
      - limit
      - size
      - data
      properties:
        limit:
          $ref: '#/components/schemas/PageLimit'
        size:
          $ref: '#/components/schemas/PageSize'
        data:
          type: array
          description: List of group members.
          items:
            $ref: '#/components/schemas/GroupMember'
        cursor:
          $ref: '#/components/schemas/PageCursor'
        type:
          $ref: '#/components/schemas/PageType'
    PageType:
      type: string
      description: Type of the object returned.
      default: cursor-list
    UpdateUserGroupMembersRequest:
      type: object
      properties:
        membersToAdd:
          type: array
          description: List of user identifiers (can be email or ID) to add to the user group.
          items:
            type: string
            description: User ID or user email.
          example:
          - '3074457345618265000'
          - user0@example.com
        membersToRemove:
          type: array
          description: List of user identifiers (can be email or ID) to remove from the user group.
          items:
            type: string
            description: User ID or user email.
          example:
          - '3074457345618265001'
          - user1@example.com
  parameters:
    pathOrgId:
      name: org_id
      description: The ID of an organization.
      in: path
      required: true
      schema:
        type: string
      example: '3074457345618265000'
    queryLimitGroupMembers:
      name: limit
      description: The maximum number of members in the result list.
      in: query
      schema:
        $ref: '#/components/schemas/QueryLimit'
    pathGroupMemberId:
      name: member_id
      description: The ID of a group member.
      in: path
      required: true
      schema:
        type: string
      example: '3074457345618265000'
    queryCursorGroupMembers:
      name: cursor
      description: A representation of the position of a member in the full set of results. It is used to determine the first item of the resulting set. Leave empty to retrieve items from the beginning.
      in: query
      schema:
        $ref: '#/components/schemas/QueryCursor'
    pathGroupId:
      name: group_id
      description: The ID of a user group.
      in: path
      required: true
      schema:
        type: string
      example: '3074457345618265000'
  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