Call2Me Interpreters API

openapi: 3.2.0
info:
  title: Call2Me Interpreters 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: Interpreters
paths:
  /v1/interpreters:
    get:
      tags:
      - Interpreters
      summary: List Interpreters
      operationId: list_interpreters_v1_interpreters_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/InterpreterResponse'
                type: array
                title: Response List Interpreters V1 Interpreters Get
    post:
      tags:
      - Interpreters
      summary: Create Interpreter
      operationId: create_interpreter_v1_interpreters_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterpreterCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterpreterResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/calls:
    get:
      tags:
      - Interpreters
      summary: List Interpreter Calls
      description: 'Interpreted calls for this workspace, live ones first.


        Serves the panel''s monitoring list: who was rung, who was dialled, whether

        the two legs actually connected, and for how long. Interpreter rooms are

        identified by `call_type = ''interpreter''` (set at insert time in

        `start_interpreted_call`), so this never mixes in ordinary agent calls.


        `interpreter_id` narrows the list to one interpreter''s own calls (the

        per-interpreter detail page); it reads `metadata->>''interpreter_id''`,

        which only rows written since that field was added carry.


        `offset` + the returned `total` drive the panel''s pagination. `total` is

        counted under the same filters as the page itself, so the control never

        offers a page that would come back empty.'
      operationId: list_interpreter_calls_v1_interpreters_calls_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: active_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Active Only
      - name: interpreter_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Interpreter Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Interpreter Calls V1 Interpreters Calls Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}:
    get:
      tags:
      - Interpreters
      summary: Get Interpreter
      operationId: get_interpreter_v1_interpreters__interpreter_id__get
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterpreterResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Interpreters
      summary: Update Interpreter
      operationId: update_interpreter_v1_interpreters__interpreter_id__patch
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterpreterUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterpreterResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Interpreters
      summary: Delete Interpreter
      operationId: delete_interpreter_v1_interpreters__interpreter_id__delete
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/call:
    post:
      tags:
      - Interpreters
      summary: Start Interpreted Call
      operationId: start_interpreted_call_v1_interpreters__interpreter_id__call_post
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartCallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Start Interpreted Call V1 Interpreters  Interpreter Id  Call Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/call-quote:
    get:
      tags:
      - Interpreters
      summary: Interpreter Call Quote
      description: 'Bu hedefi aramanın dakika fiyatı — arama BAŞLATMAZ.


        `mode=web`: karma görüşme (sahibi tarayıcıdan, tek telefon bacağı).

        `mode=phone`: iki bacaklı /call (sahibin geri arama numarası da hesaba girer).

        Reddedilen hedef 4xx değil `allowed=false` + `reason` döner: panel numara

        yazılırken soruyor, her tuş bir hata kutusu açmamalı.'
      operationId: interpreter_call_quote_v1_interpreters__interpreter_id__call_quote_get
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      - name: target_number
        in: query
        required: true
        schema:
          type: string
          title: Target Number
      - name: mode
        in: query
        required: false
        schema:
          enum:
          - web
          - phone
          type: string
          default: web
          title: Mode
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Interpreter Call Quote V1 Interpreters  Interpreter Id  Call Quote Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/web-call:
    post:
      tags:
      - Interpreters
      summary: Start Mixed Interpreted Call
      description: 'Karma görüşme: sahibi tarayıcıdan katılır, hedef telefondan aranır.


        Oda + ajan burada (senkron) hazırlanır ve sahibine LiveKit token döner;

        hedef numara arka planda, sahibi odaya GİRDİKTEN sonra aranır. İki taraf

        bağlanınca normal iki-konuşmacı tercüme (solo DEĞİL). Sahibin dili

        `source_language`, hedefin `target_language`.'
      operationId: start_mixed_interpreted_call_v1_interpreters__interpreter_id__web_call_post
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartMixedCallRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Start Mixed Interpreted Call V1 Interpreters  Interpreter Id  Web Call Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/web:
    post:
      tags:
      - Interpreters
      summary: Configure Web
      description: Enable/disable the permanent address and its passcode requirement.
      operationId: configure_web_v1_interpreters__interpreter_id__web_post
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebConfigUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Configure Web V1 Interpreters  Interpreter Id  Web Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/web/passcodes:
    post:
      tags:
      - Interpreters
      summary: Mint Passcode
      description: 'Mint a single-use passcode for this interpreter''s address.


        Returned in clear exactly once — only its hash is stored, so it cannot

        be recovered later. The panel shows it to the owner to pass on.'
      operationId: mint_passcode_v1_interpreters__interpreter_id__web_passcodes_post
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Mint Passcode V1 Interpreters  Interpreter Id  Web Passcodes Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/web/end:
    post:
      tags:
      - Interpreters
      summary: End Web Session
      description: 'Owner-side kill switch for a live browser call.


        The address is shareable and the owner pays for whoever walks in, so

        they need a way to end a call they are not part of — a guest who leaves

        the tab open, or a conversation that should not be running. Deleting the

        LiveKit room is what actually disconnects people; closing our own rows

        without it would only hide a call that is still burning balance.'
      operationId: end_web_session_v1_interpreters__interpreter_id__web_end_post
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response End Web Session V1 Interpreters  Interpreter Id  Web End Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/interpreters/{interpreter_id}/web/live:
    get:
      tags:
      - Interpreters
      summary: Live Web Session
      description: 'What is happening on this interpreter''s address right now.


        Drives the panel''s live indicator: how many people are in, and since

        when. Returns a null session rather than 404 when nothing is live, so

        the panel can poll it without treating "quiet" as an error.'
      operationId: live_web_session_v1_interpreters__interpreter_id__web_live_get
      parameters:
      - name: interpreter_id
        in: path
        required: true
        schema:
          type: string
          title: Interpreter Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Live Web Session V1 Interpreters  Interpreter Id  Web Live Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/t/{slug}:
    get:
      tags:
      - Interpreters
      summary: Web Room Info
      description: 'Public: describe a room so the page can render before anyone joins.


        Deliberately says whether the owner can currently afford the call. The

        page uses it to explain the situation up front instead of letting

        someone set up their camera and then fail — but it is NOT the

        enforcement point; `join_web_room` is.'
      operationId: web_room_info_v1_t__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Web Room Info V1 T  Slug  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/t/{slug}/join:
    post:
      tags:
      - Interpreters
      summary: Join Web Room
      description: 'Public: admit a visitor and issue their LiveKit token.


        This is the enforcement point for every rule in this module — balance,

        passcode and capacity — because the token is the only thing that

        actually opens the room. A visitor who skips the page and calls this

        endpoint directly hits exactly the same checks.'
      operationId: join_web_room_v1_t__slug__join_post
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JoinRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Join Web Room V1 T  Slug  Join Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/t/{slug}/leave:
    post:
      tags:
      - Interpreters
      summary: Leave Web Room
      description: 'Public: release a seat when a visitor closes their tab.


        Best-effort — a browser that dies without sending this leaves the seat

        held, which is what the stale-session sweep is for. Returning 200 for an

        unknown room keeps this safe to call blindly from `beforeunload`.


        `failed=true` means the browser never reached the room (the SDK would not

        load, or `room.connect` timed out). That attempt is refunded: it would

        otherwise burn one of three daily demos without the visitor hearing

        anything. See `_refund_public_demo`.'
      operationId: leave_web_room_v1_t__slug__leave_post
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: failed
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Failed
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Leave Web Room V1 T  Slug  Leave Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InterpreterCreate:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
        source_language:
          type: string
          title: Source Language
        target_language:
          type: string
          title: Target Language
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
        transparency:
          type: string
          enum:
          - invisible
          - announce
          title: Transparency
          default: invisible
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
        callback_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Callback Number
      type: object
      required:
      - name
      - source_language
      - target_language
      title: InterpreterCreate
    InterpreterResponse:
      properties:
        interpreter_id:
          type: string
          title: Interpreter Id
        name:
          type: string
          title: Name
        source_language:
          type: string
          title: Source Language
        target_language:
          type: string
          title: Target Language
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
        transparency:
          type: string
          title: Transparency
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
        callback_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Callback Number
        active:
          type: boolean
          title: Active
        created_at:
          title: Created At
        web_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Web Slug
        web_enabled:
          type: boolean
          title: Web Enabled
          default: false
        web_requires_passcode:
          type: boolean
          title: Web Requires Passcode
          default: false
        save_transcripts:
          type: boolean
          title: Save Transcripts
          default: false
      type: object
      required:
      - interpreter_id
      - name
      - source_language
      - target_language
      - transparency
      - active
      - created_at
      title: InterpreterResponse
    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
    JoinRequest:
      properties:
        passcode:
          anyOf:
          - type: string
          - type: 'null'
          title: Passcode
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        hear:
          anyOf:
          - type: string
          - type: 'null'
          title: Hear
        rejoin_identity:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^[A-Za-z0-9_]+$
          - type: 'null'
          title: Rejoin Identity
        rejoin_key:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^[A-Za-z0-9_]+$
          - type: 'null'
          title: Rejoin Key
        solo_test:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Solo Test
      type: object
      title: JoinRequest
    StartMixedCallRequest:
      properties:
        target_number:
          type: string
          minLength: 5
          title: Target Number
      type: object
      required:
      - target_number
      title: StartMixedCallRequest
    WebConfigUpdate:
      properties:
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
        requires_passcode:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Passcode
      type: object
      title: WebConfigUpdate
    InterpreterUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: Name
        source_language:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Language
        target_language:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Language
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
        transparency:
          anyOf:
          - type: string
            enum:
            - invisible
            - announce
          - type: 'null'
          title: Transparency
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
        callback_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Callback Number
        active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Active
        save_transcripts:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Save Transcripts
      type: object
      title: InterpreterUpdate
    StartCallRequest:
      properties:
        target_number:
          type: string
          minLength: 5
          title: Target Number
        initiator_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Initiator Number
      type: object
      required:
      - target_number
      title: StartCallRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app