openapi: 3.1.0
info:
  title: Microsoft Teams API
  description: >-
    Build apps and bots for Microsoft Teams via Microsoft Graph. Manage teams,
    channels, messages, members, and tabs programmatically.
  version: '1.0'
  contact:
    name: Microsoft Teams Developer Support
    url: https://developer.microsoft.com/en-us/microsoft-teams
  termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
externalDocs:
  description: Microsoft Teams API Overview
  url: https://learn.microsoft.com/en-us/graph/teams-concept-overview
servers:
  - url: https://graph.microsoft.com/v1.0
    description: Microsoft Graph v1.0 Production
tags:
  - name: Channels
    description: Manage channels within teams
  - name: Members
    description: Manage team membership
  - name: Messages
    description: Send and manage channel messages
  - name: Teams
    description: Manage teams
security:
  - oauth2: []
paths:
  /teams:
    get:
      operationId: listTeams
      summary: Microsoft List all teams
      description: List all teams in an organization.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/top'
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamCollection'
        '401':
          description: Unauthorized
    post:
      operationId: createTeam
      summary: Microsoft Create a team
      description: Create a new team.
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamRequest'
      responses:
        '202':
          description: Team creation accepted
          headers:
            Location:
              schema:
                type: string
              description: URL to poll for team creation status
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /teams/{teamId}:
    get:
      operationId: getTeam
      summary: Microsoft Get a team
      description: Retrieve the properties and relationships of the specified team.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          description: Unauthorized
        '404':
          description: Team not found
    patch:
      operationId: updateTeam
      summary: Microsoft Update a team
      description: Update the properties of a team.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamRequest'
      responses:
        '204':
          description: Team updated
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Team not found
    delete:
      operationId: deleteTeam
      summary: Microsoft Delete a team
      description: Delete a team and its associated group.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/teamId'
      responses:
        '204':
          description: Team deleted
        '401':
          description: Unauthorized
        '404':
          description: Team not found
  /teams/{teamId}/channels:
    get:
      operationId: listChannels
      summary: Microsoft List channels
      description: Retrieve the list of channels in a team.
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: List of channels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelCollection'
        '401':
          description: Unauthorized
    post:
      operationId: createChannel
      summary: Microsoft Create a channel
      description: Create a new channel in a team.
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChannelRequest'
      responses:
        '201':
          description: Channel created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /teams/{teamId}/channels/{channelId}:
    get:
      operationId: getChannel
      summary: Microsoft Get a channel
      description: Retrieve the properties of a channel.
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/channelId'
      responses:
        '200':
          description: Channel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '401':
          description: Unauthorized
        '404':
          description: Channel not found
    delete:
      operationId: deleteChannel
      summary: Microsoft Delete a channel
      description: Delete a channel in a team.
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/channelId'
      responses:
        '204':
          description: Channel deleted
        '401':
          description: Unauthorized
        '404':
          description: Channel not found
  /teams/{teamId}/channels/{channelId}/messages:
    get:
      operationId: listChannelMessages
      summary: Microsoft List channel messages
      description: Retrieve the list of messages in a channel.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/channelId'
        - $ref: '#/components/parameters/top'
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessageCollection'
        '401':
          description: Unauthorized
    post:
      operationId: sendChannelMessage
      summary: Microsoft Send a channel message
      description: Send a new message to a channel.
      tags:
        - Messages
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/channelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatMessageRequest'
      responses:
        '201':
          description: Message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessage'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /teams/{teamId}/members:
    get:
      operationId: listTeamMembers
      summary: Microsoft List team members
      description: Get the members of a team.
      tags:
        - Members
      parameters:
        - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: List of team members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberCollection'
        '401':
          description: Unauthorized
    post:
      operationId: addTeamMember
      summary: Microsoft Add a team member
      description: Add a new member to a team.
      tags:
        - Members
      parameters:
        - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddMemberRequest'
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 via 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
            Team.Create: Create teams
            Channel.ReadBasic.All: Read channels
            ChannelMessage.Read.All: Read channel messages
            ChannelMessage.Send: Send channel messages
            TeamMember.Read.All: Read team members
  parameters:
    teamId:
      name: teamId
      in: path
      required: true
      description: Team unique identifier
      schema:
        type: string
    channelId:
      name: channelId
      in: path
      required: true
      description: Channel unique identifier
      schema:
        type: string
    select:
      name: $select
      in: query
      description: Properties to include in the response
      schema:
        type: string
    filter:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    top:
      name: $top
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
  schemas:
    TeamCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Team'
    Team:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        description:
          type: string
        isArchived:
          type: boolean
        webUrl:
          type: string
        visibility:
          type: string
          enum:
            - private
            - public
        funSettings:
          type: object
          properties:
            allowGiphy:
              type: boolean
            allowStickersAndMemes:
              type: boolean
        memberSettings:
          type: object
          properties:
            allowCreateUpdateChannels:
              type: boolean
            allowDeleteChannels:
              type: boolean
            allowAddRemoveApps:
              type: boolean
    CreateTeamRequest:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
        description:
          type: string
        visibility:
          type: string
          enum:
            - private
            - public
    UpdateTeamRequest:
      type: object
      properties:
        displayName:
          type: string
        description:
          type: string
        visibility:
          type: string
    ChannelCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
    Channel:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        description:
          type: string
        membershipType:
          type: string
          enum:
            - standard
            - private
            - shared
        email:
          type: string
        webUrl:
          type: string
    CreateChannelRequest:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
        description:
          type: string
        membershipType:
          type: string
          enum:
            - standard
            - private
            - shared
    ChatMessageCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
    ChatMessage:
      type: object
      properties:
        id:
          type: string
        messageType:
          type: string
        createdDateTime:
          type: string
          format: date-time
        from:
          type: object
          properties:
            user:
              type: object
              properties:
                id:
                  type: string
                displayName:
                  type: string
        body:
          type: object
          properties:
            contentType:
              type: string
              enum:
                - text
                - html
            content:
              type: string
        importance:
          type: string
          enum:
            - normal
            - high
            - urgent
    CreateChatMessageRequest:
      type: object
      required:
        - body
      properties:
        body:
          type: object
          required:
            - content
          properties:
            contentType:
              type: string
              enum:
                - text
                - html
              default: text
            content:
              type: string
        importance:
          type: string
          enum:
            - normal
            - high
            - urgent
    MemberCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Member'
    Member:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        roles:
          type: array
          items:
            type: string
        userId:
          type: string
        email:
          type: string
    AddMemberRequest:
      type: object
      required:
        - '@odata.type'
        - roles
        - user@odata.bind
      properties:
        '@odata.type':
          type: string
          default: '#microsoft.graph.aadUserConversationMember'
        roles:
          type: array
          items:
            type: string
        user@odata.bind:
          type: string
          description: URL reference to the user to add