Cisco Webex Memberships API

openapi: 3.1.0
info:
  title: Cisco Webex Admin Audit Events Memberships API
  description: Access admin audit events for tracking administrative actions performed in Webex Control Hub. Available to full administrators for compliance monitoring and security auditing purposes.
  version: 1.0.0
  contact:
    name: Cisco Webex Developer Support
    url: https://developer.webex.com/support
  license:
    name: Cisco Webex API Terms of Service
    url: https://developer.webex.com/terms-of-service
servers:
- url: https://webexapis.com/v1
  description: Webex Production API
security:
- bearerAuth: []
tags:
- name: Memberships
  description: Operations for managing room memberships
paths:
  /memberships:
    get:
      operationId: listMemberships
      summary: Cisco Webex List Memberships
      description: Lists all room memberships. Filter by room ID, person ID, or person email. Results are paginated and include membership status and roles.
      tags:
      - Memberships
      parameters:
      - name: roomId
        in: query
        description: Filter memberships by room ID.
        schema:
          type: string
      - name: personId
        in: query
        description: Filter memberships by person ID.
        schema:
          type: string
      - name: personEmail
        in: query
        description: Filter memberships by person email address.
        schema:
          type: string
          format: email
      - name: max
        in: query
        description: Maximum number of memberships to return (default 100).
        schema:
          type: integer
          default: 100
      responses:
        '200':
          description: Successful response with list of memberships.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Membership'
        '401':
          description: Unauthorized - invalid or missing access token.
    post:
      operationId: createMembership
      summary: Cisco Webex Create a Membership
      description: Adds a person to a room. The person can be specified by person ID or email address. Optionally set the person as a room moderator.
      tags:
      - Memberships
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMembershipRequest'
      responses:
        '200':
          description: Membership created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad request - invalid input parameters.
        '401':
          description: Unauthorized - invalid or missing access token.
        '409':
          description: Conflict - person is already a member of the room.
  /memberships/{membershipId}:
    get:
      operationId: getMembershipDetails
      summary: Cisco Webex Get Membership Details
      description: Shows details for a membership by ID. Returns the membership configuration including role and hidden status.
      tags:
      - Memberships
      parameters:
      - name: membershipId
        in: path
        required: true
        description: Unique identifier for the membership.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with membership details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '404':
          description: Membership not found.
    put:
      operationId: updateMembership
      summary: Cisco Webex Update a Membership
      description: Updates properties of a membership by ID. Allows changing the moderator status and visibility of direct spaces.
      tags:
      - Memberships
      parameters:
      - name: membershipId
        in: path
        required: true
        description: Unique identifier for the membership.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMembershipRequest'
      responses:
        '200':
          description: Membership updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad request - invalid input parameters.
        '404':
          description: Membership not found.
    delete:
      operationId: deleteMembership
      summary: Cisco Webex Delete a Membership
      description: Deletes a membership by ID. The person is removed from the room and can no longer access the room's content.
      tags:
      - Memberships
      parameters:
      - name: membershipId
        in: path
        required: true
        description: Unique identifier for the membership.
        schema:
          type: string
      responses:
        '204':
          description: Membership deleted successfully.
        '404':
          description: Membership not found.
components:
  schemas:
    UpdateMembershipRequest:
      type: object
      required:
      - isModerator
      properties:
        isModerator:
          type: boolean
          description: Whether the person is a room moderator.
        isRoomHidden:
          type: boolean
          description: Whether to hide the direct space.
    CreateMembershipRequest:
      type: object
      required:
      - roomId
      properties:
        roomId:
          type: string
          description: The room ID to add the person to.
        personId:
          type: string
          description: The person ID to add. Either personId or personEmail is required.
        personEmail:
          type: string
          format: email
          description: The email address of the person to add. Either personId or personEmail is required.
        isModerator:
          type: boolean
          description: Whether the person is a room moderator.
    Membership:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the membership.
        roomId:
          type: string
          description: The room ID for the membership.
        personId:
          type: string
          description: The person ID for the membership.
        personEmail:
          type: string
          format: email
          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 the person is a room moderator.
        isRoomHidden:
          type: boolean
          description: Whether the direct space is hidden.
        roomType:
          type: string
          description: The type of room.
          enum:
          - direct
          - group
        isMonitor:
          type: boolean
          description: Whether the member is a monitoring bot.
        created:
          type: string
          format: date-time
          description: Date and time the membership was created.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Webex API access token. Obtain via OAuth 2.0 authorization flow. Requires audit:events_read scope.