Microsoft Graph Teams API

openapi: 3.0.3
info:
  title: Microsoft Graph Teams API
  description: >-
    Core REST API for accessing Microsoft Teams data including teams, channels,
    messages, tabs, apps, calls, and online meetings through Microsoft Graph.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/graph/support
  license:
    name: Microsoft API Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
  - url: https://graph.microsoft.com/v1.0
    description: Microsoft Graph v1.0 production endpoint
security:
  - oauth2:
      - Team.ReadBasic.All
      - Channel.ReadBasic.All
      - ChatMessage.Read
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization using Microsoft Identity Platform
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Team.ReadBasic.All: Read teams basic info
            Team.Create: Create teams
            Channel.ReadBasic.All: Read channel basic info
            Channel.Create: Create channels
            ChannelMessage.Read.All: Read channel messages
            ChatMessage.Read: Read chat messages
            ChatMessage.Send: Send chat messages
            Calls.Initiate.All: Initiate calls
            Calls.JoinGroupCall.All: Join group calls
            OnlineMeetings.ReadWrite.All: Create and manage online meetings
  schemas:
    Team:
      type: object
      description: Represents a Microsoft Teams team.
      properties:
        id:
          type: string
          description: Unique identifier for the team.
          example: team-a1b2c3d4
        displayName:
          type: string
          description: The display name of the team.
          example: Engineering Team
        description:
          type: string
          description: Description of the team.
          example: Core engineering team for product development.
        visibility:
          type: string
          enum:
            - public
            - private
          description: Team visibility.
          example: private
        isArchived:
          type: boolean
          description: Whether the team is archived.
          example: false
        createdDateTime:
          type: string
          format: date-time
          description: When the team was created.
          example: '2025-06-15T08:00:00Z'
        webUrl:
          type: string
          format: uri
          description: URL to the team in Microsoft Teams.
          example: https://teams.microsoft.com/l/team/19%3abc123/
    TeamCollection:
      type: object
      description: Collection of teams.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Team'
    Channel:
      type: object
      description: Represents a channel in a team.
      properties:
        id:
          type: string
          description: Unique identifier for the channel.
          example: 19:abc123@thread.tacv2
        displayName:
          type: string
          description: The display name of the channel.
          example: General
        description:
          type: string
          description: Description of the channel.
          example: General discussion channel.
        membershipType:
          type: string
          enum:
            - standard
            - private
            - shared
          description: Type of membership for the channel.
          example: standard
        createdDateTime:
          type: string
          format: date-time
          description: When the channel was created.
          example: '2025-06-15T08:00:00Z'
        webUrl:
          type: string
          format: uri
          description: URL to the channel in Teams.
    ChannelCollection:
      type: object
      description: Collection of channels.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
    ChatMessage:
      type: object
      description: Represents a message in a channel or chat.
      properties:
        id:
          type: string
          description: Unique identifier for the message.
          example: msg-001
        createdDateTime:
          type: string
          format: date-time
          description: When the message was created.
          example: '2026-04-18T10:30:00Z'
        lastModifiedDateTime:
          type: string
          format: date-time
          description: When the message was last modified.
          example: '2026-04-18T10:30:00Z'
        messageType:
          type: string
          description: The type of message.
          enum:
            - message
            - chatEvent
            - typing
            - unknownFutureValue
            - systemEventMessage
          example: message
        importance:
          type: string
          enum:
            - normal
            - high
            - urgent
          description: Message importance.
          example: normal
        subject:
          type: string
          description: Subject of the message.
          example: Project Update
        body:
          type: object
          properties:
            contentType:
              type: string
              enum:
                - text
                - html
              example: html
            content:
              type: string
              example: '<p>Here is the latest update on the project.</p>'
        from:
          type: object
          properties:
            user:
              type: object
              properties:
                id:
                  type: string
                  example: user-123
                displayName:
                  type: string
                  example: Jane Smith
    ChatMessageCollection:
      type: object
      description: Collection of chat messages.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
    TeamsTab:
      type: object
      description: Represents a tab pinned to a channel.
      properties:
        id:
          type: string
          description: Unique identifier for the tab.
          example: tab-001
        displayName:
          type: string
          description: Display name of the tab.
          example: Project Wiki
        webUrl:
          type: string
          format: uri
          description: URL to the tab content.
        configuration:
          type: object
          properties:
            entityId:
              type: string
            contentUrl:
              type: string
              format: uri
            removeUrl:
              type: string
              format: uri
            websiteUrl:
              type: string
              format: uri
    TabCollection:
      type: object
      description: Collection of tabs.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/TeamsTab'
    TeamsAppInstallation:
      type: object
      description: Represents an app installed in a team.
      properties:
        id:
          type: string
          description: Unique identifier.
          example: app-install-001
        teamsApp:
          type: object
          properties:
            id:
              type: string
              example: com.contoso.app
            displayName:
              type: string
              example: Contoso App
            distributionMethod:
              type: string
              enum:
                - store
                - organization
                - sideloaded
    AppInstallationCollection:
      type: object
      description: Collection of app installations.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/TeamsAppInstallation'
    ConversationMember:
      type: object
      description: Represents a member of a team or channel.
      properties:
        id:
          type: string
          description: Unique membership ID.
          example: membership-001
        displayName:
          type: string
          description: Display name of the member.
          example: Jane Smith
        roles:
          type: array
          items:
            type: string
          description: Roles of the member.
          example:
            - owner
        userId:
          type: string
          description: The Azure AD user ID.
          example: user-abc123
        email:
          type: string
          format: email
          description: Email address of the member.
          example: jsmith@contoso.com
    MemberCollection:
      type: object
      description: Collection of members.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMember'
    OnlineMeeting:
      type: object
      description: Represents an online meeting in Teams.
      properties:
        id:
          type: string
          description: Unique identifier for the meeting.
          example: meeting-abc123
        subject:
          type: string
          description: Subject of the meeting.
          example: Weekly Standup
        startDateTime:
          type: string
          format: date-time
          description: Start time of the meeting.
          example: '2026-04-19T09:00:00Z'
        endDateTime:
          type: string
          format: date-time
          description: End time of the meeting.
          example: '2026-04-19T09:30:00Z'
        joinWebUrl:
          type: string
          format: uri
          description: URL to join the meeting.
          example: https://teams.microsoft.com/l/meetup-join/19:meeting_abc123/
        participants:
          type: object
          properties:
            organizer:
              type: object
              properties:
                identity:
                  type: object
                  properties:
                    user:
                      type: object
                      properties:
                        id:
                          type: string
                        displayName:
                          type: string
    Call:
      type: object
      description: Represents a call in Teams.
      properties:
        id:
          type: string
          description: Unique identifier for the call.
          example: call-abc123
        state:
          type: string
          enum:
            - incoming
            - establishing
            - ringing
            - established
            - hold
            - transferring
            - transferAccepted
            - redirecting
            - terminating
            - terminated
          description: Current call state.
          example: established
        direction:
          type: string
          enum:
            - incoming
            - outgoing
          description: Direction of the call.
          example: outgoing
        subject:
          type: string
          description: Subject of the call.
          example: Quick sync
        callbackUri:
          type: string
          format: uri
          description: Callback URL for call notifications.
        requestedModalities:
          type: array
          items:
            type: string
            enum:
              - audio
              - video
              - videoBasedScreenSharing
          description: Requested communication modalities.
    ErrorResponse:
      type: object
      description: Error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: Forbidden
            message:
              type: string
              example: Insufficient privileges to complete the operation.
tags:
  - name: Teams
    description: Operations for managing teams.
  - name: Channels
    description: Operations for managing channels within teams.
  - name: Messages
    description: Operations for sending and receiving chat messages.
  - name: Tabs
    description: Operations for managing tabs in channels.
  - name: Apps
    description: Operations for managing app installations in teams.
  - name: Members
    description: Operations for managing team and channel members.
  - name: Online Meetings
    description: Operations for creating and managing online meetings.
  - name: Calls
    description: Operations for initiating and managing calls.
paths:
  /me/joinedTeams:
    get:
      operationId: listJoinedTeams
      summary: Microsoft Teams List Joined Teams
      description: Retrieve a list of teams the current user has joined.
      tags:
        - Teams
      responses:
        '200':
          description: Teams returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamCollection'
              examples:
                ListJoinedTeams200Example:
                  summary: Default listJoinedTeams 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: team-a1b2c3d4
                        displayName: Engineering Team
                        description: Core engineering team
                        visibility: private
                        isArchived: false
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams:
    post:
      operationId: createTeam
      summary: Microsoft Teams Create Team
      description: Create a new team.
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Team'
            examples:
              CreateTeamRequestExample:
                summary: Default createTeam request
                x-microcks-default: true
                value:
                  displayName: New Project Team
                  description: Team for the new project initiative
                  visibility: private
      responses:
        '202':
          description: Team creation accepted (async operation).
          headers:
            Location:
              schema:
                type: string
              description: URL to poll for operation status.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}:
    get:
      operationId: getTeam
      summary: Microsoft Teams Get Team
      description: Retrieve a specific team by ID.
      tags:
        - Teams
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      responses:
        '200':
          description: Team returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
              examples:
                GetTeam200Example:
                  summary: Default getTeam 200 response
                  x-microcks-default: true
                  value:
                    id: team-a1b2c3d4
                    displayName: Engineering Team
                    description: Core engineering team for product development.
                    visibility: private
                    isArchived: false
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateTeam
      summary: Microsoft Teams Update Team
      description: Update team properties.
      tags:
        - Teams
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Team'
            examples:
              UpdateTeamRequestExample:
                summary: Default updateTeam request
                x-microcks-default: true
                value:
                  displayName: Updated Team Name
                  description: Updated description
      responses:
        '204':
          description: Team updated successfully.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteTeam
      summary: Microsoft Teams Delete Team
      description: Delete a team and its associated group.
      tags:
        - Teams
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      responses:
        '204':
          description: Team deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/archive:
    post:
      operationId: archiveTeam
      summary: Microsoft Teams Archive Team
      description: Archive a team, making it read-only.
      tags:
        - Teams
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shouldSetSpoSiteReadOnlyForMembers:
                  type: boolean
                  description: Whether the SharePoint site should be set to read-only.
      responses:
        '202':
          description: Archive operation accepted.
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/channels:
    get:
      operationId: listChannels
      summary: Microsoft Teams List Channels
      description: Retrieve a list of channels in a team.
      tags:
        - Channels
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      responses:
        '200':
          description: Channels returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelCollection'
              examples:
                ListChannels200Example:
                  summary: Default listChannels 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: '19:abc123@thread.tacv2'
                        displayName: General
                        description: General discussion channel.
                        membershipType: standard
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createChannel
      summary: Microsoft Teams Create Channel
      description: Create a new channel in a team.
      tags:
        - Channels
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Channel'
            examples:
              CreateChannelRequestExample:
                summary: Default createChannel request
                x-microcks-default: true
                value:
                  displayName: Design Review
                  description: Channel for design review discussions
                  membershipType: standard
      responses:
        '201':
          description: Channel created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/channels/{channel-id}/messages:
    get:
      operationId: listChannelMessages
      summary: Microsoft Teams List Channel Messages
      description: Retrieve messages from a channel.
      tags:
        - Messages
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
        - name: channel-id
          in: path
          required: true
          description: The unique identifier of the channel.
          schema:
            type: string
        - name: $top
          in: query
          required: false
          description: Maximum number of messages to return.
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Messages returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessageCollection'
              examples:
                ListChannelMessages200Example:
                  summary: Default listChannelMessages 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: msg-001
                        createdDateTime: '2026-04-18T10:30:00Z'
                        messageType: message
                        importance: normal
                        subject: Project Update
                        body:
                          contentType: html
                          content: '<p>Here is the latest update.</p>'
                        from:
                          user:
                            id: user-123
                            displayName: Jane Smith
        '401':
          description: Unauthorized.
        '404':
          description: Channel not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: sendChannelMessage
      summary: Microsoft Teams Send Channel Message
      description: Send a message to a channel.
      tags:
        - Messages
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
        - name: channel-id
          in: path
          required: true
          description: The unique identifier of the channel.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatMessage'
            examples:
              SendChannelMessageRequestExample:
                summary: Default sendChannelMessage request
                x-microcks-default: true
                value:
                  body:
                    contentType: html
                    content: '<p>Hello team! Here is an update.</p>'
      responses:
        '201':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessage'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/channels/{channel-id}/tabs:
    get:
      operationId: listChannelTabs
      summary: Microsoft Teams List Channel Tabs
      description: Retrieve a list of tabs in a channel.
      tags:
        - Tabs
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
        - name: channel-id
          in: path
          required: true
          description: The unique identifier of the channel.
          schema:
            type: string
      responses:
        '200':
          description: Tabs returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TabCollection'
              examples:
                ListChannelTabs200Example:
                  summary: Default listChannelTabs 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: tab-001
                        displayName: Project Wiki
        '401':
          description: Unauthorized.
        '404':
          description: Channel not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/installedApps:
    get:
      operationId: listInstalledApps
      summary: Microsoft Teams List Installed Apps
      description: Retrieve a list of apps installed in a team.
      tags:
        - Apps
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      responses:
        '200':
          description: Installed apps returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppInstallationCollection'
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/members:
    get:
      operationId: listTeamMembers
      summary: Microsoft Teams List Team Members
      description: Retrieve a list of members in a team.
      tags:
        - Members
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      responses:
        '200':
          description: Members returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberCollection'
              examples:
                ListTeamMembers200Example:
                  summary: Default listTeamMembers 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: membership-001
                        displayName: Jane Smith
                        roles:
                          - owner
                        userId: user-abc123
                        email: jsmith@contoso.com
        '401':
          description: Unauthorized.
        '404':
          description: Team not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addTeamMember
      summary: Microsoft Teams Add Team Member
      description: Add a new member to a team.
      tags:
        - Members
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationMember'
            examples:
              AddTeamMemberRequestExample:
                summary: Default addTeamMember request
                x-microcks-default: true
                value:
                  roles:
                    - member
                  userId: user-def456
      responses:
        '201':
          description: Member added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMember'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /teams/{team-id}/members/{membership-id}:
    delete:
      operationId: removeTeamMember
      summary: Microsoft Teams Remove Team Member
      description: Remove a member from a team.
      tags:
        - Members
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
        - name: membership-id
          in: path
          required: true
          description: The membership ID of the member.
          schema:
            type: string
      responses:
        '204':
          description: Member removed successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Member not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateTeamMember
      summary: Microsoft Teams Update Team Member
      description: Update a member's role in a team.
      tags:
        - Members
      parameters:
        - name: team-id
          in: path
          required: true
          description: The unique identifier of the team.
          schema:
            type: string
        - name: membership-id
          in: path
          required: true
          description: The membership ID of the member.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  items:
                    type: string
            examples:
              UpdateTeamMemberRequestExample:
                summary: Default updateTeamMember request
                x-microcks-default: true
                value:
                  roles:
                    - owner
      responses:
        '200':
          description: Member updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMember'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /communications/onlineMeetings:
    post:
      operationId: createOnlineMeeting
      summary: Microsoft Teams Create Online Meeting
      description: Create a new online meeting.
      tags:
        - Online Meetings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnlineMeeting'
            examples:
              CreateOnlineMeetingRequestExample:
                summary: Default createOnlineMeeting request
                x-microcks-default: true
                value:
                  subject: Weekly Standup
                  startDateTime: '2026-04-19T09:00:00Z'
                  endDateTime: '2026-04-19T09:30:00Z'
      responses:
        '201':
          description: Online meeting created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnlineMeeting'
              examples:
                CreateOnlineMeeting201Example:
                  summary: Default createOnlineMeeting 201 response
                  x-microcks-default: true
                  value:
                    id: meeting-abc123
                    subject: Weekly Standup
                    startDateTime: '2

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-teams/refs/heads/main/openapi/microsoft-teams-graph-api.yaml