AgentPhone Calls API

openapi: 3.2.0
info:
  title: SMS Calls API
  description: A simple API to provision phone numbers and receive SMS
  version: 0.1.0
tags:
- name: Calls
paths:
  /v1/calls:
    get:
      tags:
      - Calls
      summary: List Calls
      description: List all calls for this account.
      operationId: list_calls_v1_calls_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by status: completed, in-progress, failed'
          title: Status
        description: 'Filter by status: completed, in-progress, failed'
      - name: direction
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by direction: inbound, outbound'
          title: Direction
        description: 'Filter by direction: inbound, outbound'
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by type: pstn, web'
          title: Type
        description: 'Filter by type: pstn, web'
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search fromNumber or toNumber (contains)
          title: Search
        description: Search fromNumber or toNumber (contains)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Calls
      summary: Create Outbound Call
      description: 'Initiate an outbound call.


        This endpoint allows you to programmatically make phone calls from your agent

        to any phone number. Use `fromNumberId` to pick which of the agent''s numbers

        to use as caller ID; if omitted, the first assigned number is used.


        Flow:

        1. Validates the agent belongs to your account and has a phone number

        2. Initiates a call from the agent''s number to the destination

        3. When recipient answers, speaks the initial greeting (if provided)

        4. Listens for recipient''s speech and sends to your webhook

        5. Continues conversation using your webhook responses'
      operationId: create_outbound_call_v1_calls_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOutboundCallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/web:
    post:
      tags:
      - Calls
      summary: Create Web Call
      description: 'Create a browser-based web call.


        Returns an access token that your frontend passes to the AgentPhone Web SDK

        (`agentphone-web-sdk`) to start the call in the browser. The token

        expires 30 seconds after creation.


        Flow:

        1. Validates the agent belongs to your account

        2. Creates a web call and returns an access token

        3. Your client calls `webClient.startCall({ accessToken })` to connect

        4. Call lifecycle (transcripts, webhooks) works the same as phone calls'
      operationId: create_web_call_v1_calls_web_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebCallRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v1/calls/{call_id}:
    get:
      tags:
      - Calls
      summary: Get Call
      description: Get a specific call with its transcripts.
      operationId: get_call_v1_calls__call_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/end:
    post:
      tags:
      - Calls
      summary: End Call
      description: 'Terminate an ongoing call.


        Works for both hosted-mode and webhook-mode calls. The call_ended

        webhook from the voice provider updates status/endedAt asynchronously,

        so this endpoint returns the current call as soon as the stop request

        is accepted upstream.'
      operationId: end_call_v1_calls__call_id__end_post
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/recording:
    get:
      tags:
      - Calls
      summary: Get Call Recording
      description: 'Stream the audio recording for a specific call. Public bearer-link endpoint.


        Forwards the browser''s Range request upstream and passes the partial response

        (206 + Content-Range) back through, so the element can seek — without

        it, clicking a timestamp does nothing because the browser can''t fetch a byte

        range.'
      operationId: get_call_recording_v1_calls__call_id__recording_get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/transcript:
    get:
      tags:
      - Calls
      summary: Get Call Transcript
      description: 'Get the full transcript for a call.


        Returns the complete, ordered transcript regardless of the webhook

        contextLimit setting. Each entry contains the user utterance and

        the corresponding agent response (when available).'
      operationId: get_call_transcript_v1_calls__call_id__transcript_get
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/transcript/stream:
    get:
      tags:
      - Calls
      summary: Stream Call Transcript
      description: 'Stream a call''s transcript via Server-Sent Events.


        On connect the server replays all existing transcript turns from the

        database, then streams new turns in real time as they arrive from the

        voice provider. A ``: heartbeat`` comment is sent every 15 s to keep

        proxies alive. The stream closes after sending an ``ended`` event

        when the call completes (or immediately after replay if the call has

        already ended).


        Works for both live and completed calls — same URL either way.'
      operationId: stream_call_transcript_v1_calls__call_id__transcript_stream_get
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/{number_id}/calls:
    get:
      tags:
      - Calls
      summary: List Calls For Number
      description: List all calls for a specific phone number.
      operationId: list_calls_for_number_v1_numbers__number_id__calls_get
      security:
      - HTTPBearer: []
      parameters:
      - name: number_id
        in: path
        required: true
        schema:
          type: string
          title: Number Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateWebCallRequest:
      properties:
        agentId:
          type: string
          title: Agentid
          description: Agent ID to start the web call with
        metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: Metadata
          description: Optional metadata to attach to the call
        variables:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Variables
          description: Optional per-call dynamic variables. Values are substituted into ``{{var_name}}`` placeholders in the agent's system prompt and begin message at call time. Requires a hosted-mode agent.
      type: object
      required:
      - agentId
      title: CreateWebCallRequest
      description: Request model for creating a browser-based web call.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateOutboundCallRequest:
      properties:
        agentId:
          type: string
          title: Agentid
          description: Agent ID to make the call from
        toNumber:
          type: string
          title: Tonumber
          description: Phone number to call (E.164 format)
        fromNumberId:
          anyOf:
          - type: string
          - type: 'null'
          title: Fromnumberid
          description: Optional phone number ID to use as caller ID. Must belong to the agent. If omitted, the agent's first assigned number is used.
        initialGreeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Initialgreeting
          description: Optional initial greeting to speak when recipient answers. Pass an empty string to have the agent stay silent and wait for the recipient to speak first.
        voice:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice
          description: Voice ID override for this call (uses agent's configured voice if omitted)
        systemPrompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Systemprompt
          description: When provided, uses a built-in LLM for the conversation instead of forwarding to a webhook. The prompt defines the AI's personality and conversation topic.
        modelTier:
          anyOf:
          - type: string
          - type: 'null'
          enum:
          - turbo
          - balanced
          - max
          - realtime
          title: Modeltier
          description: Optional model tier override for this call's built-in conversation. Only applies when ``systemPrompt`` is provided; defaults to the agent's configured modelTier.
        variables:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Variables
          description: Optional per-call dynamic variables. Values are substituted into ``{{var_name}}`` placeholders in the agent's system prompt and initial greeting at call time. Requires either ``systemPrompt`` or a hosted-mode agent.
        callScreeningIdentity:
          anyOf:
          - type: string
          - type: 'null'
          title: Callscreeningidentity
          description: 'For outbound calls that hit an automated call screener (e.g. iOS 26 Call Screening or Android Call Screen): the identity the agent gives when asked who is calling. Overrides the agent''s stored default for this call. Both identity and purpose are required to enable screening; if only a purpose is set, the agent''s name is used.'
        callScreeningPurpose:
          anyOf:
          - type: string
          - type: 'null'
          title: Callscreeningpurpose
          description: 'For outbound calls that hit an automated call screener: the purpose the agent gives when asked why it is calling. Overrides the agent''s stored default for this call.'
        disableRecording:
          type: boolean
          title: Disablerecording
          description: When true, no audio recording is stored for this call. The transcript is still captured and available via the transcript endpoints and the agent.call_ended webhook. Useful for calls where a party has not consented to being recorded (e.g. two-party consent states).
          default: false
      type: object
      required:
      - agentId
      - toNumber
      title: CreateOutboundCallRequest
      description: Request model for creating an outbound call.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer