# 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.

> **The same thing, machine-readable:** [openapi.json](https://voice.sphoro.com/openapi.json) and [openapi.yaml](https://voice.sphoro.com/openapi.yaml). Most code generators and coding assistants take either directly — see [build with AI](https://voice.sphoro.com/docs/build-with-ai).

Everything is under `https://voice.sphoro.com`, carries `Authorization: Bearer …`, and speaks JSON. [Using your API key](https://voice.sphoro.com/docs/authentication) 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.

**Shell**

```bash
# 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](https://voice.sphoro.com/docs/agents).

| 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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/calls).

| 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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/functions).

| Endpoint | Does |
| --- | --- |
| GET `/v1/functions` | List callable functions |

## Webhooks

What these are for: [5. Webhooks](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/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](https://voice.sphoro.com/docs/projects).

| 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](https://voice.sphoro.com/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](https://voice.sphoro.com/docs/agents) is the big one, and [flows](https://voice.sphoro.com/docs/flows), [journeys](https://voice.sphoro.com/docs/journeys) and [post-call analysis](https://voice.sphoro.com/docs/post-call) 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](https://voice.sphoro.com/docs/agents). |
| 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](https://voice.sphoro.com/docs/authentication) on this site. |