Cisco Expressway Calls API

openapi: 3.1.0
info:
  title: Cisco Expressway Configuration Admin Account Calls API
  description: RESTful API for configuring and managing Cisco Expressway systems including zones, search rules, transforms, DNS servers, NTP servers, SFTP configuration, system upgrades, and admin account management. The API uses JSON Schema version 4 for request and response schemas and is self-documented via RAML definitions available at /api/raml on the Expressway system. All endpoints require HTTPS and HTTP Basic Authentication using Expressway administrator credentials.
  version: 14.2.0
  contact:
    name: Cisco TAC
    email: tac@cisco.com
    url: https://www.cisco.com/c/en/us/support/unified-communications/expressway-series/tsd-products-support-series-home.html
  license:
    name: Cisco EULA
    url: https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html
  x-logo:
    url: https://www.cisco.com/c/dam/en/us/products/collateral/unified-communications/expressway-series/datasheet-c78-733751.jpg
servers:
- url: https://{host}/api
  description: Cisco Expressway server
  variables:
    host:
      default: expressway.example.com
      description: The FQDN or IP address of the Cisco Expressway node. The API is only accessible via HTTPS.
security:
- basicAuth: []
tags:
- name: Calls
  description: Active and historical call information
paths:
  /status/common/calls:
    get:
      operationId: listActiveCalls
      summary: Cisco Expressway List all active calls
      description: Retrieves the list of all currently active calls on the Expressway including source and destination endpoints, call type, protocol, duration, and bandwidth usage. Active calls are displayed with component-level details for interworked calls.
      tags:
      - Calls
      responses:
        '200':
          description: Active call list retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActiveCall'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /status/common/callhistory:
    get:
      operationId: getCallHistory
      summary: Cisco Expressway Retrieve call history
      description: Returns the call history for the Expressway limited to the most recent 500 calls or fewer if calls used multiple components. Each record includes start and end times, duration, source and destination aliases, call type, protocol, and status. Supports filtering by time interval and custom field filters.
      tags:
      - Calls
      parameters:
      - name: filter
        in: query
        required: false
        description: Filter type for call history records. Supported values include get_all_records, get_records_for_interval, get_records_for_filter, and get_all_csv_records.
        schema:
          type: string
          enum:
          - get_all_records
          - get_records_for_interval
          - get_records_for_filter
          - get_all_csv_records
      - name: start_time
        in: query
        required: false
        description: Start time for interval-based filtering in ISO 8601 format. Used with get_records_for_interval.
        schema:
          type: string
          format: date-time
      - name: end_time
        in: query
        required: false
        description: End time for interval-based filtering in ISO 8601 format. Used with get_records_for_interval.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Call history retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CallHistoryRecord'
            text/csv:
              schema:
                type: string
                description: CSV-formatted call history records when using get_all_csv_records filter
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    ActiveCall:
      type: object
      description: An active call on the Expressway
      properties:
        CallId:
          type: string
          description: Unique identifier for the call
        StartTime:
          type: string
          format: date-time
          description: Timestamp when the call started
        Duration:
          type: integer
          description: Current call duration in seconds
        SourceAlias:
          type: string
          description: Alias of the calling endpoint
          examples:
          - user1@example.com
        DestinationAlias:
          type: string
          description: Alias of the called endpoint
          examples:
          - user2@example.com
        CallType:
          type: string
          description: Type of call based on protocol
          enum:
          - SIP
          - H.323
          - Interworked
        SIPVariant:
          type: string
          description: SIP variant for SIP-based calls
          enum:
          - Standard
          - Microsoft AV
          - Microsoft SIP IM&P
        Protocol:
          type: string
          description: Protocols involved in the call
          examples:
          - SIP
        Bandwidth:
          type: integer
          description: Current bandwidth usage in kbps
        SourceZone:
          type: string
          description: Zone where the call originated
        DestinationZone:
          type: string
          description: Zone where the call terminates
        Encrypted:
          type: boolean
          description: Whether media encryption is active
        ClusterPeer:
          type: string
          description: Cluster node handling this call
    Error:
      type: object
      description: Standard error response from the Expressway API
      properties:
        error:
          type: string
          description: Error code or type
        message:
          type: string
          description: Human-readable error description
    CallHistoryRecord:
      type: object
      description: A completed call record from the call history. The history is limited to the most recent 500 calls or fewer if calls used multiple components.
      properties:
        CallId:
          type: string
          description: Unique identifier for the call
        StartTime:
          type: string
          format: date-time
          description: Timestamp when the call started
        EndTime:
          type: string
          format: date-time
          description: Timestamp when the call ended
        Duration:
          type: integer
          description: Call duration in seconds
        SourceAlias:
          type: string
          description: Alias of the calling endpoint
        DestinationAlias:
          type: string
          description: Alias of the called endpoint (may be transformed)
        CallType:
          type: string
          description: Type of call based on protocol
          enum:
          - SIP
          - H.323
          - Interworked
        Protocol:
          type: string
          description: Protocols involved in the call
        Status:
          type: string
          description: Call outcome or disconnection reason
          examples:
          - Completed
          - Failed
          - Rejected
        DisconnectReason:
          type: string
          description: Reason for call disconnection
        ClusterPeer:
          type: string
          description: Cluster node that handled this call
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid. The API requires HTTP Basic Authentication with administrator credentials over HTTPS.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated user does not have sufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Expressway administrator credentials. The API is only accessible via HTTPS.
externalDocs:
  description: Cisco Expressway REST API Summary Guide (X14.2)
  url: https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/expressway/admin_guide/X14-2/rest-api/exwy_b_cisco-expressway-rest-api-summary-guide--x142/exwy_m_using-the-expressway-rest-api.html