Generated API reference
Customer REST operations generated deterministically from the checked-in canonical OpenAPI snapshot.
This page is the customer-facing operation index generated from the checked-in OpenAPI snapshot. The running API's live OpenAPI document is canonical for exact request and response schemas. Handwritten guides explain the product model: Integrations, customer applications, and post-call results.
Snapshot: Telephony AI API v0.1.0. This generated index includes only customer SDK operations; dashboard, operator, provider, and worker transport hooks are intentionally excluded.
Customer REST operations
| Method | Path | Summary | Required scope |
|---|---|---|---|
POST | /mcp | Hosted MCP endpoint | See the live OpenAPI operation |
GET | /v1/activation-state | Get live customer activation checklist and next action | See the live OpenAPI operation |
GET | /v1/agent-catalog | List runnable agent stack entries | See the live OpenAPI operation |
GET | /v1/agent-endpoints | List agent webhook/audio endpoints | See the live OpenAPI operation |
POST | /v1/agent-endpoints | Connect an agent | See the live OpenAPI operation |
DELETE | /v1/agent-endpoints/{agent_endpoint_id} | Delete a webhook endpoint (soft: stops every delivery) | See the live OpenAPI operation |
PATCH | /v1/agent-endpoints/{agent_endpoint_id} | Change which events this endpoint receives | See the live OpenAPI operation |
POST | /v1/agent-endpoints/{agent_endpoint_id}/pause | Pause webhook deliveries to this endpoint | See the live OpenAPI operation |
POST | /v1/agent-endpoints/{agent_endpoint_id}/resume | Resume a paused or auto-disabled webhook endpoint | See the live OpenAPI operation |
POST | /v1/agent-endpoints/{agent_endpoint_id}/test-event | Dispatch a signed test event through the real delivery pipeline | See the live OpenAPI operation |
GET | /v1/agents | List first-class agents | See the live OpenAPI operation |
POST | /v1/agents | Create an external or hosted agent | See the live OpenAPI operation |
GET | /v1/agents/{agent_id} | Get one agent | agents:read |
PATCH | /v1/agents/{agent_id} | Update one agent | agents:write |
POST | /v1/agents/{agent_id}/browser-sessions | Create an authenticated LiveKit browser-test session for one hosted agent | agents:write, calls:write |
POST | /v1/agents/{agent_id}/browser-sessions/{session_id}/settle | Settle one workspace browser-test reservation | agents:write, calls:write |
GET | /v1/agents/{agent_id}/handoff | Get generated agent setup handoff | See the live OpenAPI operation |
GET | /v1/agents/{agent_id}/knowledge-bases | List active knowledge bases attached to one hosted agent | See the live OpenAPI operation |
PATCH | /v1/agents/{agent_id}/knowledge-bases | Replace the knowledge bases attached to one hosted agent | See the live OpenAPI operation |
GET | /v1/agents/{agent_id}/post-call-extraction | Read the optional advisory post-call extraction configuration | agents:read |
PATCH | /v1/agents/{agent_id}/post-call-extraction | Configure or disable bounded advisory post-call extraction | agents:write |
GET | /v1/agents/{agent_id}/simulation-suite-runs/{run_id} | Fetch one run with a bounded page of attempt results | agents:read |
POST | /v1/agents/{agent_id}/simulation-suite-runs/{run_id}/cancel | Stop the attempts of this run that have not started | agents:write |
POST | /v1/agents/{agent_id}/simulation-suite-runs/{run_id}/cases/{case_result_id}/evidence | Link an existing Talk or Phone session to this attempt as human evidence | agents:write |
POST | /v1/agents/{agent_id}/simulation-suite-runs/{run_id}/cases/{case_result_id}/save-as-regression | Promote one attempt into a permanent scenario | agents:write |
POST | /v1/agents/{agent_id}/simulation-suite-runs/{run_id}/rerun-failed | Queue a child run over this run's failed cases | agents:write |
GET | /v1/agents/{agent_id}/simulation-suite-runs/{run_id}/results | Read one run's verdicts in a stable, versioned shape | simulation_suites:read |
GET | /v1/agents/{agent_id}/simulation-suites | List this agent's simulation suites with their latest health | agents:read |
POST | /v1/agents/{agent_id}/simulation-suites | Create a simulation suite for this agent | agents:write |
GET | /v1/agents/{agent_id}/simulation-suites/{suite_id} | Fetch one suite with its authored scenarios and bounded run history | agents:read |
PATCH | /v1/agents/{agent_id}/simulation-suites/{suite_id} | Edit a suite under optimistic revision control | agents:write |
POST | /v1/agents/{agent_id}/simulation-suites/{suite_id}/duplicate | Copy a suite's authored content into a new suite | agents:write |
POST | /v1/agents/{agent_id}/simulation-suites/{suite_id}/runs | Queue a run of this suite | agents:write |
GET | /v1/agents/{agent_id}/voice-stack | Read a hosted agent's safe STT, model, and TTS configuration | agents:read |
PATCH | /v1/agents/{agent_id}/voice-stack | Validate and update a hosted agent's STT, model, and TTS selections | agents:write |
GET | /v1/agents/{agent_id}/workflow | Read an agent's editable workflow draft and bounded published-version summary | agents:read |
PATCH | /v1/agents/{agent_id}/workflow | Update the agent's workflow draft | agents:write |
POST | /v1/agents/{agent_id}/workflow | Create the one editable workflow draft for a hosted agent | agents:write |
POST | /v1/agents/{agent_id}/workflow/ai-edit | Propose a bounded AI edit to the agent's workflow draft | agents:write |
GET | /v1/agents/{agent_id}/workflow/phone-pin | Read this agent's current Phone pin status | agents:read |
POST | /v1/agents/{agent_id}/workflow/phone-pin | Arm Phone testing: pin one declared caller number to the workflow | agents:write |
POST | /v1/agents/{agent_id}/workflow/phone-pin/disarm | Cancel this agent's active Phone pin early | agents:write |
POST | /v1/agents/{agent_id}/workflow/publish | Publish the current draft as a new immutable workflow version | agents:write |
POST | /v1/agents/{agent_id}/workflow/runs | Start a Chat or Simulations test run of the agent's workflow | agents:write |
GET | /v1/agents/{agent_id}/workflow/runs/{run_id} | Fetch one test run and its turn evidence | agents:read |
POST | /v1/agents/{agent_id}/workflow/runs/{run_id}/turns | Advance one turn of a Chat test run | agents:write |
POST | /v1/agents/{agent_id}/workflow/simulations | Run a batch of scripted-persona Simulations to completion | agents:write |
POST | /v1/agents/{agent_id}/workflow/versions/{version}/restore | Restore a published version's content into the editable draft | agents:write |
GET | /v1/api-keys | List scoped API keys | See the live OpenAPI operation |
POST | /v1/api-keys | Create a scoped API key | See the live OpenAPI operation |
GET | /v1/api-keys/scopes | Read the grantable scope catalogue and bundles | See the live OpenAPI operation |
GET | /v1/api-keys/{key_id} | Get one API key | See the live OpenAPI operation |
POST | /v1/api-keys/{key_id}/revoke | Revoke an API key | See the live OpenAPI operation |
GET | /v1/audio-environments | List immutable audio-environment presets | account:read |
GET | /v1/audit-events | List audit events | See the live OpenAPI operation |
GET | /v1/billing/settings | Read wallet billing settings and auto-recharge readiness | See the live OpenAPI operation |
PATCH | /v1/billing/settings | Update safe auto-recharge settings without triggering a live charge | See the live OpenAPI operation |
POST | /v1/billing/stripe/topup-sessions | Create a Stripe checkout topup session when enabled | See the live OpenAPI operation |
POST | /v1/byo/sip-trunk/dids | List the connected BYO SIP trunk carrier account's DIDs for the import picker (live read with a transient, never-stored API token) | See the live OpenAPI operation |
POST | /v1/byo/sip-trunk/import | Import a carrier-owned DID as a voice-only number; activates only on passing live activation evidence, monthly fee stays with the carrier | See the live OpenAPI operation |
POST | /v1/byo/sip-trunk/setup-checks | Run secret-redacted BYO SIP trunk readiness checks for one DID (trunk auth, caller ID, inbound destination, channel capacity) | See the live OpenAPI operation |
GET | /v1/call-results | Read one bounded factual post-call result group | calls:read, recordings:read |
GET | /v1/calls | List calls | See the live OpenAPI operation |
POST | /v1/calls | Place one policy-gated, idempotent outbound call | See the live OpenAPI operation |
GET | /v1/calls/stats | Aggregate call volume, talk time, and spend over one or more date windows | calls:read |
GET | /v1/calls/{call_id} | Get one call | calls:read |
GET | /v1/calls/{call_id}/artifacts | List call artifacts | See the live OpenAPI operation |
POST | /v1/calls/{call_id}/cancel | Cancel a queued outbound call before origination | See the live OpenAPI operation |
GET | /v1/calls/{call_id}/events | Get one call's full internal lifecycle event log | calls:read |
POST | /v1/calls/{call_id}/hangup | Ask a live call to hang up | See the live OpenAPI operation |
GET | /v1/calls/{call_id}/observability | Get dashboard call observability bundle | See the live OpenAPI operation |
GET | /v1/calls/{call_id}/post-call-extraction | Read an optional advisory extraction result for one call | recordings:read |
DELETE | /v1/calls/{call_id}/recording | Delete the active call recording metadata and audit the action | See the live OpenAPI operation |
GET | /v1/calls/{call_id}/recording | Get call recording metadata and disclosure state | recordings:read |
GET | /v1/calls/{call_id}/recording/content | Stream call recording audio | recordings:read |
GET | /v1/calls/{call_id}/transcript | Get call transcript turns | See the live OpenAPI operation |
GET | /v1/calls/{call_id}/transcript/stream | Get transcript stream events | See the live OpenAPI operation |
GET | /v1/calls/{call_id}/waveform | Get waveform peaks for playback | See the live OpenAPI operation |
GET | /v1/campaigns | List campaigns (bounded page) | calls:read |
POST | /v1/campaigns | Create a draft outbound campaign | calls:write |
GET | /v1/campaigns/{campaign_id} | Read one campaign with its latest run and contact counters | calls:read |
PATCH | /v1/campaigns/{campaign_id} | Edit a campaign's settings | calls:write |
POST | /v1/campaigns/{campaign_id}/cancel | Cancel a campaign: queued calls are cancelled, remaining contacts skipped | calls:write |
GET | /v1/campaigns/{campaign_id}/contacts | List the latest run's contacts with status, disposition, attempts and next attempt (bounded page) | calls:read |
POST | /v1/campaigns/{campaign_id}/duplicate | Copy a campaign's configuration into a new draft | calls:write |
GET | /v1/campaigns/{campaign_id}/export | Export the latest run's results as CSV | calls:read |
POST | /v1/campaigns/{campaign_id}/launch | Authorize and start a draft campaign | calls:write |
POST | /v1/campaigns/{campaign_id}/pause | Pause a running campaign | calls:write |
POST | /v1/campaigns/{campaign_id}/resume | Resume a paused campaign | calls:write |
GET | /v1/contact-lists | List contact lists in the workspace (bounded page) | calls:read |
POST | /v1/contact-lists | Create a contact list, optionally importing rows in the same request | calls:write |
GET | /v1/contact-lists/{contact_list_id} | Read one contact list | calls:read |
GET | /v1/contact-lists/{contact_list_id}/contacts | List contacts in a list (bounded page in import order) | calls:read |
POST | /v1/contact-lists/{contact_list_id}/contacts | Append rows to a contact list | calls:write |
GET | /v1/conversations | List SMS conversations | See the live OpenAPI operation |
GET | /v1/conversations/{conversation_id} | Get one SMS conversation | See the live OpenAPI operation |
GET | /v1/coverage-matrix | List country coverage, messaging, simple onboarding terms, and safe activation speed | See the live OpenAPI operation |
GET | /v1/customer-onboarding | List business onboarding records | See the live OpenAPI operation |
POST | /v1/customer-onboarding | Submit business onboarding details | See the live OpenAPI operation |
GET | /v1/do-not-call | List the workspace do-not-call register (bounded page) | calls:read |
POST | /v1/do-not-call | Add numbers to the do-not-call register | calls:write |
DELETE | /v1/do-not-call/{phone_number} | Remove one number from the do-not-call register | calls:write |
GET | /v1/end-users/{end_user_profile_id}/registration-status | KYC + carrier identity + per-number registration status with derived customer status, and a headline naming how many number registrations OpenPhonex has submitted to the carrier (empty when none is currently submitted, and also when the profile is rejected or needs more information) | See the live OpenAPI operation |
POST | /v1/end-users/{end_user_profile_id}/submit-registration | Enqueue the carrier end-user registration chain (identity/address/proofs/verification) through the operator queue; identity is org-level and reused | See the live OpenAPI operation |
GET | /v1/gateway-deployments | List media gateways | See the live OpenAPI operation |
POST | /v1/gateway-deployments | Create a deployment | See the live OpenAPI operation |
PATCH | /v1/gateway-deployments/{gateway_id}/outbound-execution-mode | Choose whether this deployment dials its own outbound calls | gateways:write |
GET | /v1/gateway-deployments/{gateway_id}/tokens | List a gateway's machine tokens, masked to their prefixes | See the live OpenAPI operation |
POST | /v1/gateway-deployments/{gateway_id}/tokens/{gateway_token_id}/revoke | Revoke one gateway machine token immediately | See the live OpenAPI operation |
GET | /v1/hosted-ai-credentials | List bounded metadata for hosted AI BYOK credentials | agents:read |
POST | /v1/hosted-ai-credentials | Store a write-only hosted AI provider credential | agents:write |
POST | /v1/hosted-ai-credentials/{credential_id}/revoke | Revoke a hosted AI credential | agents:write |
POST | /v1/hosted-ai-credentials/{credential_id}/validate | Run a non-billable validation probe for a hosted AI credential | agents:write |
GET | /v1/integrations | List bounded metadata for reusable customer Integrations | agents:read |
POST | /v1/integrations | Create one reusable encrypted Integration and its first read action | agents:write |
GET | /v1/integrations/{integration_id}/actions | List typed actions on one reusable Integration | agents:read |
POST | /v1/integrations/{integration_id}/actions | Add an allowlisted typed read action to an Integration | agents:write |
POST | /v1/integrations/{integration_id}/disable | Disable an Integration and remove its actions from the active worker allowlist | agents:write |
GET | /v1/knowledge-bases | List bounded active knowledge bases for the authenticated project | See the live OpenAPI operation |
POST | /v1/knowledge-bases | Create a private knowledge base in the authenticated workspace | See the live OpenAPI operation |
DELETE | /v1/knowledge-bases/{knowledge_base_id} | Hide and asynchronously delete one knowledge base and its private sources | See the live OpenAPI operation |
GET | /v1/knowledge-bases/{knowledge_base_id} | Read one knowledge base | See the live OpenAPI operation |
PATCH | /v1/knowledge-bases/{knowledge_base_id} | Rename one knowledge base | See the live OpenAPI operation |
GET | /v1/knowledge-bases/{knowledge_base_id}/documents | List bounded document lifecycle state for one knowledge base | See the live OpenAPI operation |
POST | /v1/knowledge-bases/{knowledge_base_id}/documents | Direct-upload one private TXT, Markdown, PDF, or DOCX source | See the live OpenAPI operation |
POST | /v1/knowledge-bases/{knowledge_base_id}/test | Test one grounded answer against a private knowledge base | knowledge:read |
DELETE | /v1/knowledge-documents/{document_id} | Hide and asynchronously delete one private source document | See the live OpenAPI operation |
POST | /v1/knowledge-documents/{document_id}/replace | Replace one permanently unreadable private source document | knowledge:write |
POST | /v1/knowledge-documents/{document_id}/retry | Retry a recoverable knowledge document ingestion | See the live OpenAPI operation |
GET | /v1/knowledge-documents/{document_id}/text | Read a bounded page of normalized extracted text for one ready document | knowledge:read |
POST | /v1/kyc/sessions | Start a didit.me KYC (individual) or KYB (business) verification session for an end-user profile | See the live OpenAPI operation |
GET | /v1/kyc/sessions/{end_user_profile_id} | Read KYC/KYB status and the extracted decision summary (no raw document URLs) | See the live OpenAPI operation |
GET | /v1/messages | List SMS messages | See the live OpenAPI operation |
POST | /v1/messages | Send a policy-gated outbound SMS | See the live OpenAPI operation |
GET | /v1/messages/{message_id}/delivery-events | List SMS provider delivery events for one message | See the live OpenAPI operation |
GET | /v1/number-catalog | Search the stored number catalog with customer setup/monthly prices, capabilities, and onboarding terms | See the live OpenAPI operation |
GET | /v1/number-requests | List managed phone-number requests | See the live OpenAPI operation |
POST | /v1/number-requests | Request a managed OpenPhonex phone number | See the live OpenAPI operation |
GET | /v1/number-requests/{request_id} | Get one managed phone-number request | See the live OpenAPI operation |
PATCH | /v1/number-requests/{request_id} | Update managed phone-number request status or notes | See the live OpenAPI operation |
GET | /v1/numbers | List phone numbers | See the live OpenAPI operation |
GET | /v1/numbers/requirements | Resolve honest activation requirements for a country/number-type/profile-type (override > live did_groups flag > dataset prefix flag; requirement text only documents fields) | See the live OpenAPI operation |
GET | /v1/numbers/{number_id}/activation | Customer-facing number activation state: instant | pending_verification | approved | needs_info | rejected with blocking items | See the live OpenAPI operation |
POST | /v1/numbers/{number_id}/detach-agent | Compatibility alias for detaching a phone number from its agent | numbers:write |
GET | /v1/numbers/{number_id}/number-rules | Compatibility alias for phone-number Number rules | See the live OpenAPI operation |
PATCH | /v1/numbers/{number_id}/number-rules | Compatibility alias for updating phone-number Number rules | See the live OpenAPI operation |
POST | /v1/organizations | Create a sandbox customer workspace when signup mode allows it | See the live OpenAPI operation |
GET | /v1/organizations/{organization_id}/capabilities | Read the workspace's capabilities record, the selectable use-case profiles, and live usage against its caps | onboarding:read |
POST | /v1/organizations/{organization_id}/capabilities | Request or change the workspace's capabilities | onboarding:write |
POST | /v1/organizations/{organization_id}/capabilities/accept-policy | Record acceptance of the outbound policy without changing the capabilities selection | onboarding:write |
POST | /v1/organizations/{organization_id}/capabilities/destination-restrictions | Set optional workspace destination restrictions | onboarding:write |
POST | /v1/organizations/{organization_id}/capabilities/limit-requests | Request higher limits without changing current permissions or buying a plan | onboarding:write |
POST | /v1/phone-numbers/{number_id}/detach-agent | Detach a phone number from the agent that answers it | numbers:write |
GET | /v1/phone-numbers/{number_id}/number-rules | Get customer-facing Number rules for a phone number | See the live OpenAPI operation |
PATCH | /v1/phone-numbers/{number_id}/number-rules | Update customer-facing Number rules for a phone number | See the live OpenAPI operation |
GET | /v1/phone-servers | List customer phone servers | See the live OpenAPI operation |
POST | /v1/phone-servers | Create a customer phone server for self-hosted call media | See the live OpenAPI operation |
GET | /v1/phone-servers/{phone_server_id} | Get one customer phone server | See the live OpenAPI operation |
PATCH | /v1/phone-servers/{phone_server_id} | Update one customer phone server | See the live OpenAPI operation |
POST | /v1/phone-servers/{phone_server_id}/test | Dry-run verify a customer phone server before assigning Number rules | See the live OpenAPI operation |
POST | /v1/policies/evaluate | Evaluate outbound policy | See the live OpenAPI operation |
GET | /v1/pricing/catalog | List pricing plans | See the live OpenAPI operation |
POST | /v1/pricing/estimate | Estimate monthly platform cost on the public price book (public_launch_pricing_v1) | See the live OpenAPI operation |
GET | /v1/regulatory-requirements | List supported country and number-type requirements with simple onboarding terms and cache metadata | See the live OpenAPI operation |
GET | /v1/self-hosted/install-plan | Fetch a mode-specific self-hosted or customer-hosted gateway install plan | See the live OpenAPI operation |
GET | /v1/trial-calls | List historical and offline trial fixtures | See the live OpenAPI operation |
POST | /v1/trial-calls | Create an offline synthetic trial fixture | See the live OpenAPI operation |
GET | /v1/usage | Get usage summary | See the live OpenAPI operation |
GET | /v1/usage/daily | Get daily usage summary | See the live OpenAPI operation |
GET | /v1/usage/monthly | Get monthly usage summary | See the live OpenAPI operation |
GET | /v1/verification/requirement-summaries | Resolve batched per-number-type verification deltas for one country and optional reusable profile | See the live OpenAPI operation |
POST | /v1/voice-previews | Render one bounded managed voice-selector preview | agents:write |
GET | /v1/wallet | Read wallet balance and low-balance readiness against recurring and reserved costs | See the live OpenAPI operation |
GET | /v1/wallet/ledger | List org-level wallet ledger entries and linked usage/call refs | See the live OpenAPI operation |
POST | /v1/web-calls | Create a non-PSTN browser web-call test session | See the live OpenAPI operation |
GET | /v1/webhook-deliveries | List real webhook delivery attempts (status, attempts, last error, next retry) | See the live OpenAPI operation |
GET | /v1/workspace-context | Discover the bearer API key's own organization and bounded projects | account:read |
Regeneration contract
The API repository generates /openapi.json from its canonical schema. This docs
repository checks in a snapshot so builds and reviews do not depend on the network.
Refresh that snapshot from the reviewed API source, then run:
python3 scripts/generate_openapi_reference.py --check
python3 -m unittest discover -s testsIf the snapshot contains a new customer route, update the conceptual guide that explains its product model as well. Do not hand-copy request schemas into prose.