Webex Workspaces API

openapi: 3.1.0
info:
  title: Cisco Webex Workspaces API
  description: >-
    Manage workspaces representing physical locations with Webex devices.
    Provides endpoints to create, list, update, and delete workspaces and
    manage their associated device configurations.
  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: Workspaces
    description: Operations for managing workspaces
paths:
  /workspaces:
    get:
      operationId: listWorkspaces
      summary: Cisco Webex List Workspaces
      description: >-
        Lists workspaces in the organization. Supports filtering by display
        name, workspace location ID, floor ID, capacity, type, calling type,
        and calendar type. Results are paginated.
      tags:
        - Workspaces
      parameters:
        - name: displayName
          in: query
          description: Filter by workspace display name.
          schema:
            type: string
        - name: workspaceLocationId
          in: query
          description: Filter by workspace location ID.
          schema:
            type: string
        - name: floorId
          in: query
          description: Filter by floor ID.
          schema:
            type: string
        - name: capacity
          in: query
          description: Filter by workspace capacity.
          schema:
            type: integer
        - name: type
          in: query
          description: Filter by workspace type.
          schema:
            type: string
            enum:
              - notSet
              - focus
              - huddle
              - meetingRoom
              - open
              - desk
              - other
        - name: callingType
          in: query
          description: Filter by calling type.
          schema:
            type: string
            enum:
              - freeCalling
              - hybridCalling
              - webexCalling
              - webexEdgeForDevices
              - none
        - name: calendarType
          in: query
          description: Filter by calendar type.
          schema:
            type: string
            enum:
              - none
              - google
              - microsoft
        - name: orgId
          in: query
          description: Filter by organization ID.
          schema:
            type: string
        - name: start
          in: query
          description: Offset for pagination.
          schema:
            type: integer
        - name: max
          in: query
          description: Maximum number of workspaces to return (default 100).
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response with list of workspaces.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          description: Unauthorized - invalid or missing access token.
    post:
      operationId: createWorkspace
      summary: Cisco Webex Create a Workspace
      description: >-
        Creates a new workspace representing a physical location with Webex
        devices. The workspace can be configured with capacity, type,
        calling, and calendar settings.
      tags:
        - Workspaces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceRequest'
      responses:
        '200':
          description: Workspace created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Bad request - invalid input parameters.
        '401':
          description: Unauthorized - invalid or missing access token.
  /workspaces/{workspaceId}:
    get:
      operationId: getWorkspaceDetails
      summary: Cisco Webex Get Workspace Details
      description: >-
        Shows details for a workspace by ID. Returns the workspace
        configuration, device assignments, and metadata.
      tags:
        - Workspaces
      parameters:
        - name: workspaceId
          in: path
          required: true
          description: Unique identifier for the workspace.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with workspace details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '404':
          description: Workspace not found.
    put:
      operationId: updateWorkspace
      summary: Cisco Webex Update a Workspace
      description: >-
        Updates details for a workspace by ID. Allows modifying display
        name, capacity, type, calling, and calendar settings.
      tags:
        - Workspaces
      parameters:
        - name: workspaceId
          in: path
          required: true
          description: Unique identifier for the workspace.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceRequest'
      responses:
        '200':
          description: Workspace updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Bad request - invalid input parameters.
        '404':
          description: Workspace not found.
    delete:
      operationId: deleteWorkspace
      summary: Cisco Webex Delete a Workspace
      description: >-
        Deletes a workspace by ID. The workspace and its associated device
        configurations are removed. Devices remain but become unassigned.
      tags:
        - Workspaces
      parameters:
        - name: workspaceId
          in: path
          required: true
          description: Unique identifier for the workspace.
          schema:
            type: string
      responses:
        '204':
          description: Workspace deleted successfully.
        '404':
          description: Workspace not found.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Webex API access token. Obtain via OAuth 2.0 authorization flow.
        Requires spark-admin:workspaces_read and spark-admin:workspaces_write
        scopes.
  schemas:
    Workspace:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the workspace.
        orgId:
          type: string
          description: Organization ID the workspace belongs to.
        displayName:
          type: string
          description: Display name of the workspace.
        workspaceLocationId:
          type: string
          description: Location ID of the workspace.
        floorId:
          type: string
          description: Floor ID within the location.
        capacity:
          type: integer
          description: Number of people the workspace can accommodate.
        type:
          type: string
          description: Type of workspace.
          enum:
            - notSet
            - focus
            - huddle
            - meetingRoom
            - open
            - desk
            - other
        sipAddress:
          type: string
          description: SIP address assigned to the workspace.
        calling:
          type: object
          description: Calling configuration for the workspace.
          properties:
            type:
              type: string
              enum:
                - freeCalling
                - hybridCalling
                - webexCalling
                - webexEdgeForDevices
                - none
            hybridCalling:
              type: object
              properties:
                emailAddress:
                  type: string
                  format: email
        calendar:
          type: object
          description: Calendar configuration for the workspace.
          properties:
            type:
              type: string
              enum:
                - none
                - google
                - microsoft
            emailAddress:
              type: string
              format: email
        notes:
          type: string
          description: Notes or description for the workspace.
        created:
          type: string
          format: date-time
          description: Date and time the workspace was created.
        lastModified:
          type: string
          format: date-time
          description: Date and time the workspace was last modified.
    CreateWorkspaceRequest:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
          description: Display name of the workspace.
        orgId:
          type: string
          description: Organization ID.
        workspaceLocationId:
          type: string
          description: Location ID.
        floorId:
          type: string
          description: Floor ID.
        capacity:
          type: integer
          description: Workspace capacity.
        type:
          type: string
          description: Workspace type.
          enum:
            - notSet
            - focus
            - huddle
            - meetingRoom
            - open
            - desk
            - other
        calling:
          type: object
          description: Calling configuration.
          properties:
            type:
              type: string
              enum:
                - freeCalling
                - hybridCalling
                - webexCalling
                - webexEdgeForDevices
                - none
        calendar:
          type: object
          description: Calendar configuration.
          properties:
            type:
              type: string
              enum:
                - none
                - google
                - microsoft
            emailAddress:
              type: string
              format: email
        notes:
          type: string
          description: Notes for the workspace.
    UpdateWorkspaceRequest:
      type: object
      properties:
        displayName:
          type: string
          description: Updated display name.
        workspaceLocationId:
          type: string
          description: Updated location ID.
        floorId:
          type: string
          description: Updated floor ID.
        capacity:
          type: integer
          description: Updated capacity.
        type:
          type: string
          description: Updated workspace type.
          enum:
            - notSet
            - focus
            - huddle
            - meetingRoom
            - open
            - desk
            - other
        calling:
          type: object
          description: Updated calling configuration.
          properties:
            type:
              type: string
              enum:
                - freeCalling
                - hybridCalling
                - webexCalling
                - webexEdgeForDevices
                - none
        calendar:
          type: object
          description: Updated calendar configuration.
          properties:
            type:
              type: string
              enum:
                - none
                - google
                - microsoft
            emailAddress:
              type: string
              format: email
        notes:
          type: string
          description: Updated notes.