API docs for AI agents Phase D

Outbound voice-call API designed for AI agents (Claude, GPT, Cursor, MCP, Zapier, custom). Two entrypoints: a structured Skill API (manifest + idempotent run + SSE events) and the legacy free-form POST /calls. Every endpoint below is live in production. No login required to read these docs.

Authentication

Every authenticated request takes the API key in the X-API-Key header. Get a free key at the home page (100 free credits). One key works for everything; no per-endpoint scopes today.
Public (no auth): GET /skills, GET /skills/{skill_id}/manifest, GET /docs, GET /openapi.json.
Single exception: GET /calls/{id}/recording also accepts ?api_key= query param so HTML5 <audio> can fetch it.

Skill API recommended

Strongly-typed wrapper around the voice pipeline. The agent fetches the manifest (input schema + capabilities), POSTs structured data to /skills/{skill_id}/run, and the server builds the brief + dispatches the call. Idempotency, SSE events, durable ask_user — all part of this path.

Idempotency contract

Same Idempotency-Key + same body from same customer → server replays original response, no duplicate dial. Use a unique key per logical agent retry attempt (e.g. outer-loop UUID).
Storage: table skill_run_idempotency keyed on (customer_id, idempotency_key). Body fingerprinted with SHA-256 of canonical JSON. TTL 24 h; lock window 120 s.

No Idempotency-Key header → endpoint runs without replay guarantee. Network retries will produce duplicate calls. Don't ship that.

Event stream — SSE /calls/{call_id}/events

Content-Type: text/event-stream. Auth: X-API-Key. Use curl -N or any standard SSE client.

ask_user — answering bot questions

When the bot needs info during the call it emits ask_user to both the configured webhook and the SSE stream — same request_id in both, dedupe by request_id.

Cross-pod guarantee

The pending_skill_ask_user row is written before the SSE/webhook event fires. POST /answer can land on any pod (Istio path-hash routes to call's owner pod when possible, but works without it): the broker UPDATEs the row and pg_notify('ask_user_answer', request_id) wakes the owner pod.
Timeout: server-side asyncio.wait_for per ask_user. If timeout hits before answer, row goes pending → timeout. Late answers return delivered=false.

Legacy /calls API (free-form brief)

Original entrypoint, unchanged. Use only when the structured Skill API doesn't fit your case (e.g. one-off cancellation, unusual ad-hoc task). For new agent integrations, prefer Skill API.

Account & quota

ask_user webhook flow (alternative to SSE)

If your agent runs an HTTP server, configure a webhook to receive ask_user synchronously. Both webhook and SSE deliver the same event for the same request_id — your agent must dedupe by request_id if it listens to both.

Webhook payload:

Headers: webhook-signature: ... (Standard Webhooks v1, HMAC-SHA256). Verify before trusting body.

Sync reply (≤30 s): 200 with body {"answer": "..."}.

Async reply: 202 with empty body, then POST /calls/{id}/answer with {answer, request_id}.

Polling-only fallback (no webhook, no SSE)

If your AI agent has neither a webhook server nor an SSE client, you can still operate (without ask_user mid-call):

1. POST /skills/{id}/run with Idempotency-Key.
2. Poll GET /calls/{call_id} every 2-3 s.
3. Stop when status ∈ completed/failed/cancelled.
4. Read outcome_type, outcome_summary, transcript_full; optionally fetch recording_url.

ask_user mid-call without webhook OR SSE is not supported. Either configure one or include all needed info upfront in the input.

Outcome enums

When a call reaches status=completed, outcome_type is one of:

• success_booked — booking confirmed by operator
• success_no_booking — operator answered, no firm booking (info call)
• success_other — task completed, neither booking nor refusal
• failed_no_answer — no one picked up
• failed_voicemail — answering machine detected
• failed_unsupported_language — operator spoke a language we don't handle
• failed_technical — pipeline error (Twilio / Gemini / network)
• refused — operator refused / no slot

Errors & status codes

Structured errors use detail = {"error": "<code>", ...}. Codes are stable across versions.

Operational specs

Best practices for AI agents

1. Prefer the Skill API over POST /calls for new integrations — schema validation, idempotency, structured errors, dynamic manifest.
2. Always send Idempotency-Key on POST /skills/{id}/run. One key per logical retry, NOT per network attempt. Without it, a connection blip will dial twice.
3. Use SSE for terminal-mode agents. No HTTP server needed; just curl -N. Resume with Last-Event-ID after disconnect.
4. Always pass request_id in POST /answer. Disambiguates multiple in-flight ask_user. The bot supports parallel ask_user since Phase C.
5. Dedupe ask_user by request_id if you listen to BOTH webhook and SSE — same event delivered twice.
6. Pre-spell phone numbers if dictation accuracy matters. The skill formatter does this automatically for phone_to_dictate.
7. Surface 402 / 503 to the user — these need human action (top up, wait for maintenance).
8. Don't poll faster than every 2 s. Be polite — and SSE is cheaper than polling anyway.
9. Trust /openapi.json over this page if anything disagrees. It's the byte-exact contract.