openapi.yaml

openapi: 3.0.0
info:
  title: Webex Teams API
  description: "Hey there! Thanks for checking out Cisco Webex for Developers. If you've used Cisco Webex Meetings or Cisco Webex Teams (formerly Cisco Spark) you know how easy it is to meet and collaborate with your team members and customers.\r\n\r\nThe Webex for Developers program opens up the power behind the Webex platform to anyone seeking to extend the Webex experience.\r\n\r\nWebex Meetings is a powerful conferencing solution that lets you connect with anyone, anywhere, in real time. By combining video, audio and content sharing, Webex Meetings creates an effective conferencing environment, leading to more productive meetings and increased productivity. Developer information for Webex Meetings will soon be available on this site. In the meantime, to get started with developing for Webex Meetings, please see the Getting Started guides over on Cisco DevNet. Keep reading for information about Webex Teams.\r\n\r\nWebex Teams makes staying in sync with your teammates and customers easy.\r\nConversations in Webex Teams take place in virtual meeting rooms. Some rooms live for a few hours while others become permanent fixtures of your team's workflow with titles like Daily Standup or Build Status. Webex Teams allows conversations to flow seamlessly between messages, video calls, and real-time whiteboarding sessions. No other solution brings together so many facets of collaboration into a single unified platform.\r\n\r\nhttps://developer.webex.com/getting-started.html"
  contact: {}
  version: "1.0"
servers:
  - url: "https://webexapis.com/v1/"
    variables: {}
paths:
  "/adminAudit/events":
    get:
      tags:
        - Admin Audit Events
      summary: List Admin Audit Events
      description: |
        List admin audit events in your organization. Several query parameters are available to filter the response.
      operationId: ListAdminAuditEvents
      parameters:
        - name: orgId
          in: query
          required: true
          description: List events in this organization, by ID
          schema:
            type: string
        - name: from
          in: query
          required: true
          description: List events which occurred after a specific date and tim
          schema:
            type: string
        - name: to
          in: query
          required: true
          description: List events which occurred before a specific date and time
          schema:
            type: string
        - name: actorId
          in: query
          required: false
          description: List events performed by this person, by ID
          schema:
            type: string
        - name: max
          in: query
          required: false
          description: |
            Limit the maximum number of events in the response. The maximum value is 200
            Default: 100
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          description: |
            Offset from the first result that you want to fetch.
            Default: 0
          schema:
            type: integer
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEvents"
  "/events":
    get:
      tags:
        - Events
      summary: List Events
      description: | 
        List events in your organization. Several query parameters are available to filter the response.
        Long result sets will be split into pages.
      operationId: ListEvents
      parameters:
        - name: resource
          in: query
          required: false
          description: "List events with a specific resource type. Possible values: messages, memberships, tabs, rooms, attachmentActions"
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: "List events with a specific event type. Possible values: created, updated, deleted"
          schema:
            type: string
        - name: actorId
          in: query
          required: false
          description: List events performed by this person, by ID.
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: List events which occurred after a specific date and time.
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: List events which occurred before a specific date and time. If unspecified or set to a time in the future, lists events up to the present.
          schema:
            type: string
        - name: max
          in: query
          required: false
          description: |
            Limit the maximum number of events in the response. The maximum value is 200
            Default: 100
          schema:
            type: integer
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Events"
  "/events/{eventId}":
    get:
      tags:
        - Events
      summary: Get Event Details
      description: | 
        Shows details for an event, by event ID.
        Specify the event ID in the eventId parameter in the URI.
      operationId: GetEvent
      parameters:
        - name: eventId
          in: path
          required: true
          description: The unique identifier for the event.
          schema:
            type: string
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Event"
  "/memberships":
    get:
      tags:
        - Memberships
      summary: List memberships
      description: |
        Lists all room memberships. By default, lists memberships for rooms to which the authenticated user belongs.
        Use query parameters to filter the response.
        Use roomId to list memberships for a room, by ID.
        Use either personId or personEmail to filter the results.
      operationId: ListMemberships
      parameters:
        - name: roomId
          in: query
          description: List memberships associated with a room, by ID.
          required: false
          schema:
            type: string
        - name: personId
          in: query
          description: |
            List memberships associated with a person, by ID. 
            The roomId parameter is required when using this parameter.
          required: false
          schema:
            type: string
        - name: personEmail
          in: query
          description: |
            List memberships associated with a person, by email address. 
            The roomId parameter is required when using this parameter.
          required: false
          schema:
            type: string
        - name: max
          in: query
          description: |
            Limit the maximum number of memberships in the response.
            Default: 100
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Memberships"
          headers: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
    post:
      tags:
        - Memberships
      summary: Create a membership
      description: |
        Add someone to a room by Person ID or email address; optionally making them a moderator.
      operationId: CreateMembership
      parameters: []
      requestBody:
        description: "Body Parameters"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMembershipRequest"
        required: true
      responses:
        "200":
          description: "Successful request with body content."
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Membership"
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
  "/memberships/{membershipId}":
    get:
      tags:
        - Memberships
      summary: Get Membership Details
      description: |
        Get details for a membership by ID.
        Specify the membership ID in the membershipId URI parameter.
      operationId: GetMembership
      parameters:
        - name: membershipId
          in: path
          description: The unique identifier for the membership.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Membership"
          headers: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
    put:
      tags:
        - Memberships
      summary: Update a Membership
      description: |
        Updates properties for a membership by ID.
        Specify the membership ID in the membershipId URI parameter.
      operationId: UpdateMembership
      parameters:
        - name: membershipId
          in: path
          description: The unique identifier for the membership.
          required: true
          schema:
            type: string
      requestBody:
        description: "Body Parameters"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMembershipRequest"
        required: true
      responses:
        "200":
          description: "Successful request with body content."
          headers: {}
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Membership"
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
    delete:
      tags:
        - Memberships
      summary: Delete a Membership
      description: |
        Deletes a membership by ID.
        Specify the membership ID in the membershipId URI parameter.
        The membership for the last moderator of a Team's General space may not be deleted; promote another user to team moderator first.
      operationId: DeleteMembership
      parameters:
        - name: membershipId
          in: path
          description: The unique identifier for the membership.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: "Successful request without body content."
          headers: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
  "/licenses":
    get:
      tags:
        - Licenses
      summary: List Licenses
      description: |
        List all licenses for a given organization. If no orgId is specified, the default is the organization of the authenticated user.
        Response properties that are not applicable to the license will not be present in the response.
      operationId: ListLicenses
      parameters:
        - name: orgId
          in: query
          description: List licenses for this organization.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Licenses"
          headers: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
  "/licenses/{licenseId}":
    get:
      tags:
        - Licenses
      summary: Get License Details
      description: |
        Shows details for a license, by ID.
        Specify the license ID in the licenseId parameter in the URI.
        Response properties that are not applicable to the license will not be present in the response.
      operationId: GetLicense
      parameters:
        - name: licenseId
          in: path
          description: The unique identifier for the license.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful request with body content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          headers: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      deprecated: false
components:
  schemas:
    AuditEvents:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          description: items
          items:
            type: object
            properties:
              created:
                type: string
                format: date-time
                description: The date and time the event took place.
              actorOrgId:
                type: string
                description: The orgId of the person who made the change.
              id:
                type: string
                description: A unique identifier for the event.
              actorId:
                type: string
                description: The personId of the person who made the change.
              data:
                type: object
                description: data
                properties:
                  actorOrgName:
                    type: string
                    description: The display name of the organization.
                  targetName:
                    type: string
                    description: The name of the resource being acted upon.
                  eventDescription:
                    type: string
                    description: A description for the event.
                  actorName:
                    type: string
                    description: The name of the person who performed the action.
                  actorEmail:
                    type: string
                    description: The email of the person who performed the action.
                  adminRoles:
                    type: array
                    description: Admin roles for the person.
                    items:
                      type: string
                  trackingId:
                    type: string
                    description: A tracking identifier for the event.
                  targetType:
                    type: string
                    description: The type of resource changed by the event.
                  targetId:
                    type: string
                    description: The identifier for the resource changed by the event.
                  eventCategory:
                    type: string
                    description: The category of resource changed by the event.
                  actorUserAgent:
                    type: string
                    description: The browser user agent of the person who performed the action.
                  actorIp:
                    type: string
                    description: The IP address of the person who performed the action.
                  targetOrgId:
                    type: string
                    description: The orgId of the organization.
                  actionText:
                    type: string
                    description: A more detailed description of the change made by the person.
                  targetOrgName:
                    type: string
                    description: The name of the organization being acted upon.
    Event:
      type: object
      required:
        - id
        - resource
        - appId
        - actorId
        - orgId
        - created
        - actorOrgId
        - data
      properties:
        id:
          type: string
          description: A unique identifier for the event.
        resource:
          type: string
          description: The type of resource in the event.
        appId:
          type: string
          description: The ID of the application for the event.
        actorId:
          type: string
          description: The personId of the person who made the change.
        orgId:
          type: string
          description: The ID of the organization for the event.
        created:
          type: string
          format: date-time
          description: The date and time of the event.
        actorOrgId:
          type: string
          description: The orgId of the person who made the change.
        data:
          type: object
          description: data
          required:
            - id
            - roomId
            - roomType
            - text
            - personId
            - personEmail
            - created
          properties:
            id:
              type: string
              description: Action ID.
            roomId:
              type: string
              description: Room ID where the event happened.
            roomType:
              type: string
              description: Room type where the event happened.
            text:
              type: string
              description: Text related to the event, in the case of a message.
            personId:
              type: string
              description: Person ID of the user who triggered the event.
            personEmail:
              type: string
              description: Person Email of the user who triggered the event.
            created:
              type: string
              format: date-time
              description: The date and time of the event.
    Events:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Event"
    Membership:
      type: object
      required:
        - id
        - roomId
        - personId
        - personEmail
        - personDisplayName
        - personOrgId
        - isModerator
        - isRoomHidden
        - roomType
        - isMonitor
        - created
      properties:
        id:
          type: string
          description: A unique identifier for the membership.
        roomId:
          type: string
          description: The room ID.
        personId:
          type: string
          description: The person ID
        personEmail:
          type: string
          description: The email address of the person
        personDisplayName:
          type: string
          description: The display name of the person
        personOrgId:
          type: string
          description: The organization ID of the person
        isModerator:
          type: boolean
          description: Whether or not the participant is a room moderator.
        isRoomHidden:
          type: boolean
          description: Whether or not the room is hidden in the Webex Teams clients
        roomType:
          type: string
          description: |
            The type of room the membership is associated with:
              direct -> 1:1 room
              group -> group room
          enum:
            - direct
            - group
        isMonitor:
          type: boolean
          description: Whether or not the participant is a monitoring bot (deprecated).
        created:
          type: string
          format: date-time
          description: The date and time when the membership was created
    Memberships:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Membership"
    CreateMembershipRequest:
      type: object
      required:
        - roomId
      properties:
        roomId:
          type: string
          description: The room ID
        personId:
          type: string
          description: The person ID
        personEmail:
          type: string
          description: The email address of the person
        isModerator:
          type: boolean
          description: Whether or not the participant is a room moderator
    UpdateMembershipRequest:
      type: object
      required:
        - isModerator
        - isRoomHidden
      properties:
        isRoomHidden:
          type: boolean
          description: Whether or not the room is hidden in the Webex Teams clients
        isModerator:
          type: boolean
          description: Whether or not the participant is a room moderator
    License:
      type: object
      required:
        - id
        - name
        - totalUnits
        - consumedUnits
        - subscriptionId
        - siteUrl
      properties:
        id:
          type: string
          description: A unique identifier for the license
        name:
          type: string
          description: Name of the licensed feature
        totalUnits:
          type: integer
          description: Total number of license units allocated
        consumedUnits:
          type: integer
          description: Total number of license units consumed
        subscriptionId:
          type: string
          description: The subscription ID associated with this license. This ID is used in other systems, such as Webex Control Hub.
        siteUrl:
          type: string
          description: The Webex Meetings site associated with this license
        siteType:
          type: string
          description: |
            The type of site associated with this license.
            Control Hub managed site: the site is managed by Webex Control Hub
            Linked site: the site is a linked site
            Site Admin managed site: the site is managed by Site Administration
          enum:
            - Control Hub managed site
            - Linked site
            - Site Admin managed site
    Licenses:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/License"
    Error:
      type: object
      required:
        - message
        - errors
        - trackingId
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          description: API Error
          required:
            - description
          properties:
            description:
              type: string
              description: Error description
        trackingId:
          type: string
          description: Error tracking ID
  securitySchemes:
    httpBearer:
      type: http
      scheme: bearer
security:
  - httpBearer: []
tags:
  - name: Admin Audit Events
    description: "Admin Audit Events are available to full administrators for certain events performed in Webex Control Hub."
  - name: Attachment Actions
    description: "Users create attachment actions by interacting with message attachments such as clicking on a submit button in a card."
  - name: Call Controls
    description: "Call Control APIs in support of Webex Calling. All GET commands require the spark:calls_read scope while all other commands require the spark:calls_write scope."
  - name: Device Configurations
    description: "The Device Configurations API allows developers to view and modify configurations on Webex Rooms devices, as well as other devices that use the configuration service."
  - name: Devices
    description: "Devices represent cloud-registered Webex RoomOS devices, as well as actively-connected Webex soft clients on mobile or desktop. Devices may be associated with Places."
  - name: Events
    description: "Events are generated when actions take place within Webex Teams, such as when someone creates or deletes a message. Compliance Officers may use the Events API to retrieve events for all users within an organization."
  - name: Hybrid Clusters
    description: "Hybrid Clusters are groups of hosts, and the connectors these hosts contain, that are managed as a unit. All the connectors of a single type in a cluster share the same configuration."
  - name: Hybrid Connectors
    description: "Hybrid Connectors are pieces of software that run on-premise and provide a link between the Cisco Webex Cloud and on-premise resources."
  - name: Licenses
    description: "An allowance for features and services that are provided to users on a Webex Teams services subscription. Cisco and its partners manage the amount of licenses provided to administrators and users. This license resource can be accessed only by an admin."
  - name: Locations
    description: "Locations are used to organize Webex Calling (BroadCloud) features within physical locations. Webex Control Hub may be used to define new locations."
  - name: Meeting Invitees
    description: "This API manages invitees' relationships to a meeting."
  - name: Meeting Preferences
    description: "This API manages a user's meeting preferences, including Personal Meeting Room settings, video and audio settings, meeting scheduling options, and site settings."
  - name: Meetings
    description: "Meetings are virtual conferences where users can collaborate in real time using audio, video, content sharing, chat, online whiteboards, and more to collaborate."
  - name: Memberships
    description: "Memberships represent a person's relationship to a room. Use this API to list members of any room that you're in or create memberships to invite someone to a room. Memberships can also be updated to make someone a moderator or deleted to remove them from the room.\r\n\r\nJust like in the Webex Teams app, you must be a member of the room in order to list its memberships or invite people.\r\n\r\nhttps://developer.webex.com/resource-memberships.html"
  - name: Messages
    description: "Messages are how we communicate in a room. In Webex Teams, each message is displayed on its own line along with a timestamp and sender information. Use this API to list, create, and delete messages.\r\n\r\nMessage can contain plain text, rich text, and a file attachment.\r\n\r\nJust like in the Webex Teams app, you must be a member of the room in order to target it with this API.\r\n\r\nhttps://developer.webex.com/resource-messages.html"
  - name: Organizations
    description: "A set of people in Webex Teams. Organizations may manage other organizations or be managed themselves. This organizations resource can be accessed only by an admin."
  - name: People
    description: "People are registered users of Webex Teams. Searching and viewing People requires an auth token with a scope of spark:people_read. Viewing the list of all People in your Organization requires an administrator auth token with spark-admin:people_read scope. Adding, updating, and removing People requires an administrator auth token with the spark-admin:people_write scope.\r\n\r\nTo learn more about managing people in a room see the Memberships API. For information about how to allocate Hybrid Services licenses to people, see the Managing Hybrid Services guide.\r\n\r\nhttps://developer.webex.com/resource-people.html"
  - name: Places
    description: "Places represent where people work, such as conference rooms, meeting spaces, lobbies, and lunch rooms. Devices may be associated with places."
  - name: Recordings
    description: "Recordings are meeting content captured in a meeting or files uploaded via the upload page for your Webex site."
  - name: Resource Group Memberships
    description: 'Resource Group Memberships represent a person''s relationship to a Resource Group for a particular Hybrid Services license. Users assigned a new license will be automatically placed in a "default" Resource Group. Use this API to list memberships for all people in an organization or update memberships to use a different Resource Group.'
  - name: Resource Groups
    description: "Resource Groups are collections of on-premise clusters which provide Hybrid Services to a particular subset of people in an organization. If a person has a Hybrid Services license associated with their account, they will be associated with a resource group to use specific on-premise clusters for that service."
  - name: Roles
    description: "A persona for an authenticated user, corresponding to a set of privileges within an organization. This roles resource can be accessed only by an admin."
  - name: Rooms
    description: "Rooms are virtual meeting places where people post messages and collaborate to get work done. This API is used to manage the rooms themselves. Rooms are created and deleted with this API. You can also update a room to change its title, for example.\r\n\r\nTo create a team room, specify the a teamId in POST payload. Note that once a room is added to a team, it cannot be moved. To learn more about managing teams, see the Teams API.\r\n\r\nTo manage people in a room see the Memberships API.\r\n\r\nTo post content see the Messages API.\r\n\r\nhttps://developer.webex.com/resource-rooms.html"
  - name: Team Memberships
    description: "Team Memberships represent a person's relationship to a team. Use this API to list members of any team that you're in or create memberships to invite someone to a team. Team memberships can also be updated to make someone a moderator or deleted to remove them from the team.\r\n\r\nJust like in the Webex Teams app, you must be a member of the team in order to list its memberships or invite people..\r\n\r\nhttps://developer.webex.com/resource-team-memberships.html"
  - name: Teams
    description: "Teams are groups of people with a set of rooms that are visible to all members of that team. This API is used to manage the teams themselves. Teams are created and deleted with this API. You can also update a team to change its name, for example.\r\n\r\nTo manage people in a team see the Team Memberships API.\r\n\r\nTo manage team rooms see the Rooms API.\r\n\r\nhttps://developer.webex.com/resource-teams.html"
  - name: Webhooks
    description: "Webhooks allow your app to be notified via HTTP when a specific event occurs in Webex Teams. For example, your app can register a webhook to be notified when a new message is posted into a specific room.\r\n\r\nEvents trigger in near real-time allowing your app and backend IT systems to stay in sync with new content and room activity.\r\n\r\nCheck the Webhooks Guide and our blog regularly for announcements of additional webhook resources and event types.\r\n\r\nhttps://developer.webex.com/resource-webhooks.html"