InfiVoice Calls API

openapi: 3.2.0
info:
  title: InfiVoice REST Calls API
  description: Welcome to the InfiVoice REST API documentation. This API enables you to programmatically automate AI-powered voice communications at scale.
  version: 1.0.0
servers:
- url: /api/v1
  description: API v1
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Calls
  description: 'The Calls API allows you to trigger outbound calls, monitor active calls, and retrieve call history with transcripts and recordings.


    **Common Use Cases:**

    - Trigger individual calls to leads

    - Check call status and duration

    - Retrieve transcripts and AI summaries

    - Hang up active calls


    **Credit Usage:** Each call consumes credits based on duration (1 credit = 1 minute).'
paths:
  /calls:
    get:
      summary: List Calls
      description: 'Retrieve a paginated list of all calls made from your account. Results include calls from all telephony engines (ElevenLabs, Plivo, Twilio-OpenAI).


        **Tip:** Use the `page` and `pageSize` parameters to navigate through large result sets efficiently.


        **Required Scope:** `calls:read`'
      operationId: listCalls
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      responses:
        '200':
          description: List of calls with pagination metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      summary: Trigger Call
      description: 'Initiate an outbound call using a specified AI agent. The call will be placed immediately unless scheduled for a future time.


        **Prerequisites:**

        - An active AI agent (flow or incoming type)

        - Sufficient credits in your account

        - An active phone number (or provide `fromNumber`)


        **Telephony Engines:**

        - `elevenlabs` — Best voice quality, 29 languages

        - `plivo` — India/APAC optimized

        - `twilio-openai` — Global coverage


        **Required Scope:** `calls:write`'
      operationId: triggerCall
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerCallRequest'
            examples:
              basic:
                summary: Basic call
                value:
                  agentId: 550e8400-e29b-41d4-a716-446655440000
                  toNumber: '+14155551234'
              withEngine:
                summary: Specify engine
                value:
                  agentId: 550e8400-e29b-41d4-a716-446655440000
                  toNumber: '+14155551234'
                  engine: twilio-openai
                  fromNumber: '+14155559999'
      responses:
        '201':
          description: Call initiated successfully. Returns call ID and initial status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerCallResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          $ref: '#/components/responses/NotFound'
  /calls/{id}:
    get:
      summary: Get Call Details
      description: 'Retrieve detailed information about a specific call including:

        - Call status and duration

        - Full conversation transcript

        - AI-generated summary

        - Sentiment analysis

        - Recording URL (if available)


        **Tip:** Poll this endpoint to track call progress. Status will transition from `queued` → `ringing` → `in-progress` → `completed`.


        **Required Scope:** `calls:read`'
      operationId: getCall
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Complete call details with transcript and analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallDetailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /calls/{id}/hangup:
    post:
      summary: Hangup Call
      description: 'Terminate an active call immediately. Use this to end calls that are in progress.


        **Note:** This only works for calls with status `in-progress` or `ringing`. Completed or failed calls cannot be hung up.


        **Required Scope:** `calls:write`'
      operationId: hangupCall
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Hangup request accepted. Call will terminate shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HangupResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Call:
      type: object
      properties:
        id:
          type: string
          format: uuid
        engine:
          type: string
          enum:
          - elevenlabs
          - plivo
          - twilio-openai
        agentId:
          type: string
          format: uuid
        toNumber:
          type: string
        fromNumber:
          type: string
        status:
          type: string
          enum:
          - queued
          - ringing
          - in-progress
          - completed
          - failed
          - no-answer
          - busy
        duration:
          type: integer
          description: Duration in seconds
        creditsUsed:
          type: number
        transcript:
          type: string
        aiSummary:
          type: string
        recordingUrl:
          type: string
        sentiment:
          type: string
        createdAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
    CallDetailResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Call'
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
    PaginationMeta:
      allOf:
      - $ref: '#/components/schemas/Meta'
      - type: object
        properties:
          pagination:
            type: object
            properties:
              page:
                type: integer
              pageSize:
                type: integer
              totalItems:
                type: integer
              totalPages:
                type: integer
              hasNext:
                type: boolean
              hasPrev:
                type: boolean
    CallListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    HangupResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            callId:
              type: string
            status:
              type: string
              example: hangup_requested
            message:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
    TriggerCallRequest:
      type: object
      required:
      - agentId
      - toNumber
      properties:
        agentId:
          type: string
          format: uuid
          description: ID of the agent to use for the call
        toNumber:
          type: string
          description: Phone number to call (E.164 format recommended)
          example: '+14155551234'
        fromNumber:
          type: string
          description: Caller ID phone number (optional, uses default if not provided)
        engine:
          type: string
          enum:
          - elevenlabs
          - plivo
          - twilio-openai
          description: Telephony engine to use
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom metadata to attach to the call
        scheduledAt:
          type: string
          format: date-time
          description: Schedule call for a future time
    TriggerCallResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            callId:
              type: string
              format: uuid
            status:
              type: string
              example: queued
            agentId:
              type: string
              format: uuid
            toNumber:
              type: string
            fromNumber:
              type: string
            engine:
              type: string
            createdAt:
              type: string
              format: date-time
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientCredits:
      description: Insufficient credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    PageSizeParam:
      name: pageSize
      in: query
      description: Items per page (max 100)
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    PageParam:
      name: page
      in: query
      description: Page number (1-indexed)
      schema:
        type: integer
        default: 1
        minimum: 1
    IdParam:
      name: id
      in: path
      required: true
      description: Resource UUID
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token (API key)