Call2Me Demo Numbers API

openapi: 3.2.0
info:
  title: Call2Me Demo 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: Demo Numbers
paths:
  /v1/demo/eligibility:
    get:
      tags:
      - Demo Numbers
      summary: Check Eligibility
      description: 'Check whether the user can reserve a demo number.


        Eligibility rules (must all be true):

        - User has NOT used their demo before

        - User has NOT made a paid topup (paid users buy real numbers)

        - No active reservation currently


        Note: "has paid" users can still reserve, but they''re encouraged to buy.

        We don''t block them — they can demo if they choose. But UI shows "Buy Number"

        as primary for paid users.'
      operationId: check_eligibility_v1_demo_eligibility_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityResponse'
  /v1/demo/pool:
    get:
      tags:
      - Demo Numbers
      summary: Pool Status
      description: Public pool status (no auth required).
      operationId: pool_status_v1_demo_pool_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolStatusResponse'
  /v1/demo/reserve:
    post:
      tags:
      - Demo Numbers
      summary: Reserve Number
      description: 'Reserve a demo number for 15 minutes.


        Atomic flow:

        1. Verify eligibility (one-per-lifetime)

        2. Lock a pool row with SELECT ... FOR UPDATE SKIP LOCKED

        3. Insert demo_reservations row

        4. Mark pool row as ''reserved''

        5. Insert phone_numbers row pointing to user+agent

        6. All inside a transaction — rollback on any failure'
      operationId: reserve_number_v1_demo_reserve_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReserveRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/demo/release:
    post:
      tags:
      - Demo Numbers
      summary: Release Number
      description: Release the active demo reservation early (user-initiated).
      operationId: release_number_v1_demo_release_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Release Number V1 Demo Release Post
  /v1/demo/my-reservation:
    get:
      tags:
      - Demo Numbers
      summary: Get My Reservation
      description: Get user's currently active demo reservation, if any.
      operationId: get_my_reservation_v1_demo_my_reservation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ReservationInfo'
                - type: 'null'
                title: Response Get My Reservation V1 Demo My Reservation Get
components:
  schemas:
    PoolStatusResponse:
      properties:
        total:
          type: integer
          title: Total
        available:
          type: integer
          title: Available
        reserved:
          type: integer
          title: Reserved
        countries:
          items:
            type: string
          type: array
          title: Countries
      type: object
      required:
      - total
      - available
      - reserved
      - countries
      title: PoolStatusResponse
      description: Pool availability snapshot (for UI feedback).
    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
    ReserveRequest:
      properties:
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: Agent to bind the number to. If omitted, user can bind later.
      type: object
      title: ReserveRequest
      description: Reserve a demo number.
    ReservationInfo:
      properties:
        reservation_id:
          type: string
          title: Reservation Id
        phone_number:
          type: string
          title: Phone Number
        country_code:
          type: string
          title: Country Code
        display_name:
          type: string
          title: Display Name
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
        reserved_at:
          type: string
          format: date-time
          title: Reserved At
        expires_at:
          type: string
          format: date-time
          title: Expires At
        minutes_remaining:
          type: integer
          title: Minutes Remaining
      type: object
      required:
      - reservation_id
      - phone_number
      - country_code
      - display_name
      - agent_id
      - reserved_at
      - expires_at
      - minutes_remaining
      title: ReservationInfo
      description: Reservation detail shown to user.
    EligibilityResponse:
      properties:
        eligible:
          type: boolean
          title: Eligible
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        has_paid_topup:
          type: boolean
          title: Has Paid Topup
        has_used_demo:
          type: boolean
          title: Has Used Demo
        active_reservation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Active Reservation Id
      type: object
      required:
      - eligible
      - has_paid_topup
      - has_used_demo
      title: EligibilityResponse
      description: Whether the user can reserve a demo.
    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