Miro Team user groups API

openapi: 3.2.0
info:
  title: Miro Developer Platform Team user groups API
  version: v2.0
  description: '### Miro Developer Platform concepts


    - New to the Miro Developer Platform?'
servers:
- url: https://api.miro.com/
tags:
- name: Team user groups
paths:
  /v2/orgs/{org_id}/teams/{team_id}/groups:
    get:
      description: 'Retrieves the list of user groups that are part of a team in an organization.


        Required scope

        organizations:groups:read

        organizations:teams:read

        Rate limiting

        Level 1


        Enterprise only


        This API is available only for Enterprise plan 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 this form.'
      operationId: enterprise-teams-get-groups
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathTeamId'
      - $ref: '#/components/parameters/queryLimitTeamGroups'
      - $ref: '#/components/parameters/queryCursorTeamGroups'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamGroupsPage'
          description: Page of user groups to team connections
        '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 to team connections
      tags:
      - Team user groups
    post:
      description: 'Adds a user group to a team in an organization.


        Required scope

        organizations:groups:read

        organizations:teams:write

        Rate limiting

        Level 1


        Enterprise only


        This API is available only for Enterprise plan 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 this form.

        '''
      operationId: enterprise-teams-create-group
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathTeamId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamGroupRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamGroup'
          description: User group to team connection
        '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 to team connection
      tags:
      - Team user groups
  /v2/orgs/{org_id}/teams/{team_id}/groups/{group_id}:
    get:
      description: 'Retrieves information about a specific user group of a team.


        Required scope

        organizations:groups:read

        organizations:teams:read

        Rate limiting

        Level 1


        Enterprise only


        This API is available only for Enterprise plan 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 this form.'
      operationId: enterprise-teams-get-group
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathTeamId'
      - $ref: '#/components/parameters/pathGroupId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamGroup'
          description: Get user group of a team
        '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 of a team
      tags:
      - Team user groups
    delete:
      description: 'Removes a user group from a team in an existing organization.


        Required scope

        organizations:groups:read

        organizations:teams:write

        Rate limiting

        Level 1


        Enterprise only


        This API is available only for Enterprise plan 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 this form.'
      operationId: enterprise-teams-delete-group
      parameters:
      - $ref: '#/components/parameters/pathOrgId'
      - $ref: '#/components/parameters/pathTeamId'
      - $ref: '#/components/parameters/pathGroupId'
      responses:
        '204':
          description: User group to team connection deleted
        '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'
        '429':
          $ref: '#/components/responses/429'
      summary: Delete user group to team connection
      tags:
      - Team user groups
components:
  schemas:
    TeamGroupsPage:
      type: object
      description: Page of groups 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 groups.
          items:
            $ref: '#/components/schemas/TeamGroup'
        cursor:
          $ref: '#/components/schemas/PageCursor'
        type:
          $ref: '#/components/schemas/PageType'
    TeamGroup:
      type: object
      required:
      - id
      - role
      properties:
        id:
          type: string
          description: User group ID.
          example: '3074457345618265000'
        role:
          type: string
          description: Role of the user group in the team.
          enum:
          - member
          default: member
          example: member
        type:
          type: string
          description: Object type
          default: team-user-group
    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.
    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.
    QueryCursor:
      type: string
      example: '3055557345821140500'
    PageType:
      type: string
      description: Type of the object returned.
      default: cursor-list
    QueryLimit:
      type: integer
      format: int32
      minimum: 1
      maximum: 100
      default: 100
      example: 100
    CreateTeamGroupRequest:
      type: object
      required:
      - userGroupId
      - role
      properties:
        userGroupId:
          type: string
          description: User group ID.
          example: '3074457345618265000'
        role:
          type: string
          enum:
          - member
          description: Role of user group in the team.
          example: member
    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'
  parameters:
    pathGroupId:
      name: group_id
      description: The ID of a user group.
      in: path
      required: true
      schema:
        type: string
      example: '3074457345618265000'
    pathOrgId:
      name: org_id
      description: The ID of an organization.
      in: path
      required: true
      schema:
        type: string
      example: '3074457345618265000'
    pathTeamId:
      name: team_id
      description: The ID of a team.
      in: path
      required: true
      schema:
        type: string
      example: '3074457345618265000'
    queryLimitTeamGroups:
      name: limit
      description: The maximum number of user groups in the result list.
      in: query
      schema:
        $ref: '#/components/schemas/QueryLimit'
    queryCursorTeamGroups:
      name: cursor
      description: A representation of the position of a user group 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'
  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