Introduction
Public REST API for the Speko voice gateway.
Welcome
The Speko API exposes the voice gateway and agent control plane from https://api.speko.dev. Core endpoints include sessions, sessions/phone, phone-numbers, calls, callbacks, transcribe, synthesize, complete, agents, knowledge-bases, usage, credits, and provider configuration. Calls that carry a routing intent let Speko pick the highest-scoring provider and fail over server-side. Phone calls support inbound routing, outbound PSTN dialing, lifecycle webhooks, post-call reports, recordings, and blind or warm transfers. The full spec is below.
OpenAPI specification
View the OpenAPI 3.1 spec file
Servers
| Environment | Base URL |
|---|---|
| Production | https://api.speko.dev |
Authentication
All endpoints are authenticated with a bearer API key. Mint one at API keys.
Authorization: Bearer sk_live_...The OpenAPI spec declares this scheme as bearerAuth:
"security": [
{
"bearerAuth": []
}
]Errors
Error responses are JSON with this envelope:
{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [{ "path": "to", "message": "Required" }],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}| Field | Present | Meaning |
|---|---|---|
error | Always | Human-readable message. The wording can change, so do not match on it. |
code | Always | Stable, machine-readable code. Branch on this. |
retryable | When the code is in the catalog | Whether sending the identical request again could succeed. |
docs_url | With retryable | The code's entry in Error codes. |
hint | Some codes | What to do about it, where one has been written. |
issues | VALIDATION_ERROR | One { path, message } per field that failed validation. |
Some codes add fields of their own, documented on the endpoint that returns them. For example, PIPELINE_CONFIG_TOO_LARGE carries bytes and limit.
A few endpoints, such as the voice library, nest their code inside an object, as in { "error": { "code": "VOICE_NOT_FOUND" } }. For codes in the catalog those responses also carry the top-level code, retryable, and docs_url.
Retrying
Retry only when retryable is true, and back off between attempts. A 429 response carries a Retry-After header with the number of seconds to wait when the server knows it; wait at least that long. When retryable is false, sending the same request again will fail the same way: change the request or fix the cause first, such as adding credits.
Looking up a code
Error codes lists every code with its meaning. The same catalog is available as JSON from GET /v1/errors, and GET /v1/errors/{code} explains one code. Neither needs an API key.