openapi: 3.1.0
info:
  title: Cisco Webex Devices API
  description: >-
    Manage and control Webex devices and room systems. Provides endpoints
    for listing, creating, and managing device configurations, activations,
    and workspace assignments.
  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: Devices
    description: Operations for managing Webex devices
paths:
  /devices:
    get:
      operationId: listDevices
      summary: Cisco Webex List Devices
      description: >-
        Lists all devices associated with the authenticated user or
        organization. Supports filtering by person, workspace, display name,
        product, and other criteria.
      tags:
        - Devices
      parameters:
        - name: personId
          in: query
          description: Filter by person ID who owns the device.
          schema:
            type: string
        - name: workspaceId
          in: query
          description: Filter by workspace ID where the device is assigned.
          schema:
            type: string
        - name: displayName
          in: query
          description: Filter by device display name.
          schema:
            type: string
        - name: product
          in: query
          description: Filter by device product name.
          schema:
            type: string
        - name: type
          in: query
          description: Filter by device type.
          schema:
            type: string
        - name: tag
          in: query
          description: Filter by device tag.
          schema:
            type: string
        - name: connectionStatus
          in: query
          description: Filter by device connection status.
          schema:
            type: string
            enum:
              - connected
              - disconnected
              - connected_with_issues
        - name: serial
          in: query
          description: Filter by device serial number.
          schema:
            type: string
        - name: software
          in: query
          description: Filter by software version.
          schema:
            type: string
        - name: upgradeChannel
          in: query
          description: Filter by upgrade channel.
          schema:
            type: string
        - name: errorCode
          in: query
          description: Filter by error code.
          schema:
            type: string
        - name: capability
          in: query
          description: Filter by device capability.
          schema:
            type: string
        - name: permission
          in: query
          description: Filter by device permission.
          schema:
            type: string
        - 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 devices to return (default 100).
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response with list of devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized - invalid or missing access token.
    post:
      operationId: createDevice
      summary: Cisco Webex Create a Device Activation Code
      description: >-
        Creates a device activation code for onboarding a new device to a
        person or workspace. The activation code is used to register the
        device with Webex.
      tags:
        - Devices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeviceRequest'
      responses:
        '200':
          description: Device activation code created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceActivation'
        '400':
          description: Bad request - invalid input parameters.
        '401':
          description: Unauthorized - invalid or missing access token.
  /devices/{deviceId}:
    get:
      operationId: getDeviceDetails
      summary: Cisco Webex Get Device Details
      description: >-
        Shows details for a device by ID. Returns configuration, status,
        and metadata for the device.
      tags:
        - Devices
      parameters:
        - name: deviceId
          in: path
          required: true
          description: Unique identifier for the device.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with device details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          description: Device not found.
    put:
      operationId: updateDevice
      summary: Cisco Webex Update a Device
      description: >-
        Updates details for a device by ID. Allows modifying display name,
        upgrade channel, and other device properties.
      tags:
        - Devices
      parameters:
        - name: deviceId
          in: path
          required: true
          description: Unique identifier for the device.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDeviceRequest'
      responses:
        '200':
          description: Device updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '400':
          description: Bad request - invalid input parameters.
        '404':
          description: Device not found.
    delete:
      operationId: deleteDevice
      summary: Cisco Webex Delete a Device
      description: >-
        Deletes a device by ID. The device is removed from the organization
        and must be re-activated to rejoin.
      tags:
        - Devices
      parameters:
        - name: deviceId
          in: path
          required: true
          description: Unique identifier for the device.
          schema:
            type: string
      responses:
        '204':
          description: Device deleted successfully.
        '404':
          description: Device not found.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Webex API access token. Obtain via OAuth 2.0 authorization flow or
        personal access token from developer.webex.com.
  schemas:
    Device:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the device.
        displayName:
          type: string
          description: Display name of the device.
        workspaceId:
          type: string
          description: Workspace ID the device is assigned to.
        personId:
          type: string
          description: Person ID the device is assigned to.
        orgId:
          type: string
          description: Organization ID the device belongs to.
        capabilities:
          type: array
          description: List of device capabilities.
          items:
            type: string
        permissions:
          type: array
          description: List of device permissions.
          items:
            type: string
        connectionStatus:
          type: string
          description: Current connection status.
          enum:
            - connected
            - disconnected
            - connected_with_issues
        product:
          type: string
          description: Product name of the device.
        type:
          type: string
          description: Device type.
        tags:
          type: array
          description: Tags assigned to the device.
          items:
            type: string
        ip:
          type: string
          description: IP address of the device.
        mac:
          type: string
          description: MAC address of the device.
        serial:
          type: string
          description: Serial number of the device.
        software:
          type: string
          description: Software version running on the device.
        upgradeChannel:
          type: string
          description: Upgrade channel for the device.
        primarySipUrl:
          type: string
          description: Primary SIP URL.
        sipUrls:
          type: array
          description: SIP URLs for the device.
          items:
            type: string
        errorCodes:
          type: array
          description: Error codes reported by the device.
          items:
            type: string
        created:
          type: string
          format: date-time
          description: Date and time the device was created.
        firstSeen:
          type: string
          format: date-time
          description: Date and time the device was first seen.
        lastSeen:
          type: string
          format: date-time
          description: Date and time the device was last seen.
    CreateDeviceRequest:
      type: object
      properties:
        personId:
          type: string
          description: Person ID to associate the device with.
        workspaceId:
          type: string
          description: Workspace ID to associate the device with.
        model:
          type: string
          description: Model of the device.
    UpdateDeviceRequest:
      type: object
      properties:
        displayName:
          type: string
          description: Updated display name for the device.
        upgradeChannel:
          type: string
          description: Updated upgrade channel.
        tags:
          type: array
          description: Updated tags for the device.
          items:
            type: string
    DeviceActivation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the device.
        code:
          type: string
          description: Activation code for the device.
        expiresAt:
          type: string
          format: date-time
          description: Expiration time for the activation code.