Speko Docs
API Reference

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

EnvironmentBase URL
Productionhttps://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"
}
FieldPresentMeaning
errorAlwaysHuman-readable message. The wording can change, so do not match on it.
codeAlwaysStable, machine-readable code. Branch on this.
retryableWhen the code is in the catalogWhether sending the identical request again could succeed.
docs_urlWith retryableThe code's entry in Error codes.
hintSome codesWhat to do about it, where one has been written.
issuesVALIDATION_ERROROne { 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.

On this page