AgentLine Calls API

openapi: 3.2.0
info:
  title: Agentline Cloud Calls API
  version: 0.3.0
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  description: 'Operations tagged Calls across 2 of this provider''s published API definitions: agentline.cloud_openapi.json, agentline-cloud-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentline.cloud
  description: Production
tags:
- name: Calls
paths:
  /v1/calls:
    post:
      tags:
      - Calls
      summary: Create Call
      description: 'Make an outbound phone call from your AI agent.


        Dials a real person or business from the agent''s number. The agent holds

        the whole conversation on its own with its system prompt, voice and

        greeting (or this call''s overrides). The call reaches a third party and

        is billed to the account at $0.12 per minute, first minute charged in

        full, so confirm with the user first. Not idempotent: every successful

        call dials again.


        Prerequisites: an agent with an active number from buy_phone_number

        (HTTP 400 otherwise), plus remaining subscription minutes or at least

        $0.50 of wallet balance (HTTP 402 otherwise). Included minutes are used

        first; only uncovered call time is charged to the wallet.


        Returns right after dialing with the call id (call_...), agent_id,

        from_number, to_number, direction, status and started_at; the call runs

        on its own. Check get_call_details for progress and call

        get_call_transcript once status is completed.'
      operationId: make_outbound_call
      security:
      - API Key or OAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - calls
      x-fern-sdk-method-name: create
    get:
      tags:
      - Calls
      summary: List Calls
      description: 'List voice calls made by your AI agents.


        Returns call history with optional filters by agent or status.

        Each entry includes direction (inbound/outbound), duration,

        phone numbers, and current status.


        Filters:

        - agent_id: only calls for a specific AI agent

        - status: "initiated", "in-progress", "completed", or "failed"'
      operationId: list_calls
      security:
      - API Key or OAuth: []
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter calls by AI agent ID
          title: Agent Id
        description: Filter calls by AI agent ID
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by call status: ''initiated'', ''in-progress'', ''completed'', or ''failed'''
          title: Status
        description: 'Filter by call status: ''initiated'', ''in-progress'', ''completed'', or ''failed'''
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of calls to return (1-200)
          default: 50
          title: Limit
        description: Maximum number of calls to return (1-200)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of calls to skip for pagination
          default: 0
          title: Offset
        description: Number of calls to skip for pagination
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - calls
      x-fern-sdk-method-name: list
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/calls/{call_id}:
    get:
      tags:
      - Calls
      summary: Get Call
      description: 'Get full details of a specific voice call.


        Returns the call''s metadata including direction, phone numbers,

        status, duration, AI agent configuration used, and the full

        conversation transcript between the AI agent and the caller.'
      operationId: get_call_details
      security:
      - API Key or OAuth: []
      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'
      x-fern-sdk-group-name:
      - calls
      x-fern-sdk-method-name: get
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/calls/{call_id}/context:
    post:
      tags:
      - Calls
      summary: Push Call Context
      description: 'Push context into a LIVE relay-mode call (mid-call context injection).


        This is the required way for backend agents (Hermes, OpenClaw, etc.) to

        answer a live caller after a ``call.utterance`` event. Do your work, then

        POST short facts, not a script. Include ``disposition``.

        ``progress`` adds a note and keeps the caller on hold with canned lines; the text is not spoken, and the turn stays open.

        ``done`` (the default), ``facts``, and ``failed`` close the turn. The hosted voice rephrases the facts in one or two sentences. It does not read your text aloud.

        ``noop`` closes the turn with no facts.

        You receive this request only for something

        the hosted voice does not know. Poll ``GET /v1/calls/{call_id}`` for updates.


        AUTHENTICATION (one of):

        1. **Push token** (preferred — no API key): the ``push_token`` from the

        ``call.utterance`` payload, via ``X-Push-Token`` header, ``?token=``

        query param, or ``push_token`` body field.

        2. **Bearer API key**: ``Authorization: Bearer al_live_...`` for the

        account that owns the call.


        Body — any of these keys works (``context`` is canonical):

        {"context": "John emailed yesterday about an invoice."}


        Other accepted keys: ``summary``, ``answer``, ``response``, ``reply``,

        ``text``, ``result``.


        Every response must include the exact ``turn_id`` from ``call.utterance``.

        Late context is rejected instead of being applied to another question.


        Returns:

        delivered=true, status="live" — accepted for this turn

        delivered=true, status="duplicate" — identical retry already accepted

        HTTP 409 — turn is stale/cancelled

        HTTP 410 — **call has ended.** STOP working

        on this request and abandon any in-flight lookup.'
      operationId: push_call_context
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      - name: token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Push token (alt to X-Push-Token header / body).
          title: Token
        description: Push token (alt to X-Push-Token header / body).
      - name: turn_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Turn ID from call.utterance.
          title: Turn Id
        description: Turn ID from call.utterance.
      - name: X-Push-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Push-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - calls
      x-fern-sdk-method-name: push_context
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/calls/{call_id}/hangup:
    post:
      tags:
      - Calls
      summary: Hangup Call
      description: 'Hang up an active phone call.


        Programmatically terminates an in-progress voice call. Use this

        when the AI agent needs to end the conversation, or to force-stop

        a call that is no longer needed. The call''s final transcript and

        billing are processed automatically after hangup.'
      operationId: hangup_call
      security:
      - API Key or OAuth: []
      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'
      x-fern-sdk-group-name:
      - calls
      x-fern-sdk-method-name: hangup
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/calls/{call_id}/transcript:
    get:
      tags:
      - Calls
      summary: Get Transcript
      description: 'Get the full conversation transcript for a call.


        Returns the complete speech-to-text transcript of the phone call,

        with each turn labeled by role ("human" for the caller, "agent"

        for the AI agent). The call.utterance conversation field uses user and assistant instead. Useful for reviewing what was said on the call,

        extracting information, or auditing AI agent behavior.'
      operationId: get_call_transcript
      security:
      - API Key or OAuth: []
      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'
      x-fern-sdk-group-name:
      - calls
      x-fern-sdk-method-name: get_transcript
    servers:
    - url: https://api.agentline.cloud
      description: Production
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CallRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: ID of the AI agent making the call (e.g. 'agt_abc123')
        to_number:
          type: string
          title: To Number
          description: Destination phone number in E.164 format (e.g. '+12125551234')
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
          description: Per-call system prompt override. Replaces the agent's default prompt for this call ONLY. If omitted, the agent's default system_prompt is used.
        initial_greeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Initial Greeting
          description: Per-call greeting override. Replaces the agent's default greeting for this call ONLY. If omitted, the agent's default initial_greeting is used.
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
          description: 'Override the TTS voice for this call: preset name (e.g. ''female-1'') or Cartesia UUID'
        from_number_id:
          anyOf:
          - type: string
          - type: 'null'
          title: From Number Id
          description: Specific phone number ID to call from; defaults to the agent's assigned number
      type: object
      required:
      - agent_id
      - to_number
      title: CallRequest
    CallContextPush:
      properties:
        context:
          anyOf:
          - type: string
          - type: 'null'
          title: Context
          description: The facts for the caller, in plain text, e.g. "John emailed yesterday about an invoice." The hosted voice rephrases them. Required unless disposition is noop.
        disposition:
          type: string
          enum:
          - partial
          - progress
          - done
          - failed
          - noop
          - facts
          title: Disposition
          description: 'What this push does with the open task. partial: one real fact so far, spoken now, task stays open. progress: a note for the voice, not spoken, task stays open. done (default): final facts, settles the task. failed: could not do it, settles the task. noop: settle the task with nothing to say; context not needed. facts: a briefing for the whole call at any time, no turn_id needed.'
          default: done
      additionalProperties: true
      type: object
      title: CallContextPush
      description: 'Body of push_call_context. Extra keys are accepted for runtime SDKs

        that send context under another name; MCP clients use these two.'
    CallRequest_2:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: ID of the AI agent making the call (e.g. 'agt_abc123')
        to_number:
          type: string
          pattern: ^\+[1-9]\d{7,14}$
          title: To Number
          description: Destination phone number in E.164 format (e.g. '+12125551234')
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
          description: Per-call system prompt override. Replaces the agent's default prompt for this call ONLY. If omitted, the agent's default system_prompt is used.
        initial_greeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Initial Greeting
          description: Per-call greeting override. Replaces the agent's default greeting for this call ONLY. If omitted, the agent's default initial_greeting is used.
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
          description: 'Override the TTS voice for this call: preset name (e.g. ''female-1'') or a voice UUID'
        from_number_id:
          anyOf:
          - type: string
          - type: 'null'
          title: From Number Id
          description: Specific phone number ID to call from; defaults to the agent's assigned number
      type: object
      required:
      - agent_id
      - to_number
      title: CallRequest
  securitySchemes:
    API_Key_or_OAuth:
      type: http
      description: 'AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).'
      scheme: bearer
      bearerFormat: API key (al_live_...)
      x-fern-bearer:
        name: apiKey
        env: AGENTLINE_API_KEY
x-refined-from:
- agentline.cloud_openapi.json
- agentline-cloud-openapi.json