openapi: 3.0.0
info:
  title: Webex Admin Address Book Captures API
  version: 1.0.0
  description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Captures
paths:
  /v1/captures/query:
    post:
      tags:
      - Captures
      summary: List Captures
      description: Retrieve a list of Captures given a set of task IDs
      operationId: downloadMultiRecordingPath
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordingBodyParams'
      responses:
        '200':
          description: 'Returns Recording and Transcription details. If a provided taskId is not found for the specified organization, the API will return a 200 OK response with empty recording and transcription fields for that task.

            This behavior is intentional to allow partial results when multiple taskIds are provided; unmatched taskIds do not result in a 4xx error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadMultipleInteractionsResponse'
        '400':
          description: 'Error: urlExpiration should be greater than 0.'
        '401':
          description: Unauthorized, token is invalid
        '403':
          description: Forbidden From Accessing Resources
        '404':
          description: Not Found
        '429':
          description: Too many requests have been sent in a given amount of time and the request has been rate limited
        '500':
          description: An Unexpected Error Occurred
components:
  schemas:
    TranscriptMulti:
      type: object
      properties:
        Source:
          type: string
          description: Source of the transcription
          example: recording|chat|sms etc.
        Provider:
          type: string
          description: Provider of the generated transcription
          example: CISCO
        id:
          type: string
          description: 'Voice Channel Transcript: Ccai ConfigId, Digital Channel Transcript: Conversation Id'
          example: cfg-id-101|CSRKT4K37D9OM2567
        fileName:
          type: string
          description: The file name of the transcript.
          example: voiceTranscript.json|emailTranscript.json|facebookTranscript.json etc.
        filePath:
          type: string
          description: Capture download url. Please refer [Transcript Details Guide](/docs/digital-transcript-json-details) for more details.
          example: https://cjp-ccone-devus1-media-storage-recording.s3.amazonaws.com/9e4895c9-787b-4615-b15f-f1b3b12c3091/
        startTime:
          type: string
          description: Begin time of capture(epoch timestamp)
          example: '1617373126000'
        languageCode:
          type: string
          description: Language of the transcript
          example: en-US
        createTime:
          type: string
          description: Create time of capture(epoch timestamp)
          example: '1617373126000'
    RecordingQuery:
      required:
      - taskIds
      type: object
      properties:
        orgId:
          type: string
          description: Organization ID to use for this operation. If unspecified, inferred from token. Token must have permission to interact with this organization.
          example: 8e18afdf-db79-449b-b4f5-ee4f14d9f45e
        urlExpiration:
          maximum: 60
          type: integer
          description: Expiration time of returned s3 url (in minutes).
          format: int32
          example: 30
        taskIds:
          maxItems: 10
          uniqueItems: true
          type: array
          description: Comma separated list of taskIds to gather captures for. Maximum number of taskIds allowed are 10
          example:
          - 8e18afdf-db79-449b-b4f5-ee4f14d9f45e
          items:
            type: string
            format: uuid
        includeSegments:
          type: boolean
          description: Flag; (true) for individual capture segments of main recording, (false) for a stitched capture.
          example: true
        includeVARecordings:
          type: boolean
          description: Flag; (true) for including virtual agent (VA) recordings, (false) for excluding virtual agent recordings. The default value is false.
          example: false
    RecordingAttributes:
      type: object
      properties:
        fileName:
          type: string
          description: The file name of the recording.
          example: recording-1.wav
        filePath:
          type: string
          description: Capture download url.
          example: https://cjp-ccone-devus1-media-storage-recording.s3.amazonaws.com/9e4895c9-787b-4615-b15f-f1b3b12c3091/
        startTime:
          type: integer
          description: Begin time of capture(epoch timestamp)
          format: int64
          example: 1617373126000
        stopTime:
          type: integer
          description: End time of capture(epoch timestamp).
          format: int64
          example: 1627373126000
        participants:
          type: array
          description: Comma separated list of CI user Id (UUID) of agents, masked customer contact email/phone details and virtual agent id if any involved in the recording.
          example:
          - e890a591-63f0-4984-a8f2-00e631368fb4
          - +121****1219
          items:
            type: string
        channel1:
          type: string
          description: Caller - channel contains caller audio only, Agent - channel contains agent audio only for main call and its segments, VA - channel contains virtual agent audio only.
          example: Caller|Agent|VA
        channel2:
          type: string
          description: Agent if callType is consult. For main callType, Agent/Caller/VA/Others based on number of participants.
          example: Caller|Agent|VA|Others
        callType:
          type: string
          description: main if recording belongs to main call; consult if recording belongs to consult call; va-main if recording belongs to virtual agent in main call; va-consult if recording belongs to virtual agent in consult call.
          example: main|consult|va-main|va-consult
        sensitive:
          type: boolean
          description: Applicable only to virtual agent recordings. Flag; (true) indicates the virtual agent recording may contain sensitive information, (false) otherwise.
          example: true
    MultipleInteractionsRecording:
      required:
      - recording
      - transcription
      type: object
      properties:
        taskId:
          type: string
          description: The ID of the task.
          format: uuid
          example: e890a591-63f0-4984-a8f2-00e631368fb4
        recording:
          type: array
          items:
            $ref: '#/components/schemas/RecordingMulti'
        transcription:
          type: array
          items:
            $ref: '#/components/schemas/TranscriptMulti'
    RecordingMulti:
      required:
      - attributes
      type: object
      properties:
        id:
          type: string
          description: The ID of the recording.
          example: f1b130da-0cad-4d8b-91dd-7a3085440e89
        segment:
          type: boolean
          description: Flag; Indicates if this is the entire recording or only a segment of main recording. This flag will be always false for consult callType.
          example: true
        attributes:
          $ref: '#/components/schemas/RecordingAttributes'
    RecordingBodyParams:
      required:
      - query
      type: object
      properties:
        query:
          $ref: '#/components/schemas/RecordingQuery'
    DownloadMultipleInteractionsResponse:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/RecordingMetaData'
        data:
          type: array
          items:
            $ref: '#/components/schemas/MultipleInteractionsRecording'
    RecordingMetaData:
      type: object
      properties:
        orgId:
          type: string
          description: Organization ID used for this operation.
          format: uuid
          example: f1b130da-0cad-4d8b-91dd-7a3085440e89
        urlExpiration:
          type: integer
          description: Number of minutes (from now) when the signed url expires.
          format: int32
          example: 30
  securitySchemes:
    oauth2:
      flows:
        authorizationCode:
          authorizationUrl: /
          scopes: {}
          tokenUrl: /
      type: oauth2
    bearer-key:
      type: http
      description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN
      scheme: bearer
      bearerFormat: JWT
    bearerAuth:
      type: oauth2
      description: OAuth 2.0 Bearer token authentication
      flows:
        authorizationCode:
          authorizationUrl: https://webexapis.com/v1/authorize
          tokenUrl: https://webexapis.com/v1/access_token
          scopes:
            spark:applications_token: Create access tokens for Service Apps