Call2Me Phone Numbers API

openapi: 3.2.0
info:
  title: Call2Me Phone Numbers 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: Phone Numbers
  description: Provision and assign phone numbers. Buy from supported regions, connect a SIP trunk for BYOC, or reserve a temporary demo number. Numbers can be assigned to a specific agent for inbound routing.
paths:
  /v1/phone-numbers:
    get:
      tags:
      - Phone Numbers
      summary: List Phone Numbers
      description: 'List all phone numbers for the current user.


        Also surfaces the active demo reservation (if any) as a virtual row, so the

        dashboard shows it even if phone_numbers hasn''t been synced yet.'
      operationId: list_phone_numbers_v1_phone_numbers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PhoneNumberResponse'
                type: array
                title: Response List Phone Numbers V1 Phone Numbers Get
    post:
      tags:
      - Phone Numbers
      summary: Create Phone Number
      description: Create a new phone number.
      operationId: create_phone_number_v1_phone_numbers_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/phone-numbers/{number}:
    get:
      tags:
      - Phone Numbers
      summary: Get Phone Number
      description: Get phone number details.
      operationId: get_phone_number_v1_phone_numbers__number__get
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Phone Numbers
      summary: Update Phone Number
      description: Update a phone number.
      operationId: update_phone_number_v1_phone_numbers__number__patch
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Phone Numbers
      summary: Delete Phone Number
      description: 'Release a phone number.


        Behavior by provider:

        - ''telnyx'' → release from Telnyx (stops carrier billing) + delete DB row.

        - ''telnyx-demo'' → release demo reservation (returns number to pool).

        - everything else (BYOC / trunk-bound) → just delete the DB binding.

        The trunk itself and the Telnyx-unrelated number remain the user''s.'
      operationId: delete_phone_number_v1_phone_numbers__number__delete
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/phone-numbers/{number}/bind:
    post:
      tags:
      - Phone Numbers
      summary: Bind Agent
      description: Bind an agent to a phone number.
      operationId: bind_agent_v1_phone_numbers__number__bind_post
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindAgentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/phone-numbers/{number}/unbind:
    delete:
      tags:
      - Phone Numbers
      summary: Unbind Agent
      description: Unbind agent from a phone number.
      operationId: unbind_agent_v1_phone_numbers__number__unbind_delete
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/phone-numbers/{number}/agent:
    get:
      tags:
      - Phone Numbers
      summary: Get Agent For Number
      description: 'Get agent configuration for a phone number.


        This endpoint is used by the orchestrator to lookup agent config

        when a call comes in to a specific DID.'
      operationId: get_agent_for_number_v1_phone_numbers__number__agent_get
      parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          title: Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PhoneNumberResponse:
      properties:
        number:
          type: string
          title: Number
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        trunk_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trunk Id
        trunk_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Trunk Name
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        provider:
          type: string
          title: Provider
        active:
          type: boolean
          title: Active
        is_demo:
          type: boolean
          title: Is Demo
          default: false
        monthly_price_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Monthly Price Usd
        next_billing_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Billing At
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - number
      - user_id
      - agent_id
      - trunk_id
      - display_name
      - provider
      - active
      - created_at
      - updated_at
      title: PhoneNumberResponse
      description: Response model for phone numbers.
    PhoneNumberCreate:
      properties:
        number:
          type: string
          maxLength: 50
          minLength: 1
          title: Number
          description: E.164 (+905551234567) veya yerel (08503033852) — otomatik +90'a çevrilir
        display_name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Display Name
        trunk_id:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Trunk Id
        agent_id:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Agent Id
      type: object
      required:
      - number
      title: PhoneNumberCreate
      description: Request model for creating a phone number.
    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
    PhoneNumberUpdate:
      properties:
        display_name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Display Name
        trunk_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trunk Id
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
        active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Active
      type: object
      title: PhoneNumberUpdate
      description: Request model for updating a phone number.
    AgentConfigResponse:
      properties:
        agent_id:
          type: string
          title: Agent Id
        system_prompt:
          type: string
          title: System Prompt
        model:
          type: string
          title: Model
        temperature:
          type: number
          title: Temperature
        language:
          type: string
          title: Language
        voice_id:
          type: string
          title: Voice Id
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        engine:
          type: string
          title: Engine
          default: cascade
      type: object
      required:
      - agent_id
      - system_prompt
      - model
      - temperature
      - language
      - voice_id
      - user_id
      title: AgentConfigResponse
      description: 'Agent configuration for orchestrator (phone-number lookup path).


        Not: internal.py''de aynı isimli DAHA ZENGİN bir model var (email_verified,

        balance, builtin_functions vb.). Bu minimal versiyon yalnızca /{number}/agent

        inbound lookup için — isim çakışmasına dikkat, farklı router''lar ayrı import eder.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BindAgentRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
      type: object
      required:
      - agent_id
      title: BindAgentRequest
      description: Request to bind an agent to a phone number.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app