API Reference: REST endpoints, auth, OpenAPI spec

Base URL and auth

CopyBase URL: https://api.call2me.app
OpenAPI:  https://api.call2me.app/openapi.json

Interactive explorer: Browse and test every endpoint live in Swagger UI — click Authorize, paste your API key, and hit Try it out. Prefer a clean read-only reference? Use ReDoc.

SDKs (v1.5.2): Python, Node.js, and Go — all now include voice_sessions.create() for headless AI voice sessions. API keys can be scoped read-only (they get 403 on any write). New: POST /v1/voice/sessions returns a LiveKit token to embed AI voice in your own app.

Authentication:

• JWT tokens — for the dashboard and SDK clients. Returned by POST /v1/auth/login.
• API keys — long-lived, for server-to-server. Generate in dashboard → API Keys.

Header for both:

CopyAuthorization: Bearer <token-or-key>

Endpoint groups

Call2Me exposes 240+ REST operations organized into groups:

Auth

CopyPOST /v1/auth/signup     Register new user
POST /v1/auth/login        Login, returns JWT
POST /v1/auth/refresh      Refresh JWT
GET  /v1/auth/me           Current user
POST /v1/auth/logout       Logout

Agents

CopyPOST   /v1/agents          Create agent
GET    /v1/agents          List agents
GET    /v1/agents/{id}     Get agent
PATCH  /v1/agents/{id}     Update agent
DELETE /v1/agents/{id}     Delete agent
POST   /v1/agents/{id}/test-function   Test webhook function

Calls

CopyPOST   /v1/calls                Place an outbound call
GET    /v1/calls                List calls
GET    /v1/calls/{id}           Get call detail
GET    /v1/calls/{id}/recording Download recording
GET    /v1/calls/{id} Get transcript

Knowledge Base

CopyPOST   /v1/knowledge-base                  Create KB
GET    /v1/knowledge-base                  List KBs
POST   /v1/knowledge-base/{id}/add-sources     Add source
DELETE /v1/knowledge-base/{id}/source/{src} Delete source
POST   /v1/knowledge-base/{id}/query       Semantic search

Phone Numbers

CopyGET    /v1/phone-numbers                List
POST   /v1/numbers/purchase            Buy via Telnyx
POST   /v1/phone-numbers/{number}/bind    Assign to agent
DELETE /v1/phone-numbers/{number}       Release

Widgets

CopyPOST /v1/widgets                  Create widget
GET  /v1/widgets/{id}/config      Public — config for embed
GET  /v1/widgets/{id}/embed.js    Public — runtime JS
POST /v1/widgets/{id}/chat        Public — send message
GET  /v1/widgets/{id}/preview     Public — standalone preview

Schedules

CopyPOST /v1/schedules                Create scheduled call
GET  /v1/schedules                List
DELETE /v1/schedules/{id}         Cancel

Voice / LiveKit

CopyPOST /v1/livekit/token            Get LiveKit token for browser voice call
GET  /v1/livekit/health           LiveKit config check

Payments / Wallet

CopyGET  /v1/wallet/balance           Current balance (`GET /v1/wallet` is an alias)
POST /v1/payments/checkout      Add funds (checkout session)
GET  /v1/payments/auto-charge   Auto-recharge settings (PUT to update)
GET  /v1/payments/history         Transactions
GET  /v1/pricing                  Public — current pricing

Public utility endpoints (no auth)

CopyGET  /v1/pricing                       Pricing snapshot
GET  /v1/branding/{domain}             White-label branding lookup
POST /v1/contact                       Contact form
POST /v1/newsletter/subscribe          Newsletter signup
POST /v1/events                        Client-side event ingest
POST /v1/demo/call                     Demo call (rate-limited)

Rate limits

• Per API key: 1000 requests / minute (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset).
• Per-IP on public endpoints: 30 requests / minute.
• Webhook deliveries: agent webhooks are sent once, no retry; account-level webhooks make 3 attempts.

When rate-limited, you'll get a 429 Too Many Requests with a Retry-After header.

Webhooks

Configure on AgentDetail → Webhook URL. Events:

• call_ended — call finished; duration and usage inside data.
• call_analyzed — post-call analysis ready; analysis inside data.
• call_transferred — agent handed the caller to a human number.
• transfer_failed — a transfer was attempted and the target did not answer.
• function_called — the agent invoked one of your custom functions.

Names use underscores. There are no payment.* agent events; account-level voice_session.ended and wallet.low_balance are covered on the webhooks page.

Payload format (call_ended):

Copy{
  "event": "call_ended",
  "timestamp": "2026-10-06T12:34:56.000",
  "data": {
    "room": "agent_..._ab12",
    "participant": "sip_90...",
    "duration_messages": 14,
    "duration_seconds": 87,
    "usage": { "llm_tokens": 1840, "stt_seconds": 75.4, "tts_chars": 570 }
  }
}

call_started carries {room, participant, agent_id}; call_analyzed carries {room, agent_id, analysis}. Transcript, recording and call id come from GET /v1/calls. Agent webhooks are not signed and are sent once without retry; the signed, retried path is the account-level webhook — see webhooks.

SDKs

Official:

• Python — pip install call2me
• TypeScript / JavaScript — npm install @call2me/sdk

Both wrap the REST API with type-safe clients and handle auth refresh automatically.

OpenAPI spec

Full machine-readable schema:

Copyhttps://api.call2me.app/openapi.json

Import into Postman, generate clients in any language, or browse the schema directly.

Status and uptime

• Real-time status: status.call2me.app (where available)
• Historical SLA: 99.9% on the API, 99.5% on voice.