API reference
Every endpoint this deployment serves, generated from the running server — so it describes the version you are actually talking to rather than a snapshot somebody exported. For what the fields mean and which combinations make sense, follow the links: this page is the index, not the explanation.
Everything is under https://voice.sphoro.com, carries
Authorization: Bearer …, and speaks JSON.
Using your API key covers the header, pagination, rate
limits, idempotency and every error code.
The same list, as data
Everything on this page comes from one document, which you can read directly — and which carries the request bodies and response schemas this page deliberately does not repeat.
# Every path and method this deployment serves.
curl -s https://voice.sphoro.com/openapi.json | jq -r '
.paths | to_entries[] | .key as $p | .value | to_entries[]
| "\(.key | ascii_upcase)\t\($p)"'
# One endpoint, in full.
curl -s https://voice.sphoro.com/openapi.json | jq '.paths["/v1/calls"].post'62 endpoints, in 9 groups.
Agents
What these are for: Agent reference.
| Endpoint | Does |
|---|---|
GET /v1/agents | List agents |
POST /v1/agents | Create an agent |
DELETE /v1/agents/{id} | Delete an agent |
GET /v1/agents/{id} | Retrieve an agent |
PATCH /v1/agents/{id} | Update an agent |
POST /v1/agents/{id}/post_call/test | Test an agent's post-call settings |
POST /v1/agents/{id}/restore | Restore a deleted agent |
Agent groups
What these are for: Agent groups.
| Endpoint | Does |
|---|---|
GET /v1/agent_groups | List agent groups |
POST /v1/agent_groups | Create an agent group |
DELETE /v1/agent_groups/{id} | Delete an agent group |
GET /v1/agent_groups/{id} | Retrieve an agent group |
PATCH /v1/agent_groups/{id} | Update an agent group |
GET /v1/agent_groups/{id}/members | List a group's agents |
Knowledge bases
What these are for: Knowledge base.
| Endpoint | Does |
|---|---|
GET /v1/knowledge_bases | List knowledge bases |
POST /v1/knowledge_bases | Create a knowledge base |
DELETE /v1/knowledge_bases/{id} | Delete a knowledge base and everything in it |
GET /v1/knowledge_bases/{id} | Retrieve a knowledge base |
GET /v1/knowledge_bases/{id}/documents | List documents |
POST /v1/knowledge_bases/{id}/documents | Ingest a document |
DELETE /v1/knowledge_bases/{id}/documents/{doc} | Delete a document |
POST /v1/knowledge_bases/{id}/search | Search a knowledge base |
Calls
What these are for: 3. Make a call.
| Endpoint | Does |
|---|---|
GET /v1/calls | List calls |
POST /v1/calls | Start a call |
POST /v1/calls/rendezvous | Place a call between two people |
GET /v1/calls/ringing | Watch for calls waiting to be answered |
GET /v1/calls/{id} | Retrieve a call |
POST /v1/calls/{id}/claim | Answer a ringing call |
POST /v1/calls/{id}/end | End a call |
GET /v1/calls/{id}/events | Stream call events |
POST /v1/calls/{id}/events | Inject an event into a live call |
POST /v1/calls/{id}/give-up | Record that nobody answered |
GET /v1/calls/{id}/recording | Download a recording |
GET /v1/calls/{id}/recording_url | Get a playable recording link |
POST /v1/calls/{id}/seat | Take one end of a rendezvous |
POST /v1/calls/{id}/token | Join a call from a browser |
GET /v1/calls/{id}/transcript | Retrieve a transcript |
POST /v1/realtime/tokens | Mint a browser token |
Workflows
What these are for: Workflows.
| Endpoint | Does |
|---|---|
GET /v1/workflows | List workflows |
POST /v1/workflows | Create a workflow |
DELETE /v1/workflows/{id} | Delete a workflow |
GET /v1/workflows/{id} | Retrieve a workflow |
PATCH /v1/workflows/{id} | Update a workflow |
GET /v1/workflows/{id}/runs | List workflow runs |
POST /v1/workflows/{id}/runs | Run a workflow |
Functions
What these are for: Tools and functions.
| Endpoint | Does |
|---|---|
GET /v1/functions | List callable functions |
Webhooks
What these are for: 5. Webhooks.
| Endpoint | Does |
|---|---|
GET /v1/webhook_endpoints | List webhook endpoints |
POST /v1/webhook_endpoints | Create a webhook endpoint |
PUT /v1/webhook_endpoints | Declare a webhook endpoint |
DELETE /v1/webhook_endpoints/{id} | Delete a webhook endpoint |
GET /v1/webhook_endpoints/{id} | Retrieve a webhook endpoint |
PATCH /v1/webhook_endpoints/{id} | Update a webhook endpoint |
GET /v1/webhook_endpoints/{id}/deliveries | List delivery attempts |
POST /v1/webhook_endpoints/{id}/test | Send a test event |
Analytics
What these are for: Analytics.
| Endpoint | Does |
|---|---|
GET /healthz | Liveness probe |
POST /v1/analytics/csat | Record a satisfaction rating |
GET /v1/analytics/overview | Usage and quality overview |
GET /v1/analytics/timeseries | Bucketed call volume and cost |
Projects
What these are for: Projects and budgets.
| Endpoint | Does |
|---|---|
GET /v1/projects | List projects |
POST /v1/projects | Create a project |
DELETE /v1/projects/{id} | Delete a project |
GET /v1/projects/{id} | Retrieve a project |
PATCH /v1/projects/{id} | Update a project |
Request bodies and response shapes
Deliberately not repeated here. Every field of every body, with its type, its bounds and its default, is in openapi.json — where it is generated from the same code that validates the request, and therefore cannot disagree with it. A table on this page could.
For the fields you will actually be writing by hand, the guide pages carry them with the reasoning attached: agent reference is the big one, and flows, journeys and post-call analysis cover the nested shapes.
Conventions
| Versioning | Every path is under /v1. New fields are added without a
version bump; nothing is removed from a version. |
| Unknown fields | Refused with a 400 naming the field, never silently
dropped. |
| Lists and blocks | Replace whole on a PATCH. Scalars merge. See
agent reference. |
| Identifiers | Opaque prefixed strings. Store them whole. |
| Timestamps | RFC 3339, in UTC. |
| Idempotency | Idempotency-Key on any POST that has a side
effect. A retry with the same key returns the original response. |
| Errors | A problem document with a type that links into
the error table on this site. |