Call2Me Calls API

openapi: 3.2.0
info:
  title: Call2Me Calls API
  description: '# Call2Me Voice AI Platform API


    Programmatic interface to build, deploy and operate voice AI agents that can place

    and receive phone calls in real time. Designed to be consumed by humans **and** by

    AI agent frameworks (function-calling LLMs, MCP servers, automation platforms like

    Composio, Pipedream, Zapier, n8n).


    ## What you can do


    - **Place outbound calls** — give an agent a phone number to dial; the AI handles

    the conversation end-to-end and returns a transcript + recording.

    - **Manage AI agents** — create personalities, attach voices, system prompts,

    knowledge bases and post-call actions.

    - **Schedule calls** — one-shot or recurring (cron-like) outbound calls.

    - **Knowledge base (RAG)** — upload documents/URLs so the agent answers from your

    data with reduced hallucination.

    - **Inbound** — provision phone numbers that route to your agents.


    ## Common LLM tool-calling use cases


    | Goal | Endpoint |

    |------|----------|

    | "Call this person and read them this script" | `POST /v1/calls` |

    | "Schedule a follow-up tomorrow at 14:00" | `POST /v1/schedules` |

    | "Get the transcript of last call" | `GET /v1/calls/{id}` |

    | "Add this PDF to the agent''s brain" | `POST /v1/knowledge-base/{id}/sources` |


    ## Authentication


    Every request requires a Bearer token issued from the dashboard:


    ```

    Authorization: Bearer c2m_sk_xxxxxxxxxxxxxxxx

    ```


    Get your API key from the API Keys page.

    Keys are scoped per-workspace and can be rotated/revoked any time.


    ## Rate Limits


    | Plan | Requests/min | Concurrent Calls |

    |------|-------------|------------------|

    | Free | 60 | 1 |

    | Pro | 600 | 10 |

    | Enterprise | Unlimited | Unlimited |


    ## SDKs & Integrations


    - Python SDK

    - Node.js SDK

    - OpenAPI 3.1 spec: `/openapi.json` (use it to generate clients or register the

    service with AI tool platforms)


    ## Support


    - Email: support@call2me.app

    - Docs: https://docs.call2me.app

    - Discord: https://discord.gg/call2me'
  version: 1.0.0
  x-logo:
    url: https://call2me.app/logo.png
    altText: Call2Me Logo
  contact:
    name: Call2Me Support
    url: https://call2me.app/support
    email: support@call2me.app
  license:
    name: Commercial — see Terms of Service
    url: https://call2me.app/terms
  termsOfService: https://call2me.app/terms
servers:
- url: https://api.call2me.app
  description: Production
- url: http://localhost:8000
  description: Local Development
security:
- BearerAuth: []
tags:
- name: Calls
  description: Place outbound phone calls and inspect call history. `POST /v1/calls` starts an outbound call given an `agent_id`, a `from_number` and a `to_number`; the platform handles dialing, the AI conversation, recording and transcription. Use `GET /v1/calls/{id}` to retrieve the transcript, recording URL, status and post-call analysis.
  externalDocs:
    description: Learn more about calls
    url: https://docs.call2me.app/calls
paths:
  /v1/calls:
    post:
      tags:
      - Calls
      summary: Place an outbound call
      description: 'Initiate an outbound phone call. The platform will dial `to_number` from `from_number` (a phone number you own on this workspace), connect the configured AI agent, and begin a real-time voice conversation. The call is placed asynchronously — this endpoint returns immediately with `call_id` and `status=''queued''`; poll `GET /v1/calls/{id}` or subscribe to webhooks to track progress.


        **Required**: an active agent (`agent_id`) and a phone number assigned to your workspace (`from_number`). If `from_number` is omitted, the agent''s assigned phone number is used automatically.


        **Cost**: deducted from your wallet per minute of talk time. The request fails with `402` if balance is insufficient.'
      operationId: create_call_v1_calls_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/call2me_core__models__call__CreateCallRequest'
      responses:
        '201':
          description: Call queued for dialing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '400':
          description: No phone number assigned, demo number used for outbound, or other validation error.
        '402':
          description: Insufficient wallet balance.
        '404':
          description: Agent not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Calls
      summary: List calls
      description: List calls in this workspace, newest first. Supports filtering by `agent_id`, `status` (queued/active/completed/failed/canceled) and `direction` (outbound/inbound). Use `limit` and `offset` for pagination. To retrieve full call details (transcript, recording), call `GET /v1/calls/{id}` for a specific call.
      operationId: list_calls_v1_calls_get
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by agent.
          title: Agent Id
        description: Filter by agent.
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by status: queued, active, completed, failed, canceled.'
          title: Status
        description: 'Filter by status: queued, active, completed, failed, canceled.'
      - name: direction
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by direction: outbound or inbound.'
          title: Direction
        description: 'Filter by direction: outbound or inbound.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Page size.
          default: 100
          title: Limit
        description: Page size.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Pagination offset.
          default: 0
          title: Offset
        description: Pagination offset.
      responses:
        '200':
          description: Paginated list of calls with summary fields.
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/quality/report:
    get:
      tags:
      - Calls
      summary: Get Quality Report
      description: Get call quality report with aggregated metrics.
      operationId: get_quality_report_v1_calls_quality_report_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          default: 30
          title: Days
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent 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}:
    get:
      tags:
      - Calls
      summary: Get call details
      description: Retrieve a single call by ID. Returns the conversation transcript (speaker-attributed), recording URL (signed for download), call duration, disconnect reason, and any post-call analysis (sentiment, summary, function-call results). Use this endpoint after a call completes to feed transcript/summary back into your downstream workflow (CRM update, ticket creation, follow-up trigger).
      operationId: get_call_v1_calls__call_id__get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Full call object including transcript, recording URL, status and post-call analysis.
          content:
            application/json:
              schema: {}
        '404':
          description: Call not found in this workspace.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Calls
      summary: Delete a call record
      description: 'Permanently removes the call record (transcript, metadata, analysis) from this workspace. Note: the underlying recording file in object storage is **not** deleted automatically — request a separate recording purge if you need full erasure (e.g. GDPR right-to-be-forgotten requests).'
      operationId: delete_call_v1_calls__call_id__delete
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Confirmation message.
          content:
            application/json:
              schema: {}
        '404':
          description: Call not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/end:
    post:
      tags:
      - Calls
      summary: End an active call
      description: Forcefully terminate an ongoing call (e.g. when an automation decides the conversation should stop early). The call is marked `disconnection_reason='agent_hangup'`. Calls that are not currently `ongoing` cannot be ended this way.
      operationId: end_call_v1_calls__call_id__end_post
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: The updated call object with `call_status='ended'`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '400':
          description: Call is not in an ongoing state.
        '404':
          description: Call not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/recording:
    get:
      tags:
      - Calls
      summary: Get a signed URL for the call recording
      description: Generate a short-lived signed URL (1 hour) for the call's audio recording. Use this to download/stream the recording directly from object storage without exposing long-lived credentials. Suitable for embedding in QA dashboards, sentiment analysis pipelines, or compliance archival.
      operationId: get_recording_v1_calls__call_id__recording_get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: A temporary signed URL pointing to the audio recording (valid for 1 hour).
          content:
            application/json:
              schema: {}
        '404':
          description: Call or recording not found.
        '501':
          description: Object storage backend is not configured on this deployment.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/vcon:
    get:
      tags:
      - Calls
      summary: Export the call as a vCon container
      description: 'Export a completed call in the vCon standard format — a portable, self-contained record of the conversation holding the participants, the turn-by-turn dialog, the recording reference and the post-call analysis (summary, sentiment, custom extractions). Use it to hand conversation data to downstream systems without a proprietary shape. Opt-in per agent: enable `enable_vcon_export` on the agent first.'
      operationId: get_call_vcon_v1_calls__call_id__vcon_get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: 'The conversation as an IETF vCon JSON container (draft-ietf-vcon-vcon-container): parties, dialog and analysis.'
          content:
            application/json:
              schema: {}
        '404':
          description: Call not found, or vCon export is not enabled for its agent.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/live:
    get:
      tags:
      - Calls
      summary: Live transcript of an ongoing call
      description: Returns what has been said so far in a call — one item per completed caller/assistant turn — plus live events (instruction delivered, transfer, call ending), and the call's live status (`ringing`, `in_progress`, `ended`). Poll with `since` set to the previous response's `next_since` to get only new items. Turns appear when they are complete (not word by word). After the call ends the stored transcript is returned.
      operationId: get_live_transcript_v1_calls__call_id__live_get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      - name: since
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Return only items with seq greater than this.
          default: 0
          title: Since
        description: Return only items with seq greater than this.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Call not found in this workspace.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/calls/{call_id}/instruct:
    post:
      tags:
      - Calls
      summary: Send a live instruction to an ongoing call
      description: 'Steers a call that is in progress. **This affects the live conversation.** `note` adds guidance for the assistant (not spoken), `ask` makes it ask the caller something at the next pause, `say` makes it say a sentence (max 300 chars), `end` makes it say goodbye and hang up, `transfer` transfers to one of the assistant''s configured transfer targets (by name; free phone numbers are not accepted). Delivery is asynchronous: watch `GET /v1/calls/{call_id}/live` for the `instruction_applied` / `instruction_rejected` event. Max 10 instructions per call per minute.'
      operationId: instruct_call_v1_calls__call_id__instruct_post
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstructRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Call not found in this workspace.
        '409':
          description: The call is not in progress (or the assistant has left the room).
        '422':
          description: Invalid instruction (missing text, too long, unknown transfer target).
        '429':
          description: Too many instructions for this call.
components:
  schemas:
    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
    Call:
      properties:
        call_id:
          type: string
          pattern: ^(call|demo|test|interp|bridge)_[a-f0-9]{8,24}$
          title: Call Id
          description: Unique call identifier
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: Agent used for this call (tercüman/köprü aramalarında yok)
        call_status:
          type: string
          enum:
          - pending
          - ringing
          - in_progress
          - completed
          - failed
          - no_answer
          - busy
          - transferred
          - ended
          title: Call Status
          description: Current call status
        call_type:
          type: string
          enum:
          - inbound
          - outbound
          - sip_call
          - web_call
          - interpreter
          - phone_call
          - phone
          title: Call Type
          description: Call direction type
        direction:
          type: string
          enum:
          - inbound
          - outbound
          - web
          - web_bridge
          title: Direction
          description: Call direction
        from_number:
          anyOf:
          - type: string
          - type: 'null'
          title: From Number
          description: Caller phone number
        to_number:
          anyOf:
          - type: string
          - type: 'null'
          title: To Number
          description: Callee phone number
        start_timestamp:
          anyOf:
          - type: integer
          - type: 'null'
          title: Start Timestamp
          description: Unix timestamp in milliseconds when call started
        end_timestamp:
          anyOf:
          - type: integer
          - type: 'null'
          title: End Timestamp
          description: Unix timestamp in milliseconds when call ended
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
          description: Call duration in milliseconds
        transcript:
          anyOf:
          - type: string
          - type: 'null'
          title: Transcript
          description: Full transcript as text
        transcript_object:
          anyOf:
          - items:
              $ref: '#/components/schemas/TranscriptTurn'
            type: array
          - type: 'null'
          title: Transcript Object
          description: Structured transcript
        recording_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Recording Url
          description: URL to call recording
        disconnection_reason:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Disconnection Reason
          description: Reason the call ended (sabit kod ya da ajanın açıklaması)
        call_analysis:
          anyOf:
          - $ref: '#/components/schemas/CallAnalysis'
          - type: 'null'
          description: Post-call analysis
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Custom metadata
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Record creation time
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update time
      type: object
      required:
      - call_id
      - call_status
      - call_type
      - direction
      title: Call
      description: Complete call record.
    CallAnalysis:
      properties:
        call_successful:
          type: boolean
          title: Call Successful
          description: Whether the call achieved its goal
        call_summary:
          type: string
          title: Call Summary
          description: AI-generated summary of the call
        user_sentiment:
          anyOf:
          - type: string
            enum:
            - positive
            - neutral
            - negative
          - type: 'null'
          title: User Sentiment
          description: Overall user sentiment
        custom_analysis_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Custom Analysis Data
          description: Custom analysis results
      type: object
      required:
      - call_successful
      - call_summary
      title: CallAnalysis
      description: Post-call analysis results.
    InstructRequest:
      properties:
        type:
          type: string
          enum:
          - say
          - ask
          - note
          - end
          - transfer
          title: Type
          description: '`note`: guidance added to the assistant''s context (not spoken). `ask`: the assistant asks the caller this at the next natural pause. `say`: the assistant says this text (max 300 chars). `end`: the assistant says its farewell and hangs up. `transfer`: transfer to one of the assistant''s transfer targets.'
        text:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Text
          description: Required for say/ask/note.
        transfer_to:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Transfer To
          description: 'For transfer: the NAME of one of the assistant''s transfer targets. Arbitrary phone numbers are not accepted.'
      type: object
      required:
      - type
      title: InstructRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    call2me_core__models__call__CreateCallRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Agent to use for this call
        to_number:
          type: string
          pattern: ^\+[1-9]\d{1,14}$
          title: To Number
          description: E.164 format phone number to call
        from_number:
          anyOf:
          - type: string
            pattern: ^\+[1-9]\d{1,14}$
          - type: 'null'
          title: From Number
          description: Caller ID (must be owned by account)
        topic:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Topic
          description: Why this call is being placed. Reaches the agent as `call_purpose` and is woven into both the opening line and the system prompt, so the agent states its reason instead of a generic greeting.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Custom metadata for the call
        dynamic_variables:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Dynamic Variables
          description: Per-call values substituted into the agent's `{{placeholders}}` (system prompt, opening line, closing line). Up to 50 keys matching `^[A-Za-z_][A-Za-z0-9_]{0,63}$`; values are strings up to 1000 characters (numbers and booleans are converted to strings). Placeholders without a value are removed, never read aloud. The stored agent is not changed.
        begin_message:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Begin Message
          description: Exact opening sentence for THIS call (variables are substituted). Without it, outbound calls generate a direction-aware opening.
      type: object
      required:
      - agent_id
      - to_number
      title: CreateCallRequest
      description: Request to create an outbound call.
    TranscriptTurn:
      properties:
        role:
          type: string
          enum:
          - agent
          - user
          title: Role
          description: Speaker role
        text:
          type: string
          title: Text
          description: Spoken text (canlı veride `text` anahtarı)
        timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Timestamp
          description: ISO 8601 timestamp
      type: object
      required:
      - role
      - text
      title: TranscriptTurn
      description: 'Single turn in a conversation transcript.


        CANLI VERİ `text` ANAHTARI KULLANIYOR (ölçüldü 2 Eki 2026: incelenen 400

        transkript turunun 400''ünde `role` + `text`, `content` HİÇ YOK). Model

        `content` bekliyordu, dolayısıyla transkripti olan HİÇBİR arama

        `CallRepository.get()` ile okunamıyordu.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app