# Speko developer docs (/)

Explore Speko Router, Gateway, SDKs, and MCP for building and operating production voice AI.



<DocsOverview />


# Audio helpers (/adapter-livekit/audio)

WAV encode / decode and MIME parsing utilities.



The adapter exports the three audio helpers it uses internally. They're stable exports — safe to reuse if you're building custom pipelines or writing tests.

```ts
import {
  framesToWav,
  parseWav,
  pcmSampleRateFromContentType,
} from '@spekoai/adapter-livekit';
```

## `framesToWav` [#framestowav]

```ts
function framesToWav(buffer: AudioBuffer): Uint8Array;
```

Encode one or more LiveKit `AudioFrame`s (or an array) into a PCM16 mono WAV byte stream. Used by `SpekoSTT` to wrap each utterance before uploading to `/v1/transcribe`.

* Combines frames via `combineAudioFrames` from `@livekit/rtc-node`.
* Writes a standard 44-byte RIFF/WAVE header: `fmt ` chunk (PCM, 16-bit, mono, `sampleRate` from frames) + `data` chunk.
* Sample rate is pulled from the input frames — whatever LiveKit gives you is what's encoded.

**Mono-only.** A multi-channel `AudioBuffer` throws:

```
SpekoSTT: expected mono audio (1 channel), got 2. Configure your LiveKit AgentSession to pass mono audio or pre-mix upstream of the STT.
```

## `parseWav` [#parsewav]

```ts
function parseWav(bytes: Uint8Array): {
  pcm: Uint8Array;
  sampleRate: number;
  channels: number;
};
```

Minimal PCM16 WAV parser. Used by `SpekoTTS` to unwrap WAV-encoded proxy responses into raw samples for `AudioByteStream`.

Accepted subset:

* Valid `RIFF` / `WAVE` header.
* `fmt ` chunk present and of `format = 1` (PCM).
* 16-bit samples.
* `data` chunk reachable by walking subsequent chunks (tolerates e.g. `LIST` chunks between `fmt ` and `data`).

Anything outside this subset throws a coded `SpekoAdapterError`: `MALFORMED_AUDIO` for a truncated or non-RIFF payload (retryable, so the router can fail over) and `UNSUPPORTED_AUDIO_FORMAT` for non-PCM or non-16-bit audio (not retryable — retrying a misconfigured provider changes nothing). `channels` is returned as-is; the caller decides whether stereo is acceptable, and `SpekoTTS` rejects it with `UNSUPPORTED_CHANNELS`.

## `pcmSampleRateFromContentType` [#pcmsampleratefromcontenttype]

```ts
function pcmSampleRateFromContentType(
  contentType: string,
  fallback: number,
): number;
```

Parse the `rate` parameter out of a Cartesia-style content type:

```ts
pcmSampleRateFromContentType('audio/pcm;rate=24000', 16_000); // 24000
pcmSampleRateFromContentType('audio/pcm', 16_000);            // 16000
pcmSampleRateFromContentType('audio/pcm;rate=abc', 16_000);   // 16000
```

Falls back when the rate is missing, zero, or unparseable. Case-insensitive on `rate=`.

## `createSampleRateNormalizer` [#createsampleratenormalizer]

```ts
function createSampleRateNormalizer(
  inputRate: number,
  outputRate: number,
  channels?: number,
): SampleRateNormalizer;

interface SampleRateNormalizer {
  readonly resampling: boolean;
  push(frame: AudioFrame): AudioFrame[];
  flush(): AudioFrame[];
  close(): void;
}
```

Converts frames from the rate a provider actually produced to the single rate a stage advertises. `SpekoTTS` uses it so every frame it emits carries the declared `sampleRate`, whatever the router served.

* Equal rates return a pass-through: `resampling` is `false`, `push` returns the same frame instance, `flush` returns nothing, and no native handle is allocated.
* Differing rates wrap `AudioResampler` from `@livekit/rtc-node`. Call `flush()` to drain the resampler's warm-up tail, then `close()` to release the native handle — `close()` is idempotent, so a `finally` block is the right home for it.

```ts
const normalizer = createSampleRateNormalizer(48_000, 24_000);
try {
  for (const frame of incoming) {
    for (const out of normalizer.push(frame)) emit(out);
  }
  for (const out of normalizer.flush()) emit(out);
} finally {
  normalizer.close();
}
```

## Intended usage [#intended-usage]

You shouldn't need these helpers when consuming the adapter through [`createSpekoComponents`](/adapter-livekit/create-speko-components) — they're used internally by `SpekoSTT` and `SpekoTTS`. They're exported for:

* **Unit tests** — build canned WAV fixtures with `framesToWav`, round-trip them through `parseWav`.
* **Custom STT / TTS pipelines** that need to reuse the same WAV framing Speko uses.
* **Debugging** — decode what an upstream provider returned without instantiating a full TTS.


# createSpekoComponents (/adapter-livekit/create-speko-components)

Build a { stt, llm, tts } bundle ready for voice.AgentSession.



`createSpekoComponents` is the one-call wiring helper for `voice.AgentSession`. It constructs `SpekoSTT`, `SpekoLLM`, `SpekoTTS` from a single options object and wraps STT and TTS with LiveKit's `StreamAdapter` so Speko's streaming REST proxy can drive a streaming session.

```ts
import { createSpekoComponents } from '@spekoai/adapter-livekit';

const { stt, llm, tts } = createSpekoComponents({
  speko,
  vad,
  intent: { language: 'en-US', optimizeFor: 'balanced' },
});

const session = new voice.AgentSession({ vad, stt, llm, tts });
```

## Signature [#signature]

```ts
function createSpekoComponents(
  options: CreateSpekoComponentsOptions,
): SpekoComponents;
```

## `CreateSpekoComponentsOptions` [#createspekocomponentsoptions]

| Field                    | Type                                | Required | Description                                                                                                                                                                                                                                                                                                                                               |
| ------------------------ | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `speko`                  | `Speko`                             | ✅        | Initialised `@spekoai/sdk` client.                                                                                                                                                                                                                                                                                                                        |
| `intent`                 | [`Intent`](/adapter-livekit/intent) | ✅        | Routing hint shared by STT, LLM, and TTS.                                                                                                                                                                                                                                                                                                                 |
| `vad`                    | `VAD`                               | ✅        | VAD instance used by the `stt.StreamAdapter`. Typically `await silero.VAD.load()`.                                                                                                                                                                                                                                                                        |
| `voice`                  | `string?`                           |          | Voice id passed to `SpekoTTS` (maps to the Speko proxy's `voice` param).                                                                                                                                                                                                                                                                                  |
| `constraints`            | `PipelineConstraints?`              |          | Allow-list constraints applied to all three modalities.                                                                                                                                                                                                                                                                                                   |
| `sentenceTokenizer`      | `tokenize.SentenceTokenizer?`       |          | Tokenizer for chunking LLM output before TTS. Defaults to `tokenize.basic.SentenceTokenizer`.                                                                                                                                                                                                                                                             |
| `llm`                    | `{ temperature?, maxTokens? }?`     |          | Tuning forwarded to `/v1/complete`.                                                                                                                                                                                                                                                                                                                       |
| `ttsOptions`             | `{ sampleRate?, speed? }?`          |          | Output sample rate and speech speed forwarded to `SpekoTTS`.                                                                                                                                                                                                                                                                                              |
| `agentId`                | `string?`                           |          | Enables the [registered-tools loader](/guides/tool-calling). When set, the adapter calls `speko.agents.tools.listChatTools(agentId)` once per session — using the `speko` client you pass for auth and base URL — and merges the result with LiveKit's runtime `ToolContext`. Registered tools win on name collision. Omit to keep runtime-only behavior. |
| `apiBaseUrl`             | `string?`                           |          | **Deprecated and ignored** — the loader reads the base URL from the `speko` client. Safe to omit.                                                                                                                                                                                                                                                         |
| `apiKey`                 | `string?`                           |          | **Deprecated and ignored** — the loader reads the API key from the `speko` client. Safe to omit.                                                                                                                                                                                                                                                          |
| `onRegisteredToolsError` | `(err: Error) => void?`             |          | Called once if the registered-tools fetch fails. Voice session keeps running with runtime-only tools — this is a soft degradation, not a crash.                                                                                                                                                                                                           |

## Registered tools [#registered-tools]

When `agentId` is set, `createSpekoComponents` constructs a `RegisteredToolsLoader` for the underlying `SpekoLLM`. The loader lazily calls `speko.agents.tools.listChatTools(agentId)` on the first `chat()` of each session — reusing the `Speko` client you pass for auth and base URL — and caches the result for the LLM's lifetime. Voice sessions live for seconds-to-minutes and `chat()` is called many times — re-fetching every turn would be wasteful. (`apiBaseUrl`/`apiKey` are deprecated and ignored; the `speko` client carries both.)

On collision with a runtime tool of the same name, the registered tool wins (it's the customer's authoritative declaration). Fetch failures are non-fatal — the loader returns `undefined` and the agent continues with runtime tools only, calling `onRegisteredToolsError` once.

`listChatTools` returns every source kind — `inline`, `webhook`, `builtin`, and `integration` — already in the `ChatTool[]` shape `/v1/complete` accepts.

See the [tool calling guide](/guides/tool-calling) for the full picture.

## Returns — `SpekoComponents` [#returns--spekocomponents]

```ts
interface SpekoComponents {
  stt: stt.StreamAdapter;   // wraps SpekoSTT + vad
  llm: SpekoLLM;            // used directly
  tts: tts.StreamAdapter;   // wraps SpekoTTS + sentenceTokenizer
}
```

Drop the returned object straight into a `voice.AgentSession`.

## Custom sentence tokenizer [#custom-sentence-tokenizer]

```ts
import { tokenize } from '@livekit/agents';

const { stt, llm, tts } = createSpekoComponents({
  speko,
  vad,
  intent,
  sentenceTokenizer: new tokenize.basic.SentenceTokenizer({ minSentenceLength: 20 }),
});
```

Use a longer minimum sentence length if you want fewer, longer TTS calls at the cost of latency before the first audio chunk.

## Constraints shared across modalities [#constraints-shared-across-modalities]

```ts
createSpekoComponents({
  speko,
  vad,
  intent: { language: 'en' },
  constraints: {
    allowedProviders: {
      stt: ['deepgram'],
      llm: ['anthropic'],
      tts: ['cartesia'],
    },
  },
});
```

Every underlying call (`/v1/transcribe`, `/v1/complete`, `/v1/synthesize`) receives the same constraints object.

## Opting out — use classes directly [#opting-out--use-classes-directly]

If you need finer control, construct the classes yourself. `createSpekoComponents` is a convenience wrapper; nothing stops you from building the pipeline manually.

```ts
import { SpekoSTT, SpekoLLM, SpekoTTS } from '@spekoai/adapter-livekit';
import { stt, tts, tokenize } from '@livekit/agents';

const spekoSTT = new SpekoSTT({ speko, intent });
const wrappedSTT = new stt.StreamAdapter(spekoSTT, vad);

const spekoLLM = new SpekoLLM({ speko, intent, temperature: 0.7 });

const spekoTTS = new SpekoTTS({ speko, intent, voice: 'sonic-english' });
const wrappedTTS = new tts.StreamAdapter(spekoTTS, new tokenize.basic.SentenceTokenizer());
```


# Intent (/adapter-livekit/intent)

Routing hint type and construction-time validator.



`Intent` is the routing hint every adapter class takes. It's a re-export of `RoutingIntent` from `@spekoai/sdk`, so anything you already have typed as a `RoutingIntent` passes through without conversion.

```ts
import type { Intent, OptimizeFor } from '@spekoai/adapter-livekit';
```

## Type [#type]

```ts
type Intent = {
  language: string;      // BCP-47
  region?: string;       // e.g. "global", "us-east4", "europe-west3"
  optimizeFor?: 'balanced' | 'accuracy' | 'latency' | 'cost';
};
```

## `validateIntent(intent)` [#validateintentintent]

Throws a descriptive `Error` when the intent is malformed. Called by every adapter class constructor, so a bad intent fails at construction time rather than deep inside the first STT / LLM / TTS call.

```ts
import { validateIntent } from '@spekoai/adapter-livekit';

validateIntent({ language: 'en-US' });
// ok

validateIntent({ language: '' });
// throws: SpekoAdapter: intent.language is required (BCP-47 tag)

validateIntent({ language: 'en', optimizeFor: 'speed' as any });
// throws: SpekoAdapter: unknown optimizeFor "speed". Expected one of: balanced, accuracy, latency, cost.
```

Validation rules:

* `language` must be a non-empty string.
* `region`, if set, is forwarded to Speko for region-aware latency ranking.
* `optimizeFor`, if set, must be one of `balanced`, `accuracy`, `latency`, `cost`.

No BCP-47 syntactic validation beyond "is a non-empty string" — the router accepts short codes (`en`) and region-tagged codes (`es-MX`) and normalises downstream.

## Sharing one intent [#sharing-one-intent]

The adapter pattern is "one intent per agent session, shared across modalities":

```ts
const intent: Intent = { language: 'en-US', region: 'global', optimizeFor: 'latency' };

const { stt, llm, tts } = createSpekoComponents({ speko, vad, intent });
```

If you need per-modality divergence (e.g. latency-optimised STT with cost-optimised TTS), construct the classes directly:

```ts
const sttAdapter = new SpekoSTT({ speko, intent: { ...intent, optimizeFor: 'latency' } });
const ttsAdapter = new SpekoTTS({ speko, intent: { ...intent, optimizeFor: 'cost' } });
```


# @spekoai/adapter-livekit (/adapter-livekit/overview)

LiveKit Agents adapter — route STT, LLM, and TTS through Speko.



`@spekoai/adapter-livekit` bridges a [LiveKit Agents](https://docs.livekit.io/agents/) worker to the Speko proxy. Drop it into a standard agent entry file and the router picks the best STT, LLM, and TTS provider per call. Failover is server-side; you don't ship provider API keys.

## Install [#install]

```sh
npm install @spekoai/sdk @spekoai/adapter-livekit \
            @livekit/agents @livekit/agents-plugin-silero @livekit/rtc-node
```

`@livekit/agents` and `@livekit/rtc-node` are peer dependencies — pin the versions you actually run against in your own `package.json`.

## Quickstart [#quickstart]

```ts
import {
  type JobContext,
  type JobProcess,
  ServerOptions,
  cli,
  defineAgent,
  voice,
} from '@livekit/agents';
import * as silero from '@livekit/agents-plugin-silero';
import { Speko } from '@spekoai/sdk';
import { createSpekoComponents } from '@spekoai/adapter-livekit';
import { fileURLToPath } from 'node:url';

const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });

export default defineAgent({
  prewarm: async (proc: JobProcess) => {
    proc.userData.vad = await silero.VAD.load();
  },
  entry: async (ctx: JobContext) => {
    const vad = ctx.proc.userData.vad as silero.VAD;

    const { stt, llm, tts } = createSpekoComponents({
      speko,
      vad,
      intent: { language: 'en-US', optimizeFor: 'balanced' },
    });

    const session = new voice.AgentSession({ vad, stt, llm, tts });

    await session.start({
      agent: new voice.Agent({
        instructions: 'You are a helpful voice assistant. Be concise.',
      }),
      room: ctx.room,
    });

    await ctx.connect();
    session.generateReply({ instructions: 'Greet the user and offer your assistance.' });
  },
});

cli.runApp(
  new ServerOptions({
    agent: fileURLToPath(import.meta.url),
    agentName: 'speko-demo',
  }),
);
```

## Architecture [#architecture]

The adapter exports three `@livekit/agents`-compatible classes — `SpekoSTT`, `SpekoLLM`, `SpekoTTS` — and a convenience factory `createSpekoComponents()` that wraps STT and TTS with `StreamAdapter` helpers so Speko's streaming REST proxy can participate in a streaming `voice.AgentSession`:

* **`SpekoSTT`** declares `{ streaming: false }`, so it must be wrapped with `new stt.StreamAdapter(spekoSTT, vad)` to segment utterances with VAD before calling `/v1/transcribe`.
* **`SpekoTTS`** is sentence-bounded in LiveKit, so it is wrapped with `new tts.StreamAdapter(spekoTTS, sentenceTokenizer)` before each streaming `/v1/synthesize` call.
* **`SpekoLLM`** is used directly — it's a `llm.LLM` backed by streaming `/v1/complete` responses.

`createSpekoComponents` handles the wrapping for you and returns `{ stt, llm, tts }` ready to pass to `voice.AgentSession`.

## v1 limitations [#v1-limitations]

* **STT request upload is utterance-bounded.** `/v1/transcribe` streams transcript events back, but this adapter still uploads one VAD-segmented WAV per utterance instead of full-duplex microphone audio.
* **TTS remains sentence-bounded in LiveKit.** `/v1/synthesize` streams audio bytes; the adapter still calls it once per tokenized sentence.
* **Tool calls are supported.** Inline tools return to the LiveKit runtime; registered webhook, builtin, and integration tools run server-side through `/v1/complete`.
* **TTS output format.** Accepts `audio/pcm;rate=NNNN` (Cartesia) and `audio/wav`. Throws on `audio/mpeg` (ElevenLabs MP3) — pick a routing intent that prefers Cartesia, or pin a PCM-capable provider via `constraints.allowedProviders.tts`.
* **STT input format.** Mono PCM16, encoded into a WAV wrapper per utterance. Multi-channel frames throw. Speko handles sample-rate conversion downstream — whatever the `AudioFrame` carries is what's uploaded.

## Reference [#reference]

* [`createSpekoComponents`](/adapter-livekit/create-speko-components) — convenience factory.
* [`SpekoSTT`](/adapter-livekit/speko-stt) — STT class.
* [`SpekoLLM`](/adapter-livekit/speko-llm) — LLM class.
* [`SpekoTTS`](/adapter-livekit/speko-tts) — TTS class.
* [`Intent`](/adapter-livekit/intent) — routing hint type and validator.
* [Audio helpers](/adapter-livekit/audio) — WAV encode/decode utilities.


# SpekoLLM (/adapter-livekit/speko-llm)

LiveKit Agents LLM adapter backed by POST /v1/complete.



`SpekoLLM` is a `llm.LLM` implementation. It flattens a LiveKit `ChatContext` into Speko's `messages` format and calls the proxy. The router picks the best LLM provider per intent and fails over automatically.

```ts
import { SpekoLLM } from '@spekoai/adapter-livekit';

const spekoLLM = new SpekoLLM({
  speko,
  intent: { language: 'en' },
  temperature: 0.7,
  maxTokens: 400,
});
```

Unlike STT and TTS, `SpekoLLM` doesn't need a `StreamAdapter`. It calls the
streaming `/v1/complete` endpoint through the SDK and emits a LiveKit
`LLMStream` chunk when the routed completion is ready.

## Constructor [#constructor]

```ts
new SpekoLLM(options: SpekoLLMOptions)
```

### `SpekoLLMOptions` [#spekollmoptions]

| Field                    | Type                                | Required | Description                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------ | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `speko`                  | `Speko`                             | ✅        | `@spekoai/sdk` client.                                                                                                                                                                                                                                                                                                                                        |
| `intent`                 | [`Intent`](/adapter-livekit/intent) | ✅        | Validated at construction time.                                                                                                                                                                                                                                                                                                                               |
| `temperature`            | `number?`                           |          | Forwarded to `/v1/complete`.                                                                                                                                                                                                                                                                                                                                  |
| `maxTokens`              | `number?`                           |          | Forwarded to `/v1/complete`.                                                                                                                                                                                                                                                                                                                                  |
| `constraints`            | `PipelineConstraints?`              |          | Allow-list constraints.                                                                                                                                                                                                                                                                                                                                       |
| `agentId`                | `string?`                           |          | When set, enables the registered-tools loader. The adapter calls `speko.agents.tools.listChatTools(agentId)` once per session — using the `speko` client for auth and base URL — and merges the result with LiveKit's runtime `ToolContext`. Registered tools win on collision. Omit to keep runtime-only behavior. See [tool calling](/guides/tool-calling). |
| `apiBaseUrl`             | `string?`                           |          | **Deprecated and ignored** — the loader reads the base URL from the `speko` client. Safe to omit.                                                                                                                                                                                                                                                             |
| `apiKey`                 | `string?`                           |          | **Deprecated and ignored** — the loader reads the API key from the `speko` client. Safe to omit.                                                                                                                                                                                                                                                              |
| `onRegisteredToolsError` | `(err: Error) => void?`             |          | Called once if the registered-tools fetch fails. Soft degradation — the call continues with runtime-only tools rather than crashing.                                                                                                                                                                                                                          |

## Properties [#properties]

* `label() → 'speko.LLM'`
* `provider = 'speko'`
* `model = 'speko-router'`

## `.chat(params)` [#chatparams]

Standard LiveKit LLM entry point. Returns an `LLMStream` that emits a `ChatChunk`
carrying the assistant response or tool calls, then closes.

Signature (from `@livekit/agents`):

```ts
chat(params: {
  chatCtx: llm.ChatContext;
  toolCtx?: llm.ToolContext;
  connOptions?: APIConnectOptions;
  parallelToolCalls?: boolean;
  toolChoice?: llm.ToolChoice;
  extraKwargs?: Record<string, unknown>;
}): llm.LLMStream;
```

The emitted chunk includes usage:

```ts
{
  id: '<uuid>',
  delta: { role: 'assistant', content: result.text },
  usage: {
    promptTokens: result.usage.promptTokens,
    completionTokens: result.usage.completionTokens,
    promptCachedTokens: 0,
    totalTokens: result.usage.promptTokens + result.usage.completionTokens,
  },
}
```

## Context conversion — `chatContextToSpeko` [#context-conversion--chatcontexttospeko]

Exported for when you want to reuse the flattening logic (e.g. unit tests, custom pipelines).

```ts
import { chatContextToSpeko } from '@spekoai/adapter-livekit';

const messages = chatContextToSpeko(chatCtx);
```

Rules:

* Only `llm.ChatMessage` items are considered. Function-call and handoff items are skipped.
* Roles are normalised: `developer` → `system`; `system` / `user` / `assistant` pass through; anything else is dropped.
* Empty `textContent` messages are skipped.
* Ordering is preserved.

If the result is empty, `.chat()` rejects with `SpekoAdapterError('INVALID_CONTEXT')`.

## Tool Calls [#tool-calls]

Runtime tools from LiveKit's `toolCtx` are forwarded as inline tools. Registered
webhook, builtin, and integration tools can also be loaded by `agentId` — the
same set `speko.agents.tools.listChatTools(agentId)` returns — and executed
server-side by Speko before the final response is returned to LiveKit.

## Errors [#errors]

* `SpekoAdapterError` (exported): thrown for adapter-internal problems. `code` is one of:
  * `'INVALID_CONTEXT'` — `ChatContext` produced no convertible messages.

API-layer errors from the underlying `speko.complete()` surface unchanged — `SpekoApiError`, `SpekoAuthError`, `SpekoRateLimitError` from `@spekoai/sdk`.


# SpekoSTT (/adapter-livekit/speko-stt)

LiveKit Agents STT adapter backed by POST /v1/transcribe.



`SpekoSTT` is a `stt.STT` implementation. It encodes each utterance's audio frames into a WAV payload and uploads it to the Speko proxy. The router picks the best STT provider for your `(language, region, optimizeFor)` and handles failover.

```ts
import { SpekoSTT } from '@spekoai/adapter-livekit';
import { stt as sttNs } from '@livekit/agents';

const spekoSTT = new SpekoSTT({
  speko,
  intent: { language: 'en-US' },
});

const wrapped = new sttNs.StreamAdapter(spekoSTT, vad);
```

## Constructor [#constructor]

```ts
new SpekoSTT(options: SpekoSTTOptions)
```

### `SpekoSTTOptions` [#spekosttoptions]

| Field         | Type                                | Required | Description                                  |
| ------------- | ----------------------------------- | -------- | -------------------------------------------- |
| `speko`       | `Speko`                             | ✅        | `@spekoai/sdk` client.                       |
| `intent`      | [`Intent`](/adapter-livekit/intent) | ✅        | Validated at construction time.              |
| `constraints` | `PipelineConstraints?`              |          | Allow-list constraints passed on every call. |

The constructor calls `validateIntent(intent)` — a broken routing hint throws here rather than deep inside the first transcription.

## Properties [#properties]

* `label = 'speko.STT'`
* `provider = 'speko'`
* `model = 'speko-router'`
* `streaming = false`, `interimResults = false`

## Streaming requirement [#streaming-requirement]

`SpekoSTT.stream()` throws because this adapter uploads one VAD-segmented WAV per
utterance. The `/v1/transcribe` response itself streams transcript events, and
`speko.transcribe()` aggregates the final result for this class. Wrap the
instance:

```ts
import { stt } from '@livekit/agents';

const adapter = new stt.StreamAdapter(spekoSTT, vad);
```

Or use [`createSpekoComponents`](/adapter-livekit/create-speko-components) which does this for you.

## Per-utterance flow [#per-utterance-flow]

1. `StreamAdapter` + VAD segment the user's audio into utterances.
2. `SpekoSTT._recognize(frame, abortSignal)` is invoked for each utterance.
3. Frames are combined (`combineAudioFrames`) and encoded into PCM16 mono WAV via [`framesToWav`](/adapter-livekit/audio#framestowav).
4. The WAV is uploaded via `speko.transcribe()` with the intent header and any `constraints`.
5. The result is emitted as a single `FINAL_TRANSCRIPT` event with confidence defaulting to `1` when the upstream provider doesn't report one.

Aborts propagate: when the session tears down, the `AbortSignal` passed by `StreamAdapter` cancels the in-flight HTTP request.

## Mono-only [#mono-only]

Multi-channel audio throws at the WAV-encode step:

```
SpekoSTT: expected mono audio (1 channel), got 2. …
```

Configure your LiveKit `AgentSession` to pass mono audio, or pre-mix upstream.


# SpekoTTS (/adapter-livekit/speko-tts)

LiveKit Agents TTS adapter backed by POST /v1/synthesize.



`SpekoTTS` is a `tts.TTS` implementation. Each sentence is synthesised via the Speko proxy, decoded into PCM, chunked into `AudioFrame`s at 50 Hz (20 ms frames), and pushed to the LiveKit session.

```ts
import { SpekoTTS } from '@spekoai/adapter-livekit';
import { tts as ttsNs, tokenize } from '@livekit/agents';

const spekoTTS = new SpekoTTS({
  speko,
  intent: { language: 'en' },
  voice: 'sonic-english',
  sampleRate: 24_000,
});

const wrapped = new ttsNs.StreamAdapter(spekoTTS, new tokenize.basic.SentenceTokenizer());
```

## Constructor [#constructor]

```ts
new SpekoTTS(options: SpekoTTSOptions)
```

### `SpekoTTSOptions` [#spekottsoptions]

| Field         | Type                                | Required | Description                                                                                                                                            |
| ------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `speko`       | `Speko`                             | ✅        | `@spekoai/sdk` client.                                                                                                                                 |
| `intent`      | [`Intent`](/adapter-livekit/intent) | ✅        | Validated at construction time.                                                                                                                        |
| `voice`       | `string?`                           |          | Voice id forwarded to the proxy.                                                                                                                       |
| `speed`       | `number?`                           |          | Speech-speed multiplier forwarded to the proxy.                                                                                                        |
| `sampleRate`  | `number?`                           |          | Output sample rate advertised to LiveKit. Default `24000`. Every emitted frame is at this rate; a provider that emits another rate is resampled to it. |
| `constraints` | `PipelineConstraints?`              |          | Allow-list constraints.                                                                                                                                |

## Properties [#properties]

* `label = 'speko.TTS'`
* `provider = 'speko'`
* `model = 'speko-router'`
* `numChannels = 1`, `streaming = false`

## Streaming requirement [#streaming-requirement]

`SpekoTTS.stream()` throws because LiveKit's TTS `StreamAdapter` handles
sentence tokenization for this class. `/v1/synthesize` streams audio bytes for
each sentence request. Wrap:

```ts
import { tts, tokenize } from '@livekit/agents';

const adapter = new tts.StreamAdapter(spekoTTS, new tokenize.basic.SentenceTokenizer());
```

Or use [`createSpekoComponents`](/adapter-livekit/create-speko-components) which does this for you.

## `.synthesize(text, connOptions?, abortSignal?)` [#synthesizetext-connoptions-abortsignal]

Returns a `SpekoTTSChunkedStream` (exported for type use). Internally:

1. Calls `speko.synthesize(text, { ...intent, voice, speed, constraints })`.
2. Reads the response's real audio format from `X-Speko-Audio-Format` (falling back to `Content-Type`) and decodes via [`decodeSynthesisResult`](#decodesynthesisresult).
3. Chunks the PCM into `AudioFrame`s of `round(responseRate / 50)` samples each via `AudioByteStream`.
4. Resamples to the configured `sampleRate` when the response rate differs, so playback is never pitched. Matching rates are a zero-copy pass-through.
5. Pushes frames onto the output queue, marking the last one `final: true`.

Empty provider output throws `SpekoTTS: provider returned empty audio`.

## Audio format support (v1) [#audio-format-support-v1]

`decodeSynthesisResult(result)` branches on `result.contentType`:

| Content type                | Behavior                                                                                                    |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `audio/pcm;rate=NNNN`       | Raw PCM, rate parsed from the MIME. Channels pinned to `1` (Cartesia's contract).                           |
| `audio/wav` / `audio/x-wav` | Header stripped via [`parseWav`](/adapter-livekit/audio#parsewav). Stereo WAV throws.                       |
| `audio/mpeg`                | Throws — v1 doesn't include an MP3 decoder. Pin Cartesia or another PCM-capable provider via `constraints`. |
| anything else               | Throws with provider info for debugging.                                                                    |

Work around MP3 by pinning your TTS pool:

```ts
new SpekoTTS({
  speko,
  intent,
  constraints: { allowedProviders: { tts: ['cartesia'] } },
});
```

## Sample rates [#sample-rates]

The router serves whatever rate the chosen provider produces: 24 kHz for most, 48 kHz for Hume and Gradium, 16 kHz for Amazon Polly. The adapter reads that rate per response from `X-Speko-Audio-Format` and resamples to the `sampleRate` this instance advertises, so routing to (or failing over onto) a provider at another rate is handled rather than fatal.

Since v0.1.3 a differing rate is no longer an error. Earlier versions rejected the utterance with `SpekoTTS: provider returned audio at 16000 Hz but the TTS was configured for 24000 Hz`.

Set `sampleRate` to the rate your pipeline wants; leaving it at the 24 kHz default is the cheapest option because most providers emit it natively and need no resampling.

## `decodeSynthesisResult` [#decodesynthesisresult]

Exported for unit testing. Given a `SynthesizeResult` (and optionally the audio-format string to branch on, normally the response's `X-Speko-Audio-Format`), returns `{ pcm, sampleRate, channels }`. Throws for unsupported content types (see table above). The returned `sampleRate` is whatever the response declares; the caller normalizes it.

```ts
import { decodeSynthesisResult } from '@spekoai/adapter-livekit';
```


# @spekoai/ai-sdk-provider (/ai-sdk-provider/overview)

Speko provider for the Vercel AI SDK — routed speech and transcription.



`@spekoai/ai-sdk-provider` plugs Speko into the [Vercel AI SDK](https://ai-sdk.dev) as a speech and transcription provider. One provider entry replaces per-vendor voice code, and Speko's router picks the upstream provider per request.

## Install [#install]

```bash
npm install @spekoai/ai-sdk-provider ai
```

## Setup [#setup]

Get a key at [platform.speko.ai](https://platform.speko.ai/agents/keys) and set `SPEKO_API_KEY`. The default instance reads it from the environment:

```ts
import { speko } from '@spekoai/ai-sdk-provider';
```

To pass the key explicitly, or point at another base URL:

```ts
import { createSpeko } from '@spekoai/ai-sdk-provider';

const speko = createSpeko({
  apiKey: process.env.SPEKO_API_KEY,
});
```

## First call [#first-call]

```ts
import { speko } from '@spekoai/ai-sdk-provider';
import { generateSpeech } from 'ai';

const { audio } = await generateSpeech({
  model: speko.speech('auto'),
  text: 'Welcome to Speko.',
});
```

`audio.uint8Array` holds WAV bytes. Speko synthesizes raw PCM and this provider wraps it in a WAV container at the routed provider's sample rate.

## What it implements [#what-it-implements]

Provider specification v4 — `SpeechModelV4` and `TranscriptionModelV4` — for `ai` v7.

`languageModel`, `embeddingModel`, and `imageModel` throw `NoSuchModelError`. Speko is a voice platform.

## Next [#next]

<Cards>
  <Card title="Speech" href="/ai-sdk-provider/speech" description="Synthesize audio with generateSpeech." />

  <Card title="Transcription" href="/ai-sdk-provider/transcription" description="Transcribe audio with transcribe." />

  <Card title="Routing options" href="/ai-sdk-provider/routing" description="Model ids and providerOptions.speko." />
</Cards>


# Routing options (/ai-sdk-provider/routing)

Model ids and providerOptions.speko for the AI SDK provider.



The model id selects a routing strategy, not a single model.

## Model ids [#model-ids]

| Model id                            | Behavior                                               |
| ----------------------------------- | ------------------------------------------------------ |
| `auto`                              | Router default for your organization's routing policy  |
| `auto-fast`                         | Bias toward latency                                    |
| `auto-quality`                      | Bias toward accuracy and quality                       |
| `auto-cheap`                        | Bias toward cost                                       |
| `deepgram`                          | Pin routing and failover to one upstream provider      |
| `elevenlabs/eleven_multilingual_v2` | Pin the provider and request a specific upstream model |

```ts
speko.transcription('auto-quality');
speko.speech('elevenlabs/eleven_multilingual_v2');
```

## providerOptions.speko [#provideroptionsspeko]

| Option         | Applies to    | Description                                                                          |
| -------------- | ------------- | ------------------------------------------------------------------------------------ |
| `language`     | both          | BCP-47 tag, for example `en` or `es-MX`. Routing is language-aware. Defaults to `en` |
| `region`       | both          | Region to rank providers in, for example `us-east4` or `eu-west1`                    |
| `optimizeFor`  | both          | `balanced`, `accuracy`, `latency`, or `cost`. Overrides the model id preset          |
| `providers`    | both          | Restrict routing and failover to these upstream providers                            |
| `keywords`     | transcription | Domain keywords forwarded to the routed STT provider                                 |
| `outputFormat` | speech        | `wav` (default) or `pcm` for raw s16le mono                                          |
| `model`        | speech        | Upstream model override, for example `sonic-2`                                       |
| `spokenForm`   | speech        | Deterministic spoken-form normalization before synthesis                             |

## Failover [#failover]

Failover happens server-side. If the routed provider errors or degrades, Speko retries against the next-ranked provider before the call returns. A single `generateSpeech` or `transcribe` call can therefore cross providers without the caller noticing.

`providerMetadata.speko.failoverCount` reports how many were tried. Use `providers` to constrain the pool the router and its failover may draw from.

## Unsupported settings [#unsupported-settings]

`fetch` and `headers` provider settings are not supported. `@spekoai/sdk` manages its own transport and headers, so custom headers produce an unsupported-setting warning rather than being sent.


# Speech (/ai-sdk-provider/speech)

Synthesize audio through generateSpeech with routed TTS providers.



Pass `speko.speech(...)` to the AI SDK's `generateSpeech`.

```ts
import { speko } from '@spekoai/ai-sdk-provider';
import { generateSpeech } from 'ai';

const { audio } = await generateSpeech({
  model: speko.speech('auto'),
  text: 'Welcome to Speko.',
  voice: 'QtY3JBOUKEB5xzrRfOKc',
  providerOptions: {
    speko: { language: 'en', optimizeFor: 'latency' },
  },
});
```

`voice` is optional and provider-specific. Leave it out and the router picks a voice for the resolved language.

## Output format [#output-format]

`audio.uint8Array` returns WAV by default. Request raw signed 16-bit little-endian mono PCM instead:

```ts
const { audio } = await generateSpeech({
  model: speko.speech('auto'),
  text: 'Welcome to Speko.',
  providerOptions: {
    speko: { outputFormat: 'pcm' },
  },
});
```

The sample rate of the routed provider is reported in `providerMetadata.speko.sampleRate`.

## Pinning a provider or model [#pinning-a-provider-or-model]

The model id selects a routing strategy rather than a single model:

```ts
speko.speech('auto-quality');                        // bias toward quality
speko.speech('elevenlabs/eleven_multilingual_v2');   // pin provider and model
```

See [Routing options](/ai-sdk-provider/routing) for the full id list and every `providerOptions.speko` field.


# Transcription (/ai-sdk-provider/transcription)

Transcribe audio through transcribe with routed STT providers.



Pass `speko.transcription(...)` to the AI SDK's `transcribe`.

```ts
import { speko } from '@spekoai/ai-sdk-provider';
import { transcribe } from 'ai';
import { readFile } from 'node:fs/promises';

const result = await transcribe({
  model: speko.transcription('auto'),
  audio: await readFile('call.wav'),
  providerOptions: {
    speko: {
      language: 'es-MX',
      keywords: ['Speko', 'Vercel'],
    },
  },
});

console.log(result.text);
```

`keywords` are domain terms forwarded to the routed STT provider, which improves recognition of names and product vocabulary.

## Which provider answered [#which-provider-answered]

`providerMetadata.speko` reports what the router did:

```ts
console.log(result.providerMetadata.speko);
// { provider: 'deepgram', model: 'nova-3', confidence: 0.93, failoverCount: 0, scoresRunId: '...' }
```

`failoverCount` is the number of upstream providers tried before one succeeded.

## Segments and duration [#segments-and-duration]

| Input          | `durationInSeconds` | `segments`                   |
| -------------- | ------------------- | ---------------------------- |
| WAV or raw PCM | reported            | one whole-transcript segment |
| Other formats  | `undefined`         | empty                        |

The one-shot transcription endpoint does not report per-word timing yet, so duration is only available when the input length is deterministic.

## Pinning a provider [#pinning-a-provider]

```ts
speko.transcription('auto-quality');   // bias toward accuracy
speko.transcription('deepgram');       // pin routing and failover to one provider
```

See [Routing options](/ai-sdk-provider/routing) for every model id and option.


# Signing in (/cli/auth)

How speko-cli authenticates, what it stores, and how to revoke a terminal.



```bash
speko-cli login
```

Prints a short code and a URL. A human approves it in a browser — that step
cannot be automated, and it is the only one that cannot.

## Why a device grant [#why-a-device-grant]

`speko-cli login` uses the [RFC 8628 device authorization grant](https://datatracker.ietf.org/doc/html/rfc8628)
rather than a loopback redirect, because the CLI often runs where no browser can
reach it: a container, an SSH session, a coding agent's sandbox. A loopback
redirect assumes `localhost` is the same machine as the browser. Frequently it
is not.

## It never blocks an agent [#it-never-blocks-an-agent]

When output is not a terminal — which is the case for every coding agent — or
when `--no-wait` is passed, `login` prints the URL, writes the pending grant
down, and exits 0. Run it again to finish once a human has approved.

```bash
speko-cli login --no-wait   # prints the URL, returns immediately
speko-cli login             # run again to complete
```

This matters: a command that blocks for fifteen minutes hangs an agent's whole
session, and the agent will abandon the task rather than wait.

## What it stores [#what-it-stores]

A **session token**, in `~/.config/speko/credentials.json` at mode `0600` (or
under `XDG_CONFIG_HOME` where set).

That token is as powerful as being signed in — treat the file as a secret.

## A CLI session is deliberately weaker than a browser one [#a-cli-session-is-deliberately-weaker-than-a-browser-one]

`speko-cli whoami` shows three scopes where a browser session holds six:

```
speko:read  speko:write  speko:execute
```

Absent are `speko:credentials`, `speko:billing` and `speko:compliance`. So a
terminal cannot read the organization's master MCP key or webhook signing
secret, even though the same login works in both places. The server marks the
session's origin when it is minted, and that marker is not derived from anything
the client sends.

## Revoking [#revoking]

```bash
speko-cli auth list              # every signed-in terminal, current one marked
speko-cli auth revoke <id>       # end one session
speko-cli auth revoke --all      # end every CLI session, including this one
speko-cli logout                 # local only — clears the file, session stays valid
```

`logout` is local and says so. Revoking is what actually ends access.
`auth list` and the console's CLI devices page read the same endpoints, so the
two cannot disagree about what is signed in.


# Benchmarks (/cli/benchmarks)

The measured provider scores routing decides on, from the terminal.



```bash
speko-cli bench                       # every stage
speko-cli bench stt --language nb     # ranked by word error rate
speko-cli bench llm                   # ranked by measured latency
speko-cli bench tts --provider cartesia
speko-cli bench session <session_id>  # what one call actually ran on
```

The stage boards need no credential. These are published measurements, and the
person most likely to want them is deciding whether to sign up at all.

`bench session` is the one exception — a session belongs to a workspace, so it
requires sign-in and exits 3 without it.

## What the columns mean [#what-the-columns-mean]

| Column    |                                                              |
| --------- | ------------------------------------------------------------ |
| `WER`     | Word error rate at p50. Lower is better. Transcription only. |
| `LATENCY` | Measured first-response latency at p50, in ms.               |
| `$/MIN`   | Cost per minute, where it has been measured.                 |

Stages rank on the axis that means something for them: transcription on word
error rate, everything else on latency. Sorting a language model by a
transcription metric would put an arbitrary row on top.

## A dash is not a zero [#a-dash-is-not-a-zero]

`—` means the metric was **not measured**. It never means zero.

The distinction is load-bearing for cost: a provider nobody has priced would
otherwise render as `$0.0000` and look like the cheapest option on the board.
Unmeasured values are omitted rather than defaulted, all the way through the API.

## What one call ran on [#what-one-call-ran-on]

```bash
speko-cli bench session <session_id>
```

Joins the session's actual pipeline against the measured rows: what ran, what was
measured about it, and the best measured option for the same stage and language.

It does **not** explain why that stack was chosen. A session records what ran and
no reason beside it, so any explanation would be reconstructed after the fact —
and the command says so on every run rather than implying otherwise.


# Errors and exit codes (/cli/errors)

Exit codes are part of the contract, and every error body says whether to retry.



## Exit codes [#exit-codes]

Stable, and part of the contract — a caller in CI must be able to tell these
apart without parsing prose.

| Code | Meaning                                         |
| ---- | ----------------------------------------------- |
| 0    | Success                                         |
| 1    | Runtime failure (network, server error)         |
| 2    | Usage error (unknown command, missing argument) |
| 3    | Not signed in, or the credential was rejected   |
| 4    | Resource not found                              |
| 5    | Out of credit, or rate limited                  |
| 6    | An eval suite regressed                         |

`3` is how a script checks before assuming it can act:

```bash
speko-cli whoami >/dev/null 2>&1 || { echo "run: speko-cli login"; exit 1; }
```

## Explaining a code [#explaining-a-code]

```bash
speko-cli explain INSUFFICIENT_CREDITS
```

Needs no credential — the catalogue is public, so explaining `UNAUTHORIZED` does
not fail with the error it is explaining.

Most codes carry only a category so far. Where no explanation has been written,
it says so rather than inventing one.

## Error bodies [#error-bodies]

Every error response carries:

| Field       |                                                                |
| ----------- | -------------------------------------------------------------- |
| `code`      | Stable identifier, e.g. `INSUFFICIENT_CREDITS`                 |
| `retryable` | Whether retrying could possibly help. &#x2A;*Branch on this.** |
| `docs_url`  | Where the code is documented                                   |
| `hint`      | What to do about it, where one has been written                |

## Before debugging a failing call [#before-debugging-a-failing-call]

```bash
speko-cli doctor
```

Reports credit, provider reachability, the scopes this session holds, and the
last failed session. It exits non-zero only when something found will actually
stop a call from working, so it is usable as a precondition in a script.

It states facts rather than verdicts: it names the provider that needs a key
instead of reporting that routing failed, and points at the last failed session
without guessing its cause.


# Evals (/cli/evals)

Prove a prompt change did not break the agent, and fail CI when it did.



A voice regression is invisible to every tool a coding agent has. Change one line
of a system prompt and the agent quietly stops confirming before it books — no
diff, type check or unit test registers it. The user finds out from a real
customer.

```bash
speko-cli eval generate --agent <id>            # propose a suite; prints it, saves nothing
speko-cli eval generate --agent <id> --persist  # keep it
speko-cli eval list --agent <id>                # what is stored
speko-cli eval run --agent <id>                 # run it, report what broke
speko-cli eval trends --agent <id>              # pass rate over time
```

## Generation writes the suite for you [#generation-writes-the-suite-for-you]

`eval generate` builds cases from the agent's own system prompt, tools and
knowledge-base titles, so nobody hand-authors test cases.

**Preview is the default.** Generation calls a model, so the same agent yields a
different suite each run; writing on the first run would leave someone who only
wanted to look with rows to clean up. Add `--persist` to keep them.

## Exit 6 means the agent is wrong [#exit-6-means-the-agent-is-wrong]

```bash
speko-cli eval run --agent <id>
echo $?   # 6 on a failing case
```

Not 1. A CI step has to tell "the agent's behaviour is wrong" from "the network
was down" — collapse them and the first failure that was really a flake teaches
everyone to ignore the gate.

```bash
speko-cli eval run --agent "$AGENT" || {
  status=$?
  [ "$status" -eq 6 ] && { echo "behaviour regressed"; exit 1; }
  echo "eval could not run (exit $status)"; exit 0
}
```

## A queued run is not a failed run [#a-queued-run-is-not-a-failed-run]

Runs are queued for a worker that places the simulated call and scores it. A run
that never leaves `queued` means nothing is consuming the queue — reported as
exactly that, separately from a slow run that did reach `running`.

The two need opposite responses: one is missing infrastructure, the other is a
prompt to fix. Calling an unclaimed run a test failure would send someone to edit
a prompt that was never tested.

## Reading a failure [#reading-a-failure]

`eval run` prints the broken case, what the worker said about it, and the command
to re-run that one case alone — with the real ids, so it can be copied.


# @spekoai/cli (/cli/overview)

Build and operate voice agents from the terminal, including from a coding agent.



`speko-cli` covers the Speko API from a shell: sign in, create agents, place calls,
read transcripts, and prove a prompt change did not break anything. It exists so a
coding agent can build on Speko without a person clicking through the console.

## Install [#install]

```bash
npm install -g @spekoai/cli
speko-cli login
```

Or without installing:

```bash
npx @spekoai/cli login
```

The command is `speko-cli`, not `speko` — `@spekoai/mcp-calls` already uses that name.

## Teach a coding agent about it [#teach-a-coding-agent-about-it]

```bash
speko-cli init
```

Writes `.claude/skills/speko/SKILL.md`, a marked block in `AGENTS.md`, and
`.env.example`. It never writes a credential into the project, and never
overwrites an existing file without `--force`.

Every command also takes `--help`, and asking never performs the action — so an
agent can explore the surface without side effects.

## Commands [#commands]

| Command                       | What it does                                                   |
| ----------------------------- | -------------------------------------------------------------- |
| `login` / `logout` / `whoami` | Sign this device in, out, and check who it is                  |
| `auth list` / `auth revoke`   | See and revoke every signed-in terminal                        |
| `init`                        | Write Speko guidance for coding agents into the repo           |
| `call --to <e164>`            | Place a call, wait for it, print the transcript                |
| `logs <session_id>`           | Call events, `--follow` to stream                              |
| `doctor`                      | Why calls are failing: credit, providers, scopes, last failure |
| `explain <CODE>`              | What an error code means, and whether retrying helps           |
| `bench [stage]`               | Measured provider scores — the numbers routing decides on      |
| `eval`                        | Generate a test suite for an agent, run it, report regressions |
| `mcp`                         | Point an MCP client at Speko                                   |

Plus every operation in the [OpenAPI document](https://docs.speko.ai/api),
generated rather than hand-written:

```bash
speko-cli agents                    # list a group's operations
speko-cli agents list               # every agent in the workspace
speko-cli agents get <agent_id>
speko-cli agents create --data '{"name":"Front desk"}'
```

Groups come from the spec's tags: `agents`, `call-control`, `providers`, `sms`,
`telephony`, `voice`, `webhooks`. The canonical name is the operationId,
kebab-cased (`listAgents` → `list-agents`); `list`, `get`, `create`, `update`
and `delete` are aliases where a group makes them unambiguous.

Path parameters are positional in URL order, query parameters are `--flags`, and
a request body comes from `--data JSON`, `--file PATH`, or stdin. Add `--json` to
any command for machine-readable output.

## The development loop [#the-development-loop]

```bash
speko-cli call --to +15551234567 --agent <agent_id>   # place it, wait, print the transcript
speko-cli logs <session_id> --follow                  # events as they arrive
speko-cli eval run --agent <agent_id>                 # prove the change is safe
```

`call` prints the session id before it starts waiting, so the id survives a
timeout or a Ctrl-C. `--no-wait` returns immediately. A call that ends `failed`
exits 1, so a script placing calls in a loop can notice.

The transcript is the only way to verify a prompt change altered behaviour — a
diff cannot show that an agent stopped confirming before it booked.

## What the CLI will not do [#what-the-cli-will-not-do]

Some acts belong to a person, so the CLI prints the console URL instead of doing
them:

| Operation                           | Why                                             |
| ----------------------------------- | ----------------------------------------------- |
| `telephony submit-phone-number-kyb` | Asserts you are authorized to bind the business |
| `telephony create-phone-number`     | Spends money and starts a recurring charge      |
| `telephony delete-phone-number`     | Returns the number to the carrier permanently   |

There is **no command for API keys at all**. A key is a long-lived organization
credential destined for production, so it is issued in the console by a person.

`agents delete-agent` and `sms redact-sms-conversation` are destructive and
deliberately stay: the first is how anyone iterating discards a test agent, and
the second is plausibly how a data-deletion request gets serviced, which wants to
be scriptable rather than clicked.

## Environment [#environment]

| Variable              | Default                     |
| --------------------- | --------------------------- |
| `SPEKO_API_URL`       | `https://api.speko.dev`     |
| `SPEKO_DASHBOARD_URL` | `https://platform.speko.ai` |
| `XDG_CONFIG_HOME`     | `~/.config`                 |

Source: [github.com/SpekoAI/cli](https://github.com/SpekoAI/cli)


# Callbacks & events (/client/callbacks)

Every hook VoiceConversation exposes, and when they fire.



All callbacks are optional. Pass them inside the `ConversationOptions` object. They're invoked synchronously on the media transport event loop — keep them fast or defer work with `queueMicrotask`.

## `ConversationStatus` [#conversationstatus]

```ts
type ConversationStatus = 'connecting' | 'connected' | 'disconnecting' | 'disconnected';
```

Transitions:

* **`connecting`** — the initial state, set the moment the `WebRTCConnection` is constructed.
* **`connected`** — after `room.connect()`, `createLocalAudioTrack()`, and `publishTrack()` all succeed.
* **`disconnecting`** — `endSession()` has been called but the room hasn't acknowledged yet.
* **`disconnected`** — the transport has fired `Disconnected`, OR an error during `connect()` (connection, mic) short-circuited to this state.

`onStatusChange` fires only on actual transitions; duplicate transitions are deduped.

## `ConversationMode` [#conversationmode]

```ts
type ConversationMode = 'listening' | 'speaking';
```

Mirrors transport active-speaker events: `speaking` when any remote participant is in the active-speakers set, `listening` otherwise. Useful for UI states like "agent talking now — show the voice animation".

Deduped on transition — `onModeChange` won't fire twice for the same mode.

## `ConversationMessage` [#conversationmessage]

```ts
interface ConversationMessage {
  source: 'agent' | 'user';
  text: string;
  isFinal: boolean;
  segmentId?: string;
}
```

`onMessage` fires from two sources — live transcriptions (the common case when talking to a Speko agent) and custom data-channel packets:

| Inbound event              | Becomes                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| Transcription segment      | `{ source, text, isFinal, segmentId }` — `source` is `user` for the local participant, `agent` otherwise |
| `transcript` packet        | `{ source: packet.source, text, isFinal: packet.isFinal ?? true }`                                       |
| `agent_message` packet     | `{ source: 'agent', text, isFinal: packet.isFinal ?? true }`                                             |
| `user_message_echo` packet | `{ source: 'user', text, isFinal: true }`                                                                |

Transcription updates are **cumulative per segment**: the same `segmentId` is re-delivered with growing `text` (the agent's transcript streams word-by-word; the user's utterance is re-published in full on every recognizer update, and the final text can arrive more than once). Render by &#x2A;*upserting on `(source, segmentId)`** — replace that message's text in place, and only append when you see a new `segmentId`. Appending every message duplicates text, and keying only by `source` corrupts the transcript whenever user and agent updates interleave (which is normal). Messages from custom data packets carry no `segmentId`; append those.

See [Data channel protocol](/client/data-channel) for the raw wire format.

## `DisconnectionDetails` [#disconnectiondetails]

```ts
interface DisconnectionDetails {
  reason: DisconnectionReason;
  message?: string;
}

type DisconnectionReason = 'user' | 'agent' | 'error' | 'timeout' | 'unknown';
```

The SDK maps transport disconnect reasons into a smaller, intent-oriented set:

| Transport disconnect reason                      | Mapped `reason` |
| ------------------------------------------------ | --------------- |
| Client initiated                                 | `user`          |
| Participant removed / room deleted / room closed | `agent`         |
| Join failure                                     | `error`         |
| everything else (including `undefined`)          | `unknown`       |

`message` is the raw transport enum name when available (useful for debugging / logging).

## `onConnect` [#onconnect]

```ts
onConnect?: (details: { conversationId: string }) => void;
```

Fires exactly once, after the mic is publishing and status is `connected`. `conversationId` is the transport conversation id (same value as `conversation.getId()`).

## `onError` [#onerror]

```ts
onError?: (error: Error) => void;
```

Non-fatal errors:

* Media device errors from the transport.
* Output device selection failures (`setSinkId` rejections).

Malformed or unrecognised inbound data packets are silently ignored — rooms carry data from other publishers (server control topics, future participants), so a packet that isn't part of the SDK protocol is not an error.

Fatal errors during `create()` are **thrown**, not routed to `onError`. See [Errors](/client/errors).


# Data channel protocol (/client/data-channel)

Wire format for packets exchanged between browser and agent over the media data channel.



Transcripts, agent messages, and the browser's outbound packets travel as JSON-encoded bytes on the reliable media data channel. `@spekoai/client` handles encoding and decoding internally; this page documents the wire format so server / agent implementations can interoperate.

## Encoding [#encoding]

* UTF-8 JSON, one message per `publishData` call.
* Reliable ordering (`reliable: true`).
* No framing beyond JSON — each `DataReceived` event is one complete packet.

## Outbound (browser → agent) [#outbound-browser--agent]

<Warning>
  **No agent consumes the three packets below.** The SDK publishes them with no data-channel topic; the agent worker's one data handler accepts the `speko.control` topic alone and discards the rest. This is a wire format, not a working feature.

  Working alternatives: `sendChatMessage(text)` for typed turns (native `sendText` on `lk.chat`, not this protocol), and [per-session variables](/client/overview#per-session-variables-dynamic-variables) for prompt and routing values.
</Warning>

### `overrides` [#overrides]

Sent once, immediately after the mic publishes, if the browser passed an `overrides` option.

```json
{
  "type": "overrides",
  "overrides": {
    "agent": {
      "prompt": "You are a helpful receptionist.",
      "firstMessage": "Hi, how can I help?",
      "language": "en-US"
    },
    "tts": {
      "voiceId": "sonic-english",
      "speed": 1.0
    }
  }
}
```

Any subfield is optional. Nothing applies them — see the warning above.

### `user_message` [#user_message]

Sent by `conversation.sendUserMessage(text)`. For typed user input that the agent actually answers, call `sendChatMessage(text)` instead — it uses `lk.chat`, not this protocol.

```json
{ "type": "user_message", "text": "I'd like to reschedule." }
```

### `contextual_update` [#contextual_update]

Sent by `conversation.sendContextualUpdate(text)`. Out-of-band context that shouldn't be treated as a turn. Set context known before the call as a [per-session variable](/client/overview#per-session-variables-dynamic-variables) instead.

```json
{ "type": "contextual_update", "text": "user switched to the checkout page" }
```

## Inbound (agent → browser) [#inbound-agent--browser]

### `transcript` [#transcript]

STT output for either speaker.

```json
{
  "type": "transcript",
  "source": "user",
  "text": "Hello there.",
  "isFinal": true
}
```

`isFinal` defaults to `true` when omitted.

### `agent_message` [#agent_message]

An assistant message emitted by the agent — typically streamed token-by-token as `isFinal: false` and closed with `isFinal: true`.

```json
{ "type": "agent_message", "text": "Happy to help!", "isFinal": true }
```

### `user_message_echo` [#user_message_echo]

Echo of a typed `user_message` so the UI can render it in the same transcript stream. `isFinal` is always implicitly `true`.

```json
{ "type": "user_message_echo", "text": "I'd like to reschedule." }
```

## Forwarding to `onMessage` [#forwarding-to-onmessage]

The SDK converts each inbound packet into a [`ConversationMessage`](/client/callbacks#conversationmessage):

```ts
// pseudocode
switch (packet.type) {
  case 'transcript':
    return { source: packet.source, text: packet.text, isFinal: packet.isFinal ?? true };
  case 'agent_message':
    return { source: 'agent', text: packet.text, isFinal: packet.isFinal ?? true };
  case 'user_message_echo':
    return { source: 'user', text: packet.text, isFinal: true };
}
```

Unknown packet types are ignored (no message fired, no error). Malformed JSON is ignored the same way — rooms carry data published for other consumers (server control topics, future participants), so a packet that isn't part of this protocol is not an error.

## Extending the protocol [#extending-the-protocol]

If you need a new packet type, add it on both sides:

1. Agent worker publishes a new `type` value.
2. Extend `InboundPacket` in `@spekoai/client` and handle it in `packetToMessage` (or ship a wrapper that subscribes to `room.on('dataReceived')` directly).

Outbound is not symmetric with inbound. `WebRTCConnection.publish(packet)` accepts any `OutboundPacket`, so widening the type in a fork compiles — and still delivers nothing, because the packet carries no topic for a worker to match on. A new outbound type needs a topic chosen, `publish()` changed to send it, and a handler on the agent that subscribes to that topic.


# Embed element (/client/embed-element)

The <speko-voice> custom element — a voice widget for any page.



`@spekoai/embed` ships one custom element, `<speko-voice>`. It renders a docked launcher, a transcript panel and mute, connects through [`VoiceConversation`](/client/voice-conversation), and takes no framework. Point it at a URL on your own backend that mints the session:

```html
<script type="module">
  import '@spekoai/embed';
</script>

<speko-voice token-endpoint="/api/speko-session" dock="bottom-right"></speko-voice>
```

<Warning>
  There is no CDN build yet, so the import above needs a bundler. A `<script src="…">` tag that
  registers the element from a URL is not published.
</Warning>

Importing the package registers the element. The package is marked `sideEffects: true` so a bundler cannot tree-shake that registration away.

```bash
npm install @spekoai/embed
```

## Attributes [#attributes]

Everything else on the element is either [refused](#attributes-it-refuses) or ignored.

| Attribute         | Value                                                        | Meaning                                                                                            |
| ----------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `token-endpoint`  | URL                                                          | Your endpoint that mints the session. The normal way to supply credentials.                        |
| `transport-token` | string                                                       | A token you already minted. Read once, then removed from the DOM.                                  |
| `transport-url`   | `wss://…`                                                    | The transport URL that came with that token.                                                       |
| `label`           | string                                                       | Accessible name for the launcher and panel. Defaults to `Speko voice assistant`.                   |
| `dock`            | `bottom-right` \| `bottom-left` \| `top-right` \| `top-left` | Pins the widget to a viewport corner. Omit it and the element lays out inline where you placed it. |
| `open`            | boolean                                                      | Present means the panel is expanded. Reflected, so it tracks the visitor's clicks.                 |

## The token endpoint [#the-token-endpoint]

The element sends `POST` to `token-endpoint` with `accept: application/json` and **no request body**. The endpoint runs on your origin and already knows who the visitor is from its own session. The page has nothing to contribute, and deliberately no channel through which it could.

Answer with a JSON object:

| Field            | Type   | Required | Meaning                                                                     |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `transportToken` | string | yes      | Pass through unchanged from `POST /v1/sessions`.                            |
| `transportUrl`   | string | yes      | Must be a WebSocket URL (`wss://`). Pass through unchanged.                 |
| `sessionId`      | string | no       | Surfaces on the element as `sessionId`, for correlating with your own logs. |

Validation is strict, and it catches two mistakes early: a backend that proxies the whole `POST /v1/sessions` response, and one that returns an HTML error page with a `200`.

```ts
// POST /api/speko-session — your server, your session cookie
export async function POST(request: Request) {
  const candidate = await currentUser(request); // your auth, not Speko's

  const session = await fetch('https://api.speko.dev/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 'cascade',
      agentId: process.env.SPEKO_AGENT_ID,
      variables: { candidate_first_name: candidate.firstName },
    }),
  }).then((r) => r.json());

  // Forward these three and nothing else.
  return Response.json({
    transportToken: session.transportToken,
    transportUrl: session.transportUrl,
    sessionId: session.sessionId,
  });
}
```

Everything that shapes the call is bound in that mint call, before a transport token exists — the agent, [per-session variables](/client/overview#per-session-variables-dynamic-variables), tool credentials and webhook tags.

## Attributes it refuses [#attributes-it-refuses]

The element presents a session; it never configures one. The attributes below are refused, not ignored: the element paints the reason into the panel, names the attribute, and will not dial. An ignored attribute teaches an embedder nothing — they ship, it looks fine, and the value quietly never reaches the agent.

The concrete case this was designed against is an interview widget on a job application page. If `variables` were an attribute, the candidate would be the one supplying their own name — and their own scoped tool token.

| Refused attribute                                                                     | Why                                                                         |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `variables`, `dynamic-variables`                                                      | Per-session variables are bound at mint, before the transport token exists. |
| `tool-secrets`                                                                        | Tool credentials go to tool execution only and must never enter the page.   |
| `webhook-tags`                                                                        | Webhook routing decides which of your endpoints hears about this session.   |
| `api-key`                                                                             | A Speko API key mints sessions for your whole organization.                 |
| `agent-id`                                                                            | Your backend picks the agent at mint time; the page cannot be trusted to.   |
| `override-prompt`, `override-first-message`, `override-language`, `override-voice-id` | Agent configuration, not page markup.                                       |

Each belongs in the `POST /v1/sessions` call your `token-endpoint` makes, where the visitor cannot reach it. The list covers the migration surface — the attributes someone moving off another vendor's widget would copy across, plus the Speko-shaped equivalents.

## States [#states]

The current state is readable as `element.state` and mirrored to a `data-state` attribute you can style against.

| State         | Meaning                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| `idle`        | No call. The launcher is ready.                                          |
| `authorizing` | Fetching credentials from `token-endpoint`.                              |
| `connecting`  | Joining the transport. The microphone prompt happens here.               |
| `connected`   | Live.                                                                    |
| `ending`      | Hanging up.                                                              |
| `error`       | The last attempt failed, or an attribute was refused. `start()` retries. |

## Events [#events]

All four bubble and cross shadow boundaries, so you can listen on `document`.

| Event                | `detail`                                                                                                          |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `speko-connect`      | `{ conversationId, sessionId }` — `sessionId` is `null` when the endpoint omitted it.                             |
| `speko-disconnect`   | `{ reason }`                                                                                                      |
| `speko-error`        | `{ code, message }` — `code` is one of the [error codes](#errors); `message` is written to be shown to a visitor. |
| `speko-state-change` | `{ state, previous }`                                                                                             |

```js
const widget = document.querySelector('speko-voice');

widget.addEventListener('speko-connect', (event) => {
  analytics.track('voice_call_started', { sessionId: event.detail.sessionId });
});

widget.addEventListener('speko-error', (event) => {
  console.error(event.detail.code, event.detail.message);
});
```

## JavaScript API [#javascript-api]

| Member            | Type            | Notes                                                                                                                                           |
| ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`           | getter          | Current [state](#states).                                                                                                                       |
| `sessionId`       | getter          | From the token endpoint, once connected.                                                                                                        |
| `muted`           | getter          | Microphone state.                                                                                                                               |
| `open`            | getter/setter   | Expands or collapses the panel. Reflects the `open` attribute.                                                                                  |
| `tokenEndpoint`   | getter/setter   | Reflects the `token-endpoint` attribute.                                                                                                        |
| `transportToken`  | setter          | **Write-only.** A token set here never touches the DOM, which makes it the better path for scripted embedders. Reading it back returns nothing. |
| `transportUrl`    | getter/setter   | The URL paired with that token.                                                                                                                 |
| `start()`         | `Promise<void>` | Begins a call. A no-op unless the state is `idle` or `error`.                                                                                   |
| `stop()`          | `Promise<void>` | Ends the call, or cancels one still connecting.                                                                                                 |
| `setMuted(muted)` | `Promise<void>` | Mutes or unmutes. Optimistic, and rolls back if the transport refuses.                                                                          |

`start()`, `stop()` and `setMuted()` report their own failures through `speko-error`, so a rejected promise is not the channel to watch.

```js
await document.querySelector('speko-voice').start();
```

## Theming [#theming]

The element renders into a shadow root, so page CSS cannot reach inside it. Theming is by custom property, set on the element or on any ancestor. Defaults live on `:host` at single-class specificity, which means one declaration of your own wins.

Colours have a dark-scheme default under `prefers-color-scheme: dark`, so overriding one value in light mode only will show through in dark mode.

| Property                    | Default                    | Controls                            |
| --------------------------- | -------------------------- | ----------------------------------- |
| `--speko-accent`            | `#1f6feb`                  | Launcher, user bubbles, focus rings |
| `--speko-accent-text`       | `#ffffff`                  | Text on the accent colour           |
| `--speko-surface`           | `#ffffff`                  | Panel background                    |
| `--speko-surface-muted`     | `#f4f6f8`                  | Panel header and footer             |
| `--speko-text`              | `#14171c`                  | Body text                           |
| `--speko-text-muted`        | `#5c636e`                  | Status line, timestamps             |
| `--speko-border`            | `#e4e7ec`                  | Panel and control borders           |
| `--speko-live`              | `#178a5a`                  | The connected indicator             |
| `--speko-danger`            | `#c0362c`                  | Errors and the hang-up control      |
| `--speko-agent-bubble`      | `#f1f3f6`                  | Agent transcript bubble             |
| `--speko-agent-bubble-text` | `var(--speko-text)`        | Agent bubble text                   |
| `--speko-user-bubble`       | `var(--speko-accent)`      | Visitor transcript bubble           |
| `--speko-user-bubble-text`  | `var(--speko-accent-text)` | Visitor bubble text                 |
| `--speko-font`              | system stack               | Font family                         |
| `--speko-font-size`         | `14px`                     | Base size                           |
| `--speko-radius`            | `18px`                     | Corner radius                       |
| `--speko-shadow`            | layered                    | Panel and launcher shadow           |
| `--speko-launcher-size`     | `56px`                     | Launcher diameter                   |
| `--speko-panel-width`       | `360px`                    | Panel width when docked             |
| `--speko-transcript-height` | `250px`                    | Scrolling transcript height         |

Motion is four durations and three easings: `--speko-dur-instant` (`100ms`), `--speko-dur-fast` (`150ms`), `--speko-dur-base` (`200ms`), `--speko-dur-slow` (`300ms`), `--speko-ease-standard`, `--speko-ease-out`, `--speko-ease-in`. Under `prefers-reduced-motion: reduce` the durations drop to `1ms` and the widget stops moving without changing shape.

```css
speko-voice {
  --speko-accent: #0f766e;
  --speko-radius: 8px;
  --speko-panel-width: 400px;
}
```

Icons are inline SVG and there are no webfonts or remote assets, so the widget renders under a strict `Content-Security-Policy` without changes on your side.

## Errors [#errors]

Every code below arrives as `event.detail.code` on `speko-error`. The element never rejects a promise at you — the same codes are exported as the `EmbedErrorCode` type if you want to switch on them in TypeScript.

| Code                     | Cause                                                                                     | What to do                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `TOKEN_ENDPOINT_FAILED`  | The endpoint was unreachable, non-`2xx`, or returned non-JSON.                            | Check the endpoint's own logs. The element reports status only, never the failed body. |
| `TOKEN_ENDPOINT_INVALID` | The response was missing `transportToken` or `transportUrl`, or the URL was not `wss://`. | Return the two fields at the top level, unchanged from `POST /v1/sessions`.            |
| `NOT_CONFIGURED`         | Neither `token-endpoint` nor a token pair was set.                                        | Set `token-endpoint`.                                                                  |
| `MICROPHONE_DENIED`      | The visitor denied the microphone, or the device has none.                                | The minted token is unspent — `start()` again after they grant it.                     |
| `CONNECTION_FAILED`      | The transport refused or dropped the connection.                                          | Retry. Check the session in the dashboard if it repeats.                               |
| `REFUSED_ATTRIBUTE`      | A [refused attribute](#attributes-it-refuses) is on the element.                          | Move the value into your `POST /v1/sessions` call and remove the attribute.            |

## Next [#next]

<CardGroup cols="2">
  <Card title="VoiceConversation" href="/client/voice-conversation">
    The SDK class underneath the element, for a UI you build yourself.
  </Card>

  <Card title="Per-session variables" href="/client/overview#per-session-variables-dynamic-variables">
    What your token endpoint binds at mint time.
  </Card>
</CardGroup>


# Errors (/client/errors)

SpekoClientError and its error codes.



The client SDK throws a single error class, `SpekoClientError`, tagged with a stable string code.

```ts
import { SpekoClientError } from '@spekoai/client';
import type { SpekoClientErrorCode } from '@spekoai/client';
```

## Shape [#shape]

```ts
class SpekoClientError extends Error {
  code: SpekoClientErrorCode;
  cause?: unknown;   // original error when wrapping transport failures
}
```

## Codes [#codes]

| Code                | Where it's thrown                                                                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTION_FAILED` | `VoiceConversation.create()` — transport connection rejected. `cause` is the original transport error.                                                           |
| `MICROPHONE_FAILED` | `create()` — mic acquisition or `publishTrack()` failed. The room is disconnected before this is thrown.                                                         |
| `NOT_CONNECTED`     | `sendUserMessage` / `sendContextualUpdate` / internal `publish()` called while status isn't `connected`.                                                         |
| `INVALID_MESSAGE`   | No longer raised. Malformed inbound data packets are silently ignored (rooms carry non-protocol data from other publishers). Kept in the type for compatibility. |
| `DISCONNECTED`      | Reserved for future use.                                                                                                                                         |

## Fatal vs non-fatal [#fatal-vs-non-fatal]

* **Fatal errors** (connection and microphone failures during `create()`) are **thrown** from the `create()` promise so callers can branch at construction time.
* **Non-fatal errors** (media device errors from the transport) are &#x2A;*routed to `onError`**. The session continues.
* **Non-protocol data packets** (malformed JSON, unknown shapes from other publishers in the room) are **silently ignored** — they never reach `onError`.

## Example [#example]

```ts
try {
  const conv = await VoiceConversation.create({ ... });
} catch (err) {
  if (err instanceof SpekoClientError) {
    switch (err.code) {
      case 'CONNECTION_FAILED':
        // Token expired, network issue, or transport outage — ask user to retry.
        break;
      case 'MICROPHONE_FAILED':
        // Permission denied or device in use — surface a permissions prompt.
        break;
    }
  }
  throw err;
}
```


# @spekoai/client (/client/overview)

Browser SDK for real-time voice conversations.



`@spekoai/client` is the browser-side companion to `@spekoai/sdk`. It connects a browser tab to a Speko voice session: capture the user's microphone, play the agent's audio, and exchange structured events such as transcripts and status changes.

Your server must mint a short-lived session token and return only browser-safe credentials. Never expose a Speko or provider root API key to browser code. For `VoiceConversation`, audio uses Speko's browser media transport. For `RealtimeVoiceConversation`, Speko reserves credit and mints a scoped provider credential, then audio flows directly between the browser and OpenAI, xAI, or Gemini Live.

## Install [#install]

```bash
npm install @spekoai/client
# or
pnpm add @spekoai/client
```

The package does not expose low-level media transport types on its public surface, so most apps only import from `@spekoai/client` directly.

## Choose a browser path [#choose-a-browser-path]

Use [`RealtimeVoiceConversation`](/client/realtime-voice-conversation) for provider-direct S2S. Your backend creates a session with `mode: 's2s'`; the browser connects straight to the provider with the returned short-lived credential:

```ts
const session = await fetch('/api/realtime-session', { method: 'POST' }).then((r) =>
  r.json(),
);

const conversation = await RealtimeVoiceConversation.create({
  ...session,
  onMessage: ({ source, text, isFinal }) => console.log(source, text, isFinal),
});
```

See [Provider-direct speech-to-speech](/guides/realtime-conversation) for the backend and browser flow.

Use [`VoiceConversation`](/client/voice-conversation) when your backend creates `mode: 'cascade'` and returns LiveKit transport credentials:

```ts
import { VoiceConversation } from '@spekoai/client';

const conversation = await VoiceConversation.create({
  transportToken,   // from server
  transportUrl,     // from server

  onConnect: ({ conversationId }) => console.log('connected', conversationId),
  onDisconnect: ({ reason }) => console.log('disconnected', reason),
  onMessage: ({ source, text, isFinal }) =>
    console.log(source, text, isFinal),
  onStatusChange: (status) => console.log('status', status),
  onModeChange: (mode) => console.log('mode', mode),
  onError: (err) => console.error(err),
});

await conversation.setMicMuted(true);
conversation.setVolume(0.8);
conversation.sendUserMessage('hello');
conversation.sendContextualUpdate('user switched to the checkout page');

await conversation.endSession();
```

See [Build a voice agent](/guides/voice-agent) for the cascade worker side.

## Per-session variables (dynamic variables) [#per-session-variables-dynamic-variables]

One agent, different values per session: a driver's name, a tenant id, a booking reference, a scoped access token. Your backend sets them when it mints the session. `POST /v1/sessions` accepts these per-session fields alongside `agentId`:

| Field            | Effect                                                                                                                                                                                       | Limits                                                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variables`      | Binds `{{name}}` placeholders in the agent's system prompt and first message. Compiled as Liquid at mint, so `{% if %}` branching and `\| default:` filters resolve before the agent speaks. | Strings, 1 KB each. An unbound name fails the call with `400 MISSING_TEMPLATE_VARIABLES` listing the names. Keys under `system.` are reserved and rejected. |
| `toolSecrets`    | Per-session credentials released only to tool execution. Never reach the prompt, the LLM context, the transcript, the dispatch metadata, or any response body; stored encrypted.             | Up to 32 entries, 4 KB each, 16 KB total.                                                                                                                   |
| `webhookTags`    | Routes this session's lifecycle events among the endpoints registered with `POST /v1/webhooks`, matched against their `filterTags`.                                                          | Up to 20. Requires `agentId`; without one the call fails `400 WEBHOOK_TAGS_REQUIRE_AGENT`.                                                                  |
| `preCallWebhook` | Fires `call.pre_call` before the worker starts, so your handler can return overrides for this session. Off unless you send `true`.                                                           | Requires `agentId`. A refused or slow handler fails session creation — see [Pre-call webhook](/docs/guides/webhooks#pre-call-webhook).                      |

Your backend mints the session and forwards only the two transport fields:

```ts
// Server-side. SPEKO_API_KEY never leaves this process.
const session = await fetch('https://api.speko.dev/v1/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mode: 'cascade',
    agentId: 'agent_123',
    variables: {
      driver_name: driver.firstName,
      driver_id: driver.id,
      fleet_tier: driver.tier,
    },
    toolSecrets: {
      fleet_api_token: await mintFleetToken(driver.id),
    },
    webhookTags: { tenant: driver.tenantId },
  }),
}).then((r) => r.json());

// Forward these two and nothing else.
return { transportToken: session.transportToken, transportUrl: session.transportUrl };
```

The page connects knowing none of it:

```ts
const { transportToken, transportUrl } = await fetch('/api/voice-session', {
  method: 'POST',
}).then((r) => r.json());

const conversation = await VoiceConversation.create({ transportToken, transportUrl });
```

**The page cannot forge these values.** They are bound server-side before the transport token exists, and the browser never receives the fields — so tampered page code can only reconnect with values already fixed. When the variable is a `driver_id` or a tenant id, that is the difference between something the agent may act on and a string the client asserted.

Per-session values are set at mint and hold for the session's lifetime; the browser has no path to change them mid-call.

## What the SDK owns [#what-the-sdk-owns]

* Connecting with supplied short-lived provider-direct or LiveKit credentials.
* Acquiring the microphone with sensible constraints (echo cancellation, noise suppression, auto gain — all togglable via `audioConstraints`).
* Playing remote audio.
* Normalizing provider or LiveKit transcript and status events into the same callbacks.
* Sending typed user turns via `sendChatMessage`.
* Mic mute, speaker volume, output device selection.
* Tearing everything down on disconnect, including releasing the OS microphone capture.

## What it doesn't do [#what-it-doesnt-do]

* **Mint sessions from API keys.** Keep `SPEKO_API_KEY` on your server. Browser code should only receive short-lived session tokens. Per-session prompt values, tool credentials, and webhook routing are set on that server-side mint — see [per-session variables](#per-session-variables-dynamic-variables).
* **Configure the agent from the browser.** [`ConversationOverrides`](/client/voice-conversation#conversationoverrides), `sendUserMessage`, and `sendContextualUpdate` publish data packets that no agent reads. Session config is a server-side concern.
* **Retries.** A failed `connect()` throws a [`SpekoClientError`](/client/errors). Retry logic belongs in your app's UX.
* **Tool calls, guardrail hooks, MCP, VAD score streaming.** Deferred — see the package's `ROADMAP.md`.

## Reference [#reference]

* [VoiceConversation](/client/voice-conversation) — the primary API surface.
* [RealtimeVoiceConversation](/client/realtime-voice-conversation) — provider-direct S2S over OpenAI WebRTC or xAI/Gemini Live WebSockets.
* [Callbacks & events](/client/callbacks) — every hook the SDK exposes.
* [Data channel protocol](/client/data-channel) — wire format for inbound / outbound packets.
* [Errors](/client/errors) — `SpekoClientError` and its codes.


# RealtimeVoiceConversation (/client/realtime-voice-conversation)

Browser capture and playback for provider-direct speech-to-speech sessions.



`RealtimeVoiceConversation` is the browser-side helper for Speko speech-to-speech (S2S) sessions. `POST /v1/sessions` reserves credit and returns a short-lived provider credential; the browser then connects directly to OpenAI, xAI, or Gemini Live. Realtime audio does not pass through a Speko media proxy.

Use it when you want the lowest-latency S2S path and do not need the browser media transport used by [`VoiceConversation`](/client/voice-conversation).

```ts
import { RealtimeVoiceConversation } from '@spekoai/client';
```

## Mint the session on your server [#mint-the-session-on-your-server]

Create S2S sessions on your backend so `SPEKO_API_KEY` never reaches the browser. Return the provider-direct response unchanged; it contains only a scoped, short-lived provider credential plus Speko telemetry and billing-control URLs.

```ts server.ts
app.post('/api/realtime-session', async (req, res) => {
  // Preserve this value if your server retries an ambiguous upstream timeout.
  const idempotencyKey = req.get('Idempotency-Key') || crypto.randomUUID();
  const response = await fetch('https://api.speko.dev/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      mode: 's2s',
      s2s: {
        provider: 'openai',
        model: 'gpt-realtime-2.1',
        voice: 'marin',
        systemPrompt: 'You are a concise voice assistant.',
      },
      ttlSeconds: 900,
    }),
  });

  if (!response.ok) {
    res.status(response.status).json({ error: 'Could not start realtime session' });
    return;
  }

  res.json(await response.json());
});
```

## Connect from the browser [#connect-from-the-browser]

```tsx RealtimePanel.tsx
import { useEffect, useRef, useState } from 'react';
import { RealtimeVoiceConversation } from '@spekoai/client';

export function RealtimePanel() {
  const convRef = useRef<RealtimeVoiceConversation | null>(null);
  const [status, setStatus] = useState('idle');
  const [transcript, setTranscript] = useState<string[]>([]);

  async function start() {
    setStatus('connecting');
    const session = await fetch('/api/realtime-session', {
      method: 'POST',
    }).then((r) => r.json());

    const conv = await RealtimeVoiceConversation.create({
      ...session,
      onConnect: ({ conversationId }) => {
        console.log('connected', conversationId);
      },
      onStatusChange: setStatus,
      onMessage: ({ source, text, isFinal }) => {
        if (isFinal) setTranscript((items) => [...items, `${source}: ${text}`]);
      },
      onError: (err) => console.error(err),
      onDisconnect: () => setStatus('idle'),
    });

    convRef.current = conv;
  }

  async function stop() {
    await convRef.current?.endSession();
    convRef.current = null;
  }

  useEffect(() => () => { void convRef.current?.endSession(); }, []);

  return (
    <div>
      <button onClick={start} disabled={status !== 'idle'}>Start</button>
      <button onClick={stop} disabled={status === 'idle'}>Stop</button>
      <p>Status: {status}</p>
      <ul>{transcript.map((item, i) => <li key={i}>{item}</li>)}</ul>
    </div>
  );
}
```

## `RealtimeVoiceConversation.create(options)` [#realtimevoiceconversationcreateoptions]

```ts
static create(options: RealtimeConversationOptions): Promise<RealtimeVoiceConversation>
```

`create()` validates the provider endpoint, connects directly to it, waits for provider readiness, starts microphone capture, then resolves. OpenAI uses WebRTC and a provider-authenticated billing sideband; xAI and Gemini Live use provider WebSockets. The client automatically renews authorized Gemini Live slices with session resumption when the session horizon is longer than one slice.

### `RealtimeConversationOptions` [#realtimeconversationoptions]

| Field               | Type                                | Required | Description                                                               |
| ------------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------- |
| `transport`         | `'provider_direct'`                 | yes      | Ensures no Speko media-proxy transport is accepted.                       |
| `sessionId`         | `string`                            | yes      | Server-assigned session id. Also returned by `getId()`.                   |
| `attemptId`         | `string`                            | yes      | Correlates the provider connection with billing evidence.                 |
| `provider`          | `'openai' \| 'xai' \| 'google'`     | yes      | Selected realtime provider.                                               |
| `providerTransport` | `'webrtc' \| 'websocket'`           | yes      | OpenAI plans use WebRTC; xAI and Gemini Live use WebSocket.               |
| `endpoint`          | `string`                            | yes      | Allowlisted provider endpoint.                                            |
| `credential`        | `object`                            | yes      | Scoped provider bearer credential and expiry.                             |
| `telemetry`         | `object`                            | yes      | Speko control endpoint and short-lived token; it never carries media.     |
| `reservation`       | `object`                            | yes      | Authorized duration, lease expiry, billing ceiling, and optional renewal. |
| `sidebandUrl`       | `string?`                           | OpenAI   | Binds the OpenAI call to the provider-authenticated metering sideband.    |
| `inputSampleRate`   | `16000 \| 24000?`                   |          | Gemini uses 16 kHz input; OpenAI and xAI use 24 kHz.                      |
| `outputSampleRate`  | `24000?`                            |          | Provider response PCM sample rate.                                        |
| `inputDeviceId`     | `string?`                           |          | Specific microphone `deviceId`.                                           |
| `audioConstraints`  | `AudioConstraints?`                 |          | `echoCancellation`, `noiseSuppression`, and `autoGainControl`.            |
| `onConnect`         | `(d: { conversationId }) => void`   |          | Fired after provider readiness and microphone capture.                    |
| `onDisconnect`      | `(d: DisconnectionDetails) => void` |          | Fired when the provider transport closes.                                 |
| `onMessage`         | `(m: ConversationMessage) => void`  |          | Provider transcripts mapped to `{ source, text, isFinal }`.               |
| `onStatusChange`    | `(s: ConversationStatus) => void`   |          | `connecting`, `connected`, `disconnecting`, or `disconnected`.            |
| `onModeChange`      | `(m: ConversationMode) => void`     |          | `speaking` while response audio is queued, otherwise `listening`.         |
| `onError`           | `(err: Error) => void`              |          | Provider, sideband, or entitlement-renewal errors.                        |

## Instance methods [#instance-methods]

### `getId(): string` [#getid-string]

Returns the `sessionId` passed to `create()`.

### `isOpen(): boolean` [#isopen-boolean]

`true` while the SDK status is `connected` and the provider WebSocket or OpenAI data channel is open.

### `setMicMuted(muted: boolean): Promise<void>` [#setmicmutedmuted-boolean-promisevoid]

Mute or unmute local microphone capture. Muting disables the media track and stops PCM frames from being sent.

### `setVolume(volume: number): void` [#setvolumevolume-number-void]

Set response playback volume from `0` to `1`. Values outside that range are clamped.

### `endSession(): Promise<void>` [#endsession-promisevoid]

Close the provider transport, stop microphone tracks, clear queued playback, close audio contexts, and transition to `disconnected`.

## Transport notes [#transport-notes]

* OpenAI audio travels over WebRTC. The Speko sideband receives provider events and can terminate the provider call, but it never receives audio.
* xAI and Gemini audio travels over provider WebSockets using only delegated credentials.
* Gemini Live renewals reserve the next credit slice before a new credential is minted, then resume the provider session on the rotated connection.
* Client telemetry is operational evidence only. Missing or altered telemetry cannot reduce the authorized entitlement settlement.
* `AudioWorklet` capture is used when available; the SDK falls back to `ScriptProcessorNode` for older browsers.


# VoiceConversation (/client/voice-conversation)

Primary API — construct, control, and tear down a voice session.



`VoiceConversation` is the public class exported from `@spekoai/client`. Always construct it via the static `create()` factory — the factory awaits connection, so by the time it resolves the session is live.

```ts
import { VoiceConversation } from '@spekoai/client';
```

There is also a legacy namespace export, `Conversation`, with a single method `Conversation.startSession(options)` — it's an alias for `VoiceConversation.create(options)`, kept so consumers migrating from other SDKs can use familiar naming.

## `VoiceConversation.create(options)` [#voiceconversationcreateoptions]

```ts
static create(options: CreateOptions): Promise<VoiceConversation>
```

Where `CreateOptions` is the short-lived token shape:

```ts
type CreateOptions = ConversationOptions;
```

Your backend calls `POST /v1/sessions` with `mode: 'cascade'`, optionally with an [`agentId`](/concepts/agents), and forwards only `transportToken` and `transportUrl` to the browser. `VoiceConversation.create()` connects to the LiveKit media transport, publishes the microphone track, sends any [`overrides`](#conversationoverrides) over the data channel, fires `onConnect`, and resolves. It throws a [`SpekoClientError`](/client/errors) on connection, network, or microphone failure.

That same `POST /v1/sessions` call is where per-session behaviour belongs. See [per-session variables](/client/overview#per-session-variables-dynamic-variables) for prompt values, tool credentials, and webhook routing scoped to one browser session.

<Warning>
  Do not send `SPEKO_API_KEY` to browser code. `VoiceConversation` no longer accepts `agentId`, `apiKey`, or `apiBaseUrl`; session minting belongs on your server.
</Warning>

### `ConversationOptions` [#conversationoptions]

| Field              | Type                                | Required | Description                                                                                                                                                                                               |
| ------------------ | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transportToken`   | `string`                            | ✅        | Browser-safe media transport token, returned by your server.                                                                                                                                              |
| `transportUrl`     | `string`                            | ✅        | Media transport URL, returned by your server. Pass it straight through — the SDK does not default this so consumers can't ship against the wrong environment.                                             |
| `overrides`        | `ConversationOverrides?`            |          | Accepted and published, but **no agent reads it** — see [`ConversationOverrides`](#conversationoverrides). Use [per-session variables](/client/overview#per-session-variables-dynamic-variables) instead. |
| `inputDeviceId`    | `string?`                           |          | Specific microphone `deviceId`.                                                                                                                                                                           |
| `outputDeviceId`   | `string?`                           |          | Specific speaker `deviceId`. Applied via `setSinkId`; silently ignored on browsers without support.                                                                                                       |
| `audioConstraints` | `AudioConstraints?`                 |          | `echoCancellation`, `noiseSuppression`, `autoGainControl`. All default `true`.                                                                                                                            |
| `onConnect`        | `(d: { conversationId }) => void`   |          | Fired after the mic publishes and status becomes `connected`.                                                                                                                                             |
| `onDisconnect`     | `(d: DisconnectionDetails) => void` |          | Fired on server or client disconnect.                                                                                                                                                                     |
| `onMessage`        | `(m: ConversationMessage) => void`  |          | Inbound transcripts, agent messages, user-message echoes.                                                                                                                                                 |
| `onStatusChange`   | `(s: ConversationStatus) => void`   |          | `connecting → connected → disconnecting → disconnected`.                                                                                                                                                  |
| `onModeChange`     | `(m: ConversationMode) => void`     |          | `listening` vs `speaking`, derived from transport active-speaker events.                                                                                                                                  |
| `onError`          | `(err: Error) => void`              |          | Non-fatal errors (malformed data packets, media device errors, sink-id failures).                                                                                                                         |

`conversationToken` and `livekitUrl` are still accepted as legacy aliases for existing callers.

### `ConversationOverrides` [#conversationoverrides]

```ts
interface ConversationOverrides {
  agent?: {
    prompt?: string;
    firstMessage?: string;
    language?: string;
  };
  tts?: {
    voiceId?: string;
    speed?: number;
  };
}
```

<Warning>
  **Overrides have no effect.** The SDK serializes them and publishes them over the data channel; no agent worker reads them. Passing `overrides` changes nothing about the agent's behaviour.

  The packet goes out with no data-channel topic, and the worker's one data handler accepts the `speko.control` topic alone, so it is discarded on arrival. On that topic the handler dispatches two message types, neither of them `overrides`.

  Set prompt, first message, and language with [per-session variables](/client/overview#per-session-variables-dynamic-variables) instead. Your server sets those when it mints the session, so page JavaScript cannot forge them.
</Warning>

The type and its [wire format](/client/data-channel#overrides) remain documented; the API is retained pending a decision on browser-side overrides.

### `AudioConstraints` [#audioconstraints]

```ts
interface AudioConstraints {
  echoCancellation?: boolean; // default true
  noiseSuppression?: boolean; // default true
  autoGainControl?: boolean; // default true
}
```

The SDK always routes through `createLocalAudioTrack({ ... })` rather than `setMicrophoneEnabled(true)` so that constraints are applied even when no `inputDeviceId` is passed — `setMicrophoneEnabled` silently ignores them in that case.

## Instance methods [#instance-methods]

### `getId(): string` [#getid-string]

Returns the transport conversation id. Populated after `create()` resolves.

### `isOpen(): boolean` [#isopen-boolean]

`true` while the underlying status is `connected`.

### `setMicMuted(muted: boolean): Promise<void>` [#setmicmutedmuted-boolean-promisevoid]

Mute / unmute the local microphone track. Uses the track-level mute API when a track is attached; falls back to `LocalParticipant.setMicrophoneEnabled()` otherwise.

### `setVolume(volume: number): void` [#setvolumevolume-number-void]

Set playback volume for every remote audio element (0–1, clamped). Applied immediately to existing elements and to future ones.

### `sendChatMessage(text: string): Promise<void>` [#sendchatmessagetext-string-promisevoid]

Send typed text to the agent as a user turn. **This is the outbound text path that works** — prefer it over `sendUserMessage`.

It is not a data packet. The SDK calls the transport's native `sendText` on the `lk.chat` topic, which LiveKit Agents' `RoomIO` consumes as a user turn, so the agent replies with audio and transcription as it would to speech.

Delivery depends on the framework's `text_enabled` default. Speko's worker does not set that flag in either direction, so this path rests on a LiveKit default rather than on a platform guarantee.

### `sendUserMessage(text: string): void` [#sendusermessagetext-string-void]

Publish a `user_message` packet over the reliable data channel.

**No agent reads this packet** — it is dropped on the same topic mismatch described under [`ConversationOverrides`](#conversationoverrides). Use `sendChatMessage` for typed user input.

### `sendContextualUpdate(text: string): void` [#sendcontextualupdatetext-string-void]

Publish a `contextual_update` packet, intended for out-of-band context such as "user switched to the checkout page".

**No agent reads this packet either**, for the same reason. To give the agent per-session context that does take effect, pass it as a [per-session variable](/client/overview#per-session-variables-dynamic-variables) when your server mints the session. Context that has to arrive mid-call has no working browser path today.

### `endSession(): Promise<void>` [#endsession-promisevoid]

Initiate clean disconnection. Sets status to `disconnecting`, asks the transport to disconnect; the disconnect event completes the teardown (stops the mic track, removes audio elements, fires `onDisconnect`). Idempotent — calling it twice is a no-op.

## Teardown invariants [#teardown-invariants]

When disconnection completes (whether triggered by `endSession()`, agent leaving, token expiry, or error), the SDK:

1. Sets status to `disconnected` and fires `onStatusChange`.
2. Stops the local microphone track so the browser's mic indicator goes away.
3. Detaches and removes every `<audio>` element it added to `document.body`.
4. Fires `onDisconnect` with a mapped [`DisconnectionReason`](/client/callbacks#disconnectionreason).

Your component's unmount effect should call `endSession()` so navigating away doesn't leak a live transport session.


# Architecture (/gateway/architecture)

The three hosted surfaces and one local runtime that make up Speko, and which one your traffic touches.



## The pieces [#the-pieces]

| Component                                                                        | Where it runs                                             | What it does                                                                                                                                                                                   |
| -------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Speko Router** (`router.speko.dev`)                                            | Speko's regional fleet, fronted by AWS Global Accelerator | Hosted HTTP/WebSocket API for STT, TTS, and LLM requests. Terminates your request, picks a provider, proxies media, meters usage.                                                              |
| **Speko control plane** (`gateway.speko.dev`)                                    | Speko's cloud                                             | Authenticates API keys, admits requests, signs short-lived execution plans, meters and settles billing. Publishes signing keys at `/.well-known/jwks.json` and `/.well-known/relay-jwks.json`. |
| **Speko Gateway**                                                                | **Your** container, next to your agent                    | Open-source sidecar exposing a local streaming API on a Unix socket. Dials providers directly. Optional: consults the control plane for routing and managed credentials.                       |
| **Dashboard** ([`platform.speko.ai/gateway`](https://platform.speko.ai/gateway)) | Speko's cloud                                             | Key management, activity, usage, BYOK configuration, and the live model catalog.                                                                                                               |

## Two traffic paths [#two-traffic-paths]

### Router path — media flows through Speko [#router-path--media-flows-through-speko]

```
Your app ──HTTPS/WSS──▶ router.speko.dev (nearest region) ──▶ provider
                              │
                              └── admission, metering ──▶ gateway.speko.dev
```

You call `router.speko.dev` with a Speko API key. A regional edge admits the request through the control plane (credit, concurrency, route health), a per-provider connector opens the provider connection with Speko's own provider credentials, and the result streams back to you. Every response tells you which provider, model, and region served it.

### Gateway path — media flows direct to the provider [#gateway-path--media-flows-direct-to-the-provider]

```
Your agent ──unix socket──▶ speko-gateway (same container) ──▶ provider
                                  │
                                  └── (managed requests) signed plans ──▶ gateway.speko.dev
```

The gateway serves its API only on a local Unix socket — it opens **no TCP port**. BYOK requests are planned locally and make no Speko planning call (apart from optional anonymous telemetry). Managed requests use a **signed session plan** from the control plane: the plan carries the route, a short-lived provider credential, and metering ceilings, signed with a key you can verify against the public JWKS. Both types can coexist in one process, and audio and text still travel directly between your process and the provider.

## Trust boundaries [#trust-boundaries]

* Router **edge** processes hold no provider secrets. Only per-provider **connector** processes hold provider keys, and they accept work only via cryptographically signed, single-use relay plans.
* The **control plane** is the single monetary authority: admission, budgets, and settlement live there.
* The **gateway** verifies every plan's signature, issuer, audience, expiry, and single-use token before attaching any credential or media.
* Signed session plans (gateway) and signed relay plans (relay fleet) use **separate signing keys** published at separate JWKS URLs, so neither artifact can ever authorize the other's consumer.

For what data crosses each boundary, see [Trust and signing](/gateway/trust).


# Configuration (/gateway/configuration)

Every environment variable the gateway reads.



The gateway is configured entirely through environment variables. Every secret-bearing variable also accepts an exclusive `_FILE` variant (`NAME_FILE=/path`) — setting both `NAME` and `NAME_FILE` is an error, secret files are capped at 64 KiB, and an empty file is an error.

## Core [#core]

| Variable                           | Default                   | Purpose                                      |
| ---------------------------------- | ------------------------- | -------------------------------------------- |
| `SPEKO_LOCAL_AUTH_TOKEN`           | **required**              | Bearer token for the local API               |
| `SPEKO_API_KEY`                    | unset                     | Enables [Speko-managed mode](/gateway/modes) |
| `SPEKO_SOCKET_PATH`                | `/run/speko/runtime.sock` | Absolute Unix socket path                    |
| `SPEKO_MAX_SESSIONS`               | `100`                     | Per-process session capacity                 |
| `SPEKO_LOCAL_MAX_SESSION_DURATION` | `24h`                     | Provider-direct session hard deadline        |
| `SPEKO_TELEMETRY_DISABLED`         | `false`                   | Opt out of optional telemetry                |
| `SPEKO_RUNTIME_INSTANCE_ID`        | hostname                  | Non-secret process identity                  |
| `SPEKO_WORKLOAD_TYPE`              | `agent` when an ID is set | Dashboard workload category                  |
| `SPEKO_WORKLOAD_ID`                | unset                     | Stable workload identity for the dashboard   |

## Control plane (managed mode) [#control-plane-managed-mode]

| Variable                            | Default                                 | Purpose                   |
| ----------------------------------- | --------------------------------------- | ------------------------- |
| `SPEKO_CONTROL_PLANE_URL`           | `https://gateway.speko.dev`             | Speko control plane       |
| `SPEKO_JWKS_URL`                    | `<control-plane>/.well-known/jwks.json` | Plan signing keys         |
| `SPEKO_PLAN_ISSUER`                 | control-plane URL                       | Required plan issuer      |
| `SPEKO_PLAN_AUDIENCE`               | `speko-runtime`                         | Required plan audience    |
| `SPEKO_INSTANCE_HEARTBEAT_INTERVAL` | `20s`                                   | Worker heartbeat interval |

## Warm plan pool (managed mode) [#warm-plan-pool-managed-mode]

| Variable                        | Default  | Purpose                                                                  |
| ------------------------------- | -------- | ------------------------------------------------------------------------ |
| `SPEKO_WARM_PLAN_TARGET`        | `4`      | Prefetched plans per route; `0` disables                                 |
| `SPEKO_WARM_ROUTES`             | unset    | Pre-declared routes: `kind:provider[:model[:language]]`, comma-separated |
| `SPEKO_WARM_TTS_MAX_CHARACTERS` | `100000` | Character allowance requested for warmed TTS routes                      |

## BYOK provider keys [#byok-provider-keys]

Set any of these to enable that provider for BYOK requests:

`SPEKO_ALIBABA_BYOK_API_KEY`, `SPEKO_ASSEMBLYAI_BYOK_API_KEY`, `SPEKO_CARTESIA_BYOK_API_KEY`, `SPEKO_DEEPGRAM_BYOK_API_KEY`, `SPEKO_ELEVENLABS_BYOK_API_KEY`, `SPEKO_FISH_BYOK_API_KEY`, `SPEKO_GLADIA_BYOK_API_KEY`, `SPEKO_GOOGLE_BYOK_ACCESS_TOKEN`, `SPEKO_GRADIUM_BYOK_API_KEY`, `SPEKO_HUME_BYOK_API_KEY`, `SPEKO_INWORLD_BYOK_API_KEY`, `SPEKO_MINIMAX_BYOK_API_KEY`, `SPEKO_MODULATE_BYOK_API_KEY`, `SPEKO_OPENAI_BYOK_API_KEY`, `SPEKO_RIME_BYOK_API_KEY`, `SPEKO_SMALLEST_BYOK_API_KEY`, `SPEKO_SONIOX_BYOK_API_KEY`, `SPEKO_XAI_BYOK_API_KEY`

Provider-specific configuration:

* **Google STT** additionally requires `SPEKO_GOOGLE_STT_ENDPOINT` set to a project-scoped recognizer URL; the catalog row stays visible but unroutable until it is configured.
* **TTS voice overrides** use `SPEKO_<PROVIDER>_BYOK_TTS_VOICE` when a deployment needs a provider-specific default.

## Container hardening [#container-hardening]

The published image is distroless and runs as UID/GID `65532`. The reference [docker-compose file](https://github.com/SpekoAI/gateway/blob/main/deploy/docker-compose.yml) runs it with `read_only: true`, `cap_drop: ALL`, `no-new-privileges`, a named volume on `/run/speko`, and a small `noexec` tmpfs on `/tmp`. Because the documented setup shares one container between agent and gateway, the agent process can read the container environment — use separate containers when you need process-level credential isolation.


# Control plane API (/gateway/control-plane)

The hosted API at gateway.speko.dev that the sidecar consumes in managed mode.



The gateway talks to Speko's control plane at &#x2A;*`https://gateway.speko.dev`** in managed mode. You normally never call these endpoints yourself — the sidecar does — but the contract is documented here for transparency and for anyone implementing the protocol independently.

## Conventions [#conventions]

* Auth is `Authorization: Bearer <SPEKO_API_KEY>`, except where noted.
* Every plan-related POST sends `Idempotency-Key` and `Speko-Protocol-Revision: 3` (exact match required; mismatches return `400 unsupported_protocol_revision`).
* Bodies are JSON, capped at 1 MiB, with unknown fields rejected.
* Every response carries an `X-Request-ID` header (`cp_...`) — quote it in support requests.
* The error envelope is minimal: `{"error":{"code":"..."}}`. Note this differs from the [Router envelope](/relay/errors).

## Endpoints [#endpoints]

| Method + path                                   | Auth                  | Purpose                                                                           |
| ----------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- |
| `GET /healthz`, `GET /readyz`                   | none                  | health                                                                            |
| `GET /.well-known/jwks.json`                    | none                  | session-plan signing keys                                                         |
| `GET /.well-known/relay-jwks.json`              | none                  | relay-plan signing keys (separate key set by design)                              |
| `POST /v1/session-plans`                        | API key               | mint one signed session plan                                                      |
| `POST /v1/session-plan-batches`                 | API key               | `{"count": N, "plan": {...}}` → up to 16 plans (warm-pool prefetch)               |
| `POST /v1/sessions/{session_id}/fallback-plans` | API key or plan token | exchange a failed attempt for a plan on a backup provider                         |
| `PUT /v1/runtime-instances/{instance_id}`       | API key               | instance heartbeat                                                                |
| `DELETE /v1/runtime-instances/{instance_id}`    | API key               | mark instance offline                                                             |
| `POST /v1/runtime-events`                       | plan telemetry token  | authenticated content-free telemetry                                              |
| `POST /v1/anonymous-runtime-events`             | **none allowed**      | BYOK anonymous telemetry; a request with an `Authorization` header is rejected    |
| `POST /v1/turn-events`                          | API key               | authenticated conversation-profiler markers                                       |
| `POST /v1/anonymous-turn-events`                | **none allowed**      | BYOK profiler markers without account linkage; authorization headers are rejected |

## Plan issuance errors [#plan-issuance-errors]

| Status | Code                                              |
| ------ | ------------------------------------------------- |
| 401    | `authentication_failed`                           |
| 402    | `credit_exhausted`                                |
| 403    | `launches_disabled`, `provider_not_entitled`      |
| 409    | `idempotency_conflict`, `idempotency_in_progress` |
| 422    | `no_eligible_route`                               |
| 429    | `quota_exhausted`                                 |
| 503    | `service_unavailable`                             |

<Note>
  The control plane and Router name credit exhaustion differently: `credit_exhausted` here, [`insufficient_credit`](/relay/errors) on Router. Both are HTTP 402.
</Note>

## What a signed session plan contains [#what-a-signed-session-plan-contains]

The plan is a JWS (`typ: speko.session-plan+jws`, algorithm `EdDSA` or `RS256`, audience `speko-runtime`) whose payload binds:

* `plan_id`, `session_id`, `attempt_id`, and an expiry (minutes)
* the **route**: provider, model, optional voice and region, adapter, transport, endpoint, and — on managed routes — a short-lived provider credential
* the **reservation**: metering unit, authorized units, a fixed provider-direct deadline, and concurrency reservation
* the **telemetry** destination and session-scoped token
* an optional **fallback** exchange URL
* `requirements`: protocol `speko.voice.v0`, revision exactly `3`

The gateway verifies signature, `kid` against the JWKS, issuer, audience, expiry, and single-use `jti` before opening the provider connection. Fallback exchanges are always forced to the configured control-plane origin, even if a plan says otherwise. Full trust details in [Trust and signing](/gateway/trust).

Provider-direct plan deadlines are fixed and enforced locally. There is no mid-call renewal endpoint. The hosted Router uses a separate renewable lease contract for its long-lived streams.


# Errors (/gateway/errors)

The local API's error envelope and code set.



## The envelope [#the-envelope]

Every local API error is:

```json
{ "error": { "code": "session_not_found", "message": "..." } }
```

<Note>
  This is the **local gateway** envelope. The hosted Router uses a richer envelope with `retryable` and `request_id` — see [Router errors](/relay/errors). The two code sets are also different.
</Note>

## HTTP error codes [#http-error-codes]

| Status        | Code                          | Where                                                                                        |
| ------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
| 401           | `local_auth_required`         | any authenticated route without a valid bearer (response carries `WWW-Authenticate: Bearer`) |
| 400           | `idempotency_key_required`    | `POST /v1/sessions` without the header                                                       |
| 400           | `invalid_request`             | body too large (64 KiB), unknown fields, invalid combinations                                |
| 400           | `unsupported_protocol`        | WebSocket upgrade without the `speko.voice.v0.r3` subprotocol                                |
| 404           | `session_not_found`           | stream attach or delete for an unknown session                                               |
| 409           | `idempotency_key_conflict`    | key reused with a different body                                                             |
| 409           | `duplicate_session`           | the control plane returned an already-active session ID                                      |
| 409           | `stream_already_attached`     | second WebSocket consumer                                                                    |
| 429           | `local_concurrency_exhausted` | at `SPEKO_MAX_SESSIONS`                                                                      |
| 500           | `request_fingerprint_failed`  | internal idempotency hashing failure                                                         |
| 502           | `session_open_failed`         | the provider session could not be opened                                                     |
| 502           | `control_plane_unavailable`   | plan fetch transport failure (managed mode)                                                  |
| 503           | `gateway_draining`            | the process is shutting down                                                                 |
| 504           | `control_plane_timeout`       | control-plane deadline exceeded (managed mode)                                               |
| *passthrough* | `control_plane_rejected`      | the control plane refused the plan; the original status is preserved                         |

On `control_plane_rejected`, correlate with Speko support using the `X-Control-Plane-Request-ID` response header. The control plane's own codes (for example `credit_exhausted`, `provider_not_entitled`) are documented in [Control plane API](/gateway/control-plane).

## In-stream errors [#in-stream-errors]

Failures after a session is established arrive as the [`error` event](/gateway/streaming#the-error-event) on the WebSocket, with `retryable`, `terminal`, and `source` fields.


# Speko Gateway (/gateway)

The open-source, customer-side runtime for real-time voice AI.



The Speko Gateway is an MIT-licensed sidecar binary (`spekoai/gateway` on Docker Hub, source at [github.com/SpekoAI/gateway](https://github.com/SpekoAI/gateway)) that runs **inside your infrastructure**, next to your agent. It gives your agent one local streaming protocol across voice providers, keeps BYOK credentials inside your process, and can optionally use Speko for managed routing, observability, and consolidated billing.

<Warning>
  Early preview: the protocol is versioned, but breaking changes may occur before the first stable release.
</Warning>

## What makes it different [#what-makes-it-different]

* **No network surface.** The gateway serves its API only on an owner-only Unix socket (`/run/speko/runtime.sock` by default). It opens no TCP port; the container exposes none.
* **Provider traffic is direct.** Audio and text flow straight from your process to the provider — never through Speko — on provider-direct routes.
* **Verified execution plans.** Every session is authorized by a signed plan the gateway verifies before attaching credentials or media. Managed plans come from Speko's control plane; BYOK plans are minted and HMAC-signed in-process.
* **One protocol, many providers.** Installed STT/TTS adapters share one [session API](/gateway/sessions) and [WebSocket stream](/gateway/streaming). The local [`GET /v1/models`](/gateway/models) response is authoritative for each build.

## Request-scoped credential sources [#request-scoped-credential-sources]

|                     | BYOK request                    | Speko-managed request                        |
| ------------------- | ------------------------------- | -------------------------------------------- |
| Selection           | `credential_source: "byok"`     | `credential_source: "managed"`               |
| Provider credential | yours, never leaves the process | short-lived, delegated per session           |
| Routing             | you name the provider           | Speko picks per request (`provider: "auto"`) |
| Billing             | your provider bills you         | consolidated on your Speko invoice           |
| Speko account       | not required                    | required                                     |

Both request types can coexist in one process. The LiveKit integration's `credential_source="auto"` selects managed when `SPEKO_API_KEY` or `SPEKO_API_KEY_FILE` is configured, and BYOK otherwise. Details in [Modes](/gateway/modes).

## The local API at a glance [#the-local-api-at-a-glance]

| Route                          | Purpose                                           |
| ------------------------------ | ------------------------------------------------- |
| `GET /healthz`, `GET /readyz`  | liveness and drain state (unauthenticated)        |
| `GET /v1/models`               | which adapters this build ships (unauthenticated) |
| `POST /v1/sessions`            | create a provider session                         |
| `GET /v1/sessions/{id}/stream` | the canonical WebSocket for audio and events      |
| `DELETE /v1/sessions/{id}`     | abort a session                                   |
| `GET /metrics`                 | Prometheus metrics (authenticated)                |

All authenticated routes take `Authorization: Bearer <SPEKO_LOCAL_AUTH_TOKEN>`.

Start with the [quickstart](/gateway/quickstart).


# Models (/gateway/models)

GET /v1/models — the adapters this gateway build implements.



## `GET /v1/models` [#get-v1models]

Unauthenticated. Answers "what does this build implement", with optional filters `?kind=stt|tts` and `?provider=<name>`:

```json
{
  "protocol": "speko.voice.v0",
  "protocol_revision": 3,
  "runtime": { "name": "go-gateway", "version": "0.1.0", "placement": "sidecar" },
  "models": [
    {
      "id": "elevenlabs:scribe_v2_realtime",
      "provider": "elevenlabs",
      "kind": "stt",
      "adapter": "elevenlabs.stt.v1",
      "transport": "websocket",
      "installed": true
    }
  ]
}
```

`id` is always `<provider>:<default_model>`. `installed: false` means the row is in the catalog but this deployment did not load the adapter. `requires_config` appears when a provider needs deployment configuration before it can route (currently only Google STT, which needs `SPEKO_GOOGLE_STT_ENDPOINT`).

<Note>
  This response shape is specific to the local gateway. The hosted Router's [`/v1/models`](/relay/models) is a different endpoint with a different schema — don't conflate them.
</Note>

## The installed catalog [#the-installed-catalog]

The response from your running gateway is the source of truth for its installed providers, adapters, default models, and configuration requirements. The dashboard's [Models page](https://platform.speko.ai/gateway/models) is authoritative for managed availability.

Representative local entries include Deepgram STT (`flux-general-en`), Deepgram TTS (`flux-haley-en`), and Soniox TTS (`tts-rt-v2`). Catalog contents change with gateway releases, so integrations should discover them through `/v1/models` instead of embedding a provider matrix.

Notes:

* Adapters are named `<provider>.<kind>.v1` and connect over WebSocket except Google TTS/STT, Hume, Inworld TTS, and OpenAI TTS, which are HTTP.
* No row carries media constraints, so `installed: true` does not mean the adapter accepts the [`media`](/gateway/sessions) you are sending. OpenAI STT accepts `sample_rate_hz: 24000` only; the gateway does not resample, and a refused rate surfaces as `502 session_open_failed` naming no field.
* Some TTS vendors refuse to open a session without a voice, so those adapters carry a default voice for local BYOK use. Google's default is deliberately empty because its voice names embed the language.
* Provider endpoints are validated against exact official host allowlists before credentials attach; production connections require TLS on port 443.
* LLM adapters are not part of the local gateway — language models are served by the [Router](/relay/llm/responses).


# BYOK and managed credentials (/gateway/modes)

Choose local BYOK or Speko-managed credentials independently for each request.



The gateway supports BYOK and Speko-managed sessions through the same local socket. Credential source is request-scoped, so one process can serve both at the same time.

## BYOK requests [#byok-requests]

Set at least one `SPEKO_<PROVIDER>_BYOK_API_KEY` (or its `_FILE` variant) and send `credential_source: "byok"`.

* Session plans are minted **in-process** and HMAC-signed with an ephemeral per-process key. No control-plane call is made for planning or fallback.
* Your provider key is injected into the provider request only after the local plan verifies. It never leaves the process.
* Sessions must request `credential_source: "byok"`, `provider_route: "provider_direct"` (or `"auto"`), and `relay_policy: "forbidden"`. If more than one configured BYOK provider supports the session kind, `request.provider` must name one explicitly.
* Provider-direct sessions receive a fixed local hard deadline capped by `SPEKO_LOCAL_MAX_SESSION_DURATION` (default `24h`). The deadline is not renewed during a call.
* Anonymous, content-free telemetry is sent by default; disable with `SPEKO_TELEMETRY_DISABLED=true`. It carries no API key, account ID, credential, or stable installation identifier.

## Speko-managed requests [#speko-managed-requests]

Set `SPEKO_API_KEY` (or `SPEKO_API_KEY_FILE`) and send `credential_source: "managed"`.

* Before a session opens, the gateway fetches a **signed session plan** from `gateway.speko.dev`: the route (provider, model, endpoint, adapter), a short-lived delegated provider credential, metering ceilings, and a session-scoped telemetry token. The gateway verifies signature, issuer, audience, expiry, and structure against the public JWKS before accepting media.
* `request.provider: "auto"` becomes available — Speko picks the route.
* One bounded **fallback** is available: if the provider fails to open, the gateway exchanges the failed attempt for a plan on a backup provider, transparently.
* Usage is metered and consolidated onto your Speko invoice, post-paid. See [Billing](/relay/billing).

### Warm plans (zero-overhead session setup) [#warm-plans-zero-overhead-session-setup]

For managed requests, the gateway prefetches a small pool of signed plans per route shape, so `POST /v1/sessions` normally costs **zero control-plane round trips**:

* `SPEKO_WARM_PLAN_TARGET` (default `4`) plans per route; `0` disables prefetching.
* Pre-declare hot routes with `SPEKO_WARM_ROUTES` (comma-separated `kind:provider[:model[:language]]`), or let the pool learn from traffic.
* Each warmed plan carries a short-lived credential; unused plans are discarded at expiry and settle at zero cost.

The trade-off is that delegated credentials exist in memory from prefetch time rather than session-start time — bounded by the plan TTL (minutes) and the pool size. Set `SPEKO_WARM_PLAN_TARGET=0` if that window matters more to you than setup latency.

## Automatic selection in the LiveKit integration [#automatic-selection-in-the-livekit-integration]

The raw local API always requires an explicit `execution.credential_source`. The LiveKit STT and TTS helpers default to `credential_source="auto"`:

* `SPEKO_API_KEY` or `SPEKO_API_KEY_FILE` configured → managed;
* otherwise → BYOK.

Set `credential_source="byok"` explicitly when you want voice requests to use local provider keys while keeping a Speko API key available for LLM Router calls or other managed traffic. The [validation rules](/gateway/sessions#validation-rules) cover the legal request combinations.


# Observability (/gateway/observability)

Health probes, Prometheus metrics, and what telemetry the gateway exports.



## Health probes [#health-probes]

Both are unauthenticated:

* `GET /healthz` → `200 {"status":"ok"}`
* `GET /readyz` → `200 {"status":"ready"}`, or `503 {"status":"draining"}` during shutdown

## Prometheus metrics [#prometheus-metrics]

`GET /metrics` (authenticated, unlike the probes) serves the standard text format:

| Metric                                                                                                     | Type    | Meaning                                 |
| ---------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------- |
| `speko_gateway_sessions_active`                                                                            | gauge   | Currently open sessions                 |
| `speko_gateway_sessions_total`                                                                             | counter | Sessions ever created                   |
| `speko_gateway_draining`                                                                                   | gauge   | 1 while shutting down                   |
| `speko_gateway_auth_failures_total`                                                                        | counter | Local auth rejections                   |
| `speko_gateway_input_queue_messages` / `..._bytes`                                                         | gauge   | Input backpressure                      |
| `speko_gateway_telemetry_dropped_total`                                                                    | counter | Telemetry events dropped under pressure |
| `speko_gateway_warm_plan_hits_total`, `..._misses_total`, `..._expired_total`, `..._refill_failures_total` | counter | Warm-pool effectiveness                 |
| `speko_gateway_warm_plan_depth`, `..._routes`                                                              | gauge   | Warm-pool state                         |

## Telemetry [#telemetry]

The gateway exports **content-free** events to Speko — no audio, no transcripts, no prompts, no tool arguments, no credentials, ever:

| Event            | Payload                                                 |
| ---------------- | ------------------------------------------------------- |
| `session.opened` | provider connection latency (`{"provider_open_ms": N}`) |
| `agent.event`    | canonical event type and sequence number                |
| `usage.observed` | provider request correlation ID                         |
| `usage.reported` | accepted usage quantity                                 |
| `session.closed` | no payload                                              |
| `error`          | error class, source, retryability, provider HTTP status |

Delivery is asynchronous and bounded (queue 1024, batches of 64, 3 attempts); under pressure events are dropped and counted rather than blocking media.

`SPEKO_TELEMETRY_DISABLED=true` suppresses anonymous and optional events. On managed routes, `usage.reported`, `usage.observed`, and the terminal event still flow — they are the billing record. BYOK routes have no mandatory events.

## Conversation profiler [#conversation-profiler]

The optional LiveKit `ConversationProbe` posts content-free markers to the gateway's local `POST /v1/turn-events` route. The gateway forwards managed markers to `gateway.speko.dev/v1/turn-events` with authentication, or BYOK markers to `/v1/anonymous-turn-events` without an authorization header.

Markers cover conversation and turn boundaries, speech timing, final-transcript timing, LLM first-token/completion, tool timing, TTS first audio, playback, interruptions, and attached route IDs. They never contain transcripts, prompts, model output, tool names or arguments, synthesized text, or audio. Conversation and turn IDs are random and opaque. Delivery is optional, bounded, and disabled by `SPEKO_TELEMETRY_DISABLED=true`.

## Heartbeats and the dashboard [#heartbeats-and-the-dashboard]

When a Speko API key is configured, the gateway heartbeats its instance identity, capacity, and session counters to the control plane every `SPEKO_INSTANCE_HEARTBEAT_INTERVAL` (default 20 s). Set `SPEKO_WORKLOAD_ID` (and optionally `SPEKO_WORKLOAD_TYPE`) to group instances into a named workload in the [dashboard](https://platform.speko.ai/gateway).


# Python integration (/gateway/python)

The speko-gateway Python package — a socket client and LiveKit STT, TTS, and LLM plugins.



The gateway image ships a pip-installable package at `/opt/speko/python` (also installable from the [source repo](https://github.com/SpekoAI/gateway/tree/main/integrations/python)). Requires Python ≥ 3.10; the LiveKit plugin needs the `livekit` extra.

```bash
pip install /opt/speko/python          # inside the container build
pip install "speko-gateway[livekit]"   # with the LiveKit plugin dependency
```

## LiveKit plugin [#livekit-plugin]

```python
from speko_gateway.livekit import STT

stt = STT(
    language="en",
    provider="auto",
    model="auto",
    credential_source="auto",
    sample_rate=16_000,
)
```

`sample_rate` is forwarded to the provider unchanged — the gateway does not
resample, so it has to match what the chosen adapter accepts, and the default of
`16_000` does not suit every one. OpenAI STT accepts `24_000` only; sending
anything else fails session create as `502 session_open_failed`, which names no
field. Note the TTS class defaults to `24_000` instead, so the two are not
interchangeable.

A `livekit.agents.stt.STT` subclass with streaming and interim results. It connects to the gateway over the Unix socket automatically and maps gateway events onto LiveKit speech events (`speech.started`/`speech.ended` → start/end of speech, `transcript.delta` → interim, `transcript.final` → final).

`provider` and `model` default to `"auto"`. `credential_source="auto"` chooses managed when `SPEKO_API_KEY` or `SPEKO_API_KEY_FILE` is configured and BYOK otherwise. Set it explicitly to mix managed and BYOK voice legs in the same process.

## Conversation profiler [#conversation-profiler]

Attach the optional probe to collect content-free turn timing in the dashboard profiler:

```python
from speko_gateway.probe import ConversationProbe

probe = ConversationProbe(session)
probe.start()
await session.start(...)
# ...
await probe.aclose()
```

### TTS [#tts]

```python
from speko_gateway.livekit import TTS

tts = TTS(
    voice="",
    language="en",
    provider="auto",
    model="auto",
    sample_rate=24_000,
    max_input_characters=100_000,
    credential_source="auto",
)
```

A `livekit.agents.tts.TTS` subclass, synthesizing over the same socket. Note the
default `sample_rate` is `24_000` here, where the STT class defaults to `16_000`.

### LLM [#llm]

```python
from speko_gateway.livekit import LLM

llm = LLM(
    provider="auto",
    model="auto",
    objective="balanced",
    max_output_tokens=8192,
)
```

A `livekit.agents.llm.LLM` subclass. Unlike STT and TTS it does **not** use the
local socket — language models are not part of the gateway build, so this calls
the hosted [Router](/relay/llm/responses) directly. A failure here is a Router
problem, not a sidecar one.

It reports timing markers for speech, transcription, LLM, tools, TTS, playback, and interruptions through the gateway's local `POST /v1/turn-events` endpoint. It never sends transcripts, prompts, tool names or arguments, synthesized text, or audio. `SPEKO_TELEMETRY_DISABLED=true` suppresses it entirely.

## GatewayClient [#gatewayclient]

For anything beyond the plugin, the low-level async client:

```python
import asyncio
from speko_gateway.client import GatewayClient, SessionConfig

async def main():
    client = GatewayClient.from_env()   # reads SPEKO_SOCKET_PATH + SPEKO_LOCAL_AUTH_TOKEN
    await client.ready()

    session = await client.open(SessionConfig(
        kind="stt",
        provider="deepgram",
        language="en",
        sample_rate_hz=16_000,
    ))

    await session.send_audio(pcm_bytes)
    await session.commit_audio()

    async for event in session.events():
        if event.type == "transcript.final":
            print(event.data["text"])
        if event.type in ("session.closed", "error"):
            break

    await session.aclose()

asyncio.run(main())
```

Session methods: `send_audio`, `commit_audio`, `append_text`, `commit_text`, `cancel`, `finish`, `aclose`, and the `events()` iterator. `open()` generates a UUID idempotency key unless you pass `idempotency_key=` yourself.

Secrets follow the same rules as the gateway: `SPEKO_LOCAL_AUTH_TOKEN_FILE` works anywhere `SPEKO_LOCAL_AUTH_TOKEN` does.


# Quickstart (/gateway/quickstart)

Add the gateway sidecar to a LiveKit agent container and transcribe with your own Deepgram key.



## 1. Add the gateway to your agent image [#1-add-the-gateway-to-your-agent-image]

The gateway ships as a static binary plus a Python integration in the `spekoai/gateway` image. Add both to your existing agent Dockerfile:

```dockerfile
FROM spekoai/gateway:latest AS speko

FROM python:3.12-slim
# ... your existing agent build ...

COPY --from=speko /usr/local/bin/speko-gateway /usr/local/bin/speko-gateway
COPY --from=speko /opt/speko/python /opt/speko/python
RUN pip install /opt/speko/python

# Run the gateway alongside your agent process
```

Start `speko-gateway` before (or supervised alongside) your agent process — it is one binary with no arguments; all configuration is environment variables.

## 2. Configure BYOK mode [#2-configure-byok-mode]

The minimum viable environment is a local auth token plus one provider key:

```bash
export SPEKO_LOCAL_AUTH_TOKEN=$(openssl rand -hex 32)
export SPEKO_DEEPGRAM_BYOK_API_KEY=dg_your_key
```

Every secret also accepts an exclusive `_FILE` variant (`SPEKO_DEEPGRAM_BYOK_API_KEY_FILE=/run/secrets/deepgram`) for file-mounted secrets.

## 3. Use it from a LiveKit agent [#3-use-it-from-a-livekit-agent]

```python
from livekit.agents import AgentSession
from speko_gateway.livekit import STT

session = AgentSession(
    stt=STT(),   # connects to the gateway's Unix socket automatically
    # ... llm, tts, vad as usual ...
)
```

`STT()` defaults to `language="en"`, `provider="auto"`, `model="auto"`, `credential_source="auto"`, and a 16 kHz stream. The plugin reads `SPEKO_SOCKET_PATH` and `SPEKO_LOCAL_AUTH_TOKEN` from the environment. Automatic credential selection uses managed credentials when `SPEKO_API_KEY` or `SPEKO_API_KEY_FILE` is configured, and BYOK otherwise.

## 4. Or call the local API directly [#4-or-call-the-local-api-directly]

```bash
curl -s --unix-socket /run/speko/runtime.sock http://speko-gateway/v1/sessions \
  -H "Authorization: Bearer $SPEKO_LOCAL_AUTH_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "stt",
    "execution": { "provider_route": "provider_direct", "credential_source": "byok", "relay_policy": "forbidden" },
    "request": { "provider": "deepgram", "language": "en" },
    "media": { "encoding": "pcm_s16le", "sample_rate_hz": 16000, "channels": 1 }
  }'
```

The response includes a `stream_url`; attach the [WebSocket](/gateway/streaming) there and start sending audio.

## 5. Go managed (optional) [#5-go-managed-optional]

Set a Speko API key, then select managed credentials for the requests that Speko should route and bill:

```bash
export SPEKO_API_KEY=sk_speko_...
```

BYOK and managed requests can coexist in one gateway process. See [Modes](/gateway/modes) for selection rules, and the hardened [docker-compose example](https://github.com/SpekoAI/gateway/blob/main/deploy/docker-compose.yml) for production container settings (read-only rootfs, dropped capabilities, non-root user).


# Sessions (/gateway/sessions)

POST /v1/sessions — create a provider session on the local gateway API.



## Create a session [#create-a-session]

`POST /v1/sessions` on the Unix socket, with `Authorization: Bearer <SPEKO_LOCAL_AUTH_TOKEN>` and a required `Idempotency-Key` header (any non-blank string; bodies are capped at 64 KiB and unknown fields are rejected).

```json
{
  "kind": "tts",
  "integration": { "name": "custom", "version": "1.0.0" },
  "execution": {
    "provider_route": "provider_direct",
    "credential_source": "managed",
    "relay_policy": "forbidden"
  },
  "request": {
    "provider": "auto",
    "voice": "voice_123",
    "language": "en",
    "max_input_characters": 4000
  },
  "media": { "encoding": "pcm_s16le", "sample_rate_hz": 16000, "channels": 1 }
}
```

<ParamField name="kind" type="string">
  `stt`, `tts`, `llm`, or `realtime`.
</ParamField>

<ParamField name="execution.provider_route" type="string">
  `auto`, `provider_direct`, or `speko_relay`. `auto` is request-only — the resolved plan always names a concrete route.
</ParamField>

<ParamField name="execution.credential_source" type="string">
  `managed` or `byok`. This is selected independently for every request, so both can coexist in one gateway process.
</ParamField>

<ParamField name="execution.relay_policy" type="string">
  `required`, `allowed`, or `forbidden`.
</ParamField>

<ParamField name="request.provider" type="string">
  Provider name, or `auto`. Managed requests can delegate selection to Speko. BYOK requests resolve `auto` only when exactly one configured provider supports the session kind. Blank is treated as `auto`.
</ParamField>

<ParamField name="request.voice" type="string">
  Provider voice ID. Always wins when set; when absent, the plan's route voice applies — this exists because a caller sending `provider: "auto"` cannot know which vendor's voice ID space to use.
</ParamField>

<ParamField name="request.max_input_characters" type="number">
  **Required for TTS** (must be positive); must be absent for every other kind.
</ParamField>

<ParamField name="media" type="object">
  Required for `stt`, `tts`, and `realtime`; forbidden for `llm`. `encoding` is `pcm_s16le` or `opus`; `sample_rate_hz` 8000–192000; `channels` 1–8.

  That range is what the protocol accepts, **not** what every adapter accepts. The
  gateway forwards `sample_rate_hz` to the provider unchanged and does not resample,
  so a rate this endpoint validates can still be refused upstream. A provider that
  refuses one surfaces as `502 session_open_failed`, which names no field — so a
  session that will not open on an otherwise-correct request is worth retrying at
  the provider's rate before assuming the adapter is broken.

  Known constraint: **`openai` STT (`gpt-live-transcribe`) accepts 24000 only** —
  OpenAI's own minimum and maximum are both 24000. Every example in these docs
  uses 16000, so copy one for that adapter and the session will not open.
</ParamField>

### Validation rules [#validation-rules]

* `byok` cannot use `speko_relay`, and cannot set `relay_policy: "required"`.
* `relay_policy: "required"` conflicts with `provider_route: "provider_direct"`; `relay_policy: "forbidden"` conflicts with `provider_route: "speko_relay"`.
* Local BYOK sessions require `byok` + `provider_direct` (or `auto`) + `relay_policy: "forbidden"`, and must name `request.provider` when more than one configured BYOK provider supports the kind.
* `integration.name` and `integration.version` must be provided together.

### Idempotency [#idempotency]

Reusing an `Idempotency-Key` with the same body replays the original response with `200`; the same key with a different body returns `409 idempotency_key_conflict`. Concurrent requests with one key join the same in-flight attempt.

## Response [#response]

`201 Created` (or `200 OK` on replay):

```json
{
  "session_id": "session_...",
  "attempt_id": "attempt_...",
  "execution": { "placement": "sidecar", "provider_route": "provider_direct", "credential_source": "managed" },
  "route": { "provider": "deepgram", "model": "flux-general-en", "region": "eu", "adapter": "deepgram.stt.v1", "transport": "websocket" },
  "stream_url": "/v1/sessions/session_.../stream",
  "control_plane_request_id": "..."
}
```

The `route` deliberately omits the provider endpoint's query string and the credential. Failed creates that involved the control plane carry an `X-Control-Plane-Request-ID` response header for support correlation.

Attach the WebSocket at `stream_url` within 30 seconds — unattached sessions expire. See [Streaming](/gateway/streaming).

## Delete a session [#delete-a-session]

`DELETE /v1/sessions/{session_id}` aborts and removes the session, returning `204 No Content`.


# Streaming (/gateway/streaming)

The canonical session WebSocket — subprotocol, frames, and the event schema.



## Attaching [#attaching]

`GET /v1/sessions/{session_id}/stream` upgrades to a WebSocket. Requirements:

* `Authorization: Bearer <SPEKO_LOCAL_AUTH_TOKEN>`
* The subprotocol &#x2A;*`speko.voice.v0.r3`**, sent as `Sec-WebSocket-Protocol` (missing → `400 unsupported_protocol`)
* One consumer per session — a second attach returns `409 stream_already_attached`
* Attach within 30 seconds of session creation

## Client → gateway frames [#client--gateway-frames]

| Frame                                            | Meaning                                 |
| ------------------------------------------------ | --------------------------------------- |
| *binary*                                         | Raw audio in the session's media format |
| `{"type":"audio.commit"}`                        | End of the current audio input          |
| `{"type":"text.append","data":{"text":"Hello"}}` | Append text input (TTS/LLM)             |
| `{"type":"text.commit"}`                         | Flush appended text                     |
| `{"type":"response.cancel"}`                     | Cancel the in-flight response           |
| `{"type":"session.close"}`                       | Close the session cleanly               |

Anything else is a connection error. Input is bounded per session: 64 queued messages / 1 MiB queued bytes — producers that outrun the provider see backpressure errors rather than unbounded memory growth.

## Gateway → client frames [#gateway--client-frames]

Binary frames carry synthesized audio. Text frames are JSON events:

```json
{
  "type": "transcript.final",
  "event_id": "evt_...",
  "session_id": "session_...",
  "attempt_id": "attempt_...",
  "sequence": 12,
  "created_at_ms": 1754000000000,
  "data": { "text": "Hello there." }
}
```

Event types:

| Category      | Events                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------- |
| Lifecycle     | `session.ready`, `session.recovering`, `session.recovered`, `session.closed`                      |
| Speech        | `speech.started`, `speech.ended`                                                                  |
| Transcription | `transcript.delta`, `transcript.final`                                                            |
| Generation    | `response.started`, `text.delta`, `text.done`, `tool.call`, `response.done`, `response.cancelled` |
| Audio         | `audio.started`, `audio.done` (audio itself arrives as binary frames)                             |
| Metadata      | `alignment`, `route.selected`, `usage.observed`, `usage.reported`, `warning`, `error`             |

## The `error` event [#the-error-event]

```json
{
  "type": "error",
  "data": {
    "code": "provider_unavailable",
    "message": "...",
    "retryable": true,
    "terminal": true,
    "source": "provider",
    "provider_status": 503
  }
}
```

`source` is `runtime` or `provider`. Provider-sourced codes: `provider_unavailable`, `provider_rate_limited`, `provider_quota_exceeded`, `authentication_failed`, `invalid_request`, `input_too_large`. Runtime codes include `internal` and `session_lease_expired`. The latter means the fixed deadline in the verified plan elapsed; provider-direct sessions do not renew it mid-call.

## Liveness [#liveness]

Frames the gateway writes time out after 15 seconds if the consumer stalls; slow consumers see the session terminated rather than blocking other sessions.


# Trust and signing (/gateway/trust)

How signed plans, JWKS keys, and credential rules keep the gateway trustworthy.



## Plan verification [#plan-verification]

Every session — BYOK or managed — is authorized by a plan the gateway verifies before any credential attaches or media flows.

**Managed plans** are JWS artifacts signed by the control plane:

* Protected header: `alg` (`EdDSA` or `RS256`), a non-blank `kid`, `typ: speko.session-plan+jws`.
* Payload claims: issuer (must equal the configured control plane), audience (must contain `speko-runtime`), `iat`/`exp` with 30 s clock skew, and a `jti` consumed exactly once — replaying a plan fails.
* The enclosed plan must match the served plan **byte for byte**, and the envelope `exp` must equal the plan's own `expires_at`.

Keys are fetched from [`gateway.speko.dev/.well-known/jwks.json`](https://gateway.speko.dev/.well-known/jwks.json), with `Cache-Control`/`ETag` honored, an unknown `kid` forcing one synchronous refresh, and HTTPS-only redirects.

**Local BYOK plans** never touch the network: the gateway mints the plan itself and HMAC-signs it with an ephemeral per-process key (`local.v1.` signature prefix, 1-minute TTL). The same verification pipeline runs either way — BYOK keys are injected only after the plan verifies.

## Plan invariants worth knowing [#plan-invariants-worth-knowing]

* BYOK plans must **not** carry a credential; managed plans must.
* A credential can never outlive its plan.
* Transport and endpoint scheme are cross-checked (`websocket` → `wss`, `http` → `https`, and so on), and provider endpoints must match exact official host allowlists.
* Managed plans carry a telemetry block with a session-scoped token; that token — not your API key — authenticates runtime telemetry. Provider-direct deadlines are fixed and are not renewed mid-call.

## The hosted Router plan family [#the-hosted-router-plan-family]

The hosted Router uses a **second, deliberately isolated plan family**: `typ: speko.relay-plan+jws`, audience `speko-relay`, protocol revision `5`, signed with a **different key** published at [`gateway.speko.dev/.well-known/relay-jwks.json`](https://gateway.speko.dev/.well-known/relay-jwks.json). The local session protocol remains revision `3`; Router protocol revision 5 is a parallel artifact for the hosted fleet, not its successor. Separate keys and audiences mean neither plan family's signature can ever authorize the other's consumer.

## Credential rules [#credential-rules]

* Local gateway **BYOK keys** stay in gateway memory. They are never sent to Speko — not even in the setup request. Hosted [Router BYOK](/relay/byok) uses separately encrypted organization credentials resolved inside regional connectors.
* Your &#x2A;*`SPEKO_API_KEY`** is used only against `gateway.speko.dev`. It is never sent to a provider.
* **Delegated provider credentials** in managed plans are short-lived and session-scoped.
* On managed Deepgram STT routes, the provider also receives Speko's opaque reservation ID for bill correlation — no other customer data.

## What the setup request contains (managed mode) [#what-the-setup-request-contains-managed-mode]

Session kind and protocol revision; gateway version, instance ID, installed adapters; optional integration name/version; route and credential constraints; requested provider, model, voice, language, region, allow/deny lists, TTS character allowance, and the routing `objective`; media format.

<Warning>
  Do not put prompts, transcripts, or user content in `objective` or any other setup field — setup requests are routing metadata, not payload.
</Warning>

## Limits of the model [#limits-of-the-model]

Process memory is not a hardware security boundary: run the gateway with least privilege, a read-only filesystem, and a dedicated workload identity. In the single-container sidecar layout, your agent process can read the shared environment — split containers when you need credential isolation from your own agent code.


# API keys (/relay/api-keys)

Creating, using, and protecting Speko API keys.



## Format [#format]

Speko API keys look like:

```
sk_speko_<43 characters of base64url>
```

A key belongs to one organization and authorizes both product surfaces:

* **Router** — sent as `Authorization: Bearer sk_speko_...` on every request to `router.speko.dev`.
* **Gateway (managed mode)** — set as `SPEKO_API_KEY` in the sidecar's environment; the gateway uses it only to talk to the control plane, never to a provider.

## Creating keys [#creating-keys]

Create and revoke keys in the dashboard's [API keys](https://platform.speko.ai/gateway/keys) page. Gateway key creation includes the Router stack composer, and organizations can create as many active keys as their environments and workloads require. The raw key is shown **exactly once** at creation time — Speko stores only a keyed hash (HMAC-SHA256) and cannot recover the value. Store it in your secrets manager immediately.

Keys can be revoked at any time; revocation takes effect immediately.

## Handling rules [#handling-rules]

<Warning>
  Never ship an `sk_speko_` key to a browser, mobile app, or any other client you distribute. Keys are server-side credentials: anyone holding one can spend against your organization until you revoke it.
</Warning>

* Prefer one key per service or environment so you can revoke narrowly.
* The gateway accepts every secret as either `SPEKO_API_KEY` or `SPEKO_API_KEY_FILE` (mutually exclusive) so you can mount keys from files instead of environment variables.
* Speko never asks for your key over email or support channels.

## What a key is not [#what-a-key-is-not]

A key does not select routes, models, or regions — that is done per request. It also carries no spending cap of its own; credit and concurrency limits apply at the organization level. See [Billing](/relay/billing).


# Authentication (/relay/authentication)

Bearer keys, required headers, and the response headers on every Router call.



## Bearer authentication [#bearer-authentication]

Every Router request — HTTP and WebSocket alike — authenticates with a Speko API key:

```
Authorization: Bearer sk_speko_...
```

The scheme must be exactly `Bearer` and the token must be a single non-blank string. Failures return `401` with code `authentication_failed`:

```json
{"error":{"code":"authentication_failed","message":"a Bearer authorization header is required","retryable":false}}
```

See [API keys](/relay/api-keys) for creating and protecting keys.

## Required request headers [#required-request-headers]

| Header            | Required on                                | Notes                                                             |
| ----------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| `Authorization`   | everything except `/healthz`, `/readyz`    | `Bearer sk_speko_...`                                             |
| `Idempotency-Key` | every POST **and every WebSocket upgrade** | opaque, at most 256 bytes — see [Idempotency](/relay/idempotency) |
| `Content-Type`    | POST bodies                                | `application/json`, or `multipart/form-data` for transcriptions   |

`GET /v1/models` needs only the `Authorization` header.

## Response headers [#response-headers]

Every routed response carries correlation and route headers:

| Header                   | Meaning                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `Speko-Request-ID`       | Stable ID for the request (`rreq_...`). Quote it in support requests.                                                       |
| `Speko-Attempt-ID`       | The provider attempt that produced this response. Changes on failover.                                                      |
| `Speko-Provider`         | Provider that served the request                                                                                            |
| `Speko-Model`            | Model that served the request                                                                                               |
| `Speko-Region`           | The Speko region that served you — a proximity fact about Speko infrastructure, **not** a provider data-residency guarantee |
| `Speko-Usage-Characters` | TTS one-shot only: characters metered for the synthesis                                                                     |

Error responses also carry `Speko-Request-ID` whenever one was assigned, and the same ID appears as `request_id` inside the [error envelope](/relay/errors).

<Note>
  `GET /v1/models` responses use an edge-local correlation ID of the form `req_edge_...` rather than `rreq_...` — listing the catalog does not create an admitted request.
</Note>


# Billing and usage (/relay/billing)

How Speko meters, prices, and settles managed usage.



## Post-paid by default [#post-paid-by-default]

Managed usage on Speko is **post-paid**: nothing is charged before a request runs, usage is metered as it happens, and you are invoiced monthly for what was actually consumed. Your organization has a credit limit and an optional monthly spend limit; requests are refused with a `402` error when the projected cost of in-flight work would exceed remaining credit.

[BYOK Router routes](/relay/byok) and BYOK gateway sessions generate **no Speko provider-usage charges** — your provider bills you directly. Managed routes are metered and invoiced by Speko.

## How a request is metered [#how-a-request-is-metered]

1. **Admission.** Before work starts, Speko computes a conservative ceiling for the request — audio duration for STT, character count for TTS, token estimates plus your `max_output_tokens` for LLM calls — and checks it against your available credit and concurrency limits.
2. **Frozen prices.** Unit rates are frozen **per attempt** when the attempt starts. If Speko fails over to another provider mid-request, the new attempt gets its own frozen rates; a price change can never reprice work already delivered.
3. **Usage reporting.** Actual consumption (seconds transcribed, characters accepted, tokens in and out) is reported as the request runs and settles afterward. You are billed for reported usage, not for the admission ceiling.

## What counts as usage [#what-counts-as-usage]

* **STT** — audio duration, in seconds.
* **TTS** — characters **accepted for synthesis**. On streaming TTS, characters count when an `input.append` is accepted; cancelling playback afterward does not refund them.
* **LLM** — input tokens, cached input tokens, output tokens, and reasoning tokens, reported as mutually exclusive lines that always sum to the totals.

Every Router response carries `Speko-Request-ID` and `Speko-Attempt-ID` headers so you can correlate a line on your invoice with a specific request and attempt.

## Limits [#limits]

| Limit               | Applies to   | When exceeded                                                               |
| ------------------- | ------------ | --------------------------------------------------------------------------- |
| Credit limit        | organization | `402 insufficient_credit` (Router) / `402 credit_exhausted` (control plane) |
| Monthly spend limit | organization | same as credit exhaustion, resets monthly                                   |
| Concurrency limit   | organization | `429 concurrency_exhausted` / `429 quota_exhausted`                         |

The dashboard's [usage view](https://platform.speko.ai/gateway/usage) shows requests, failures, failovers, latency percentiles, and per-model breakdowns in near real time.


# Bring your own provider keys (/relay/byok)

Use your own provider credentials with the hosted Router.



Router can use provider credentials that your organization stores in Speko. Configure them in the dashboard's [BYOK page](https://platform.speko.ai/gateway/byok); you keep the same Router endpoints and request shapes.

## How credential selection works [#how-credential-selection-works]

A configured key takes precedence for that provider. If Router selects a provider for which your organization has a key, the request uses that key. If the provider has no configured key, the request uses Speko-managed credentials.

Auto routing chooses a route first, then resolves the credential for the selected provider. You do not add a credential-source field to Router requests.

## Billing [#billing]

* **BYOK route:** the provider bills your provider account directly. Speko does not charge provider usage for that attempt.
* **Managed route:** usage appears on your Speko invoice at the price frozen when the attempt starts.

Removing a provider key returns that provider to managed credentials for future requests.

## Storage and access [#storage-and-access]

Provider credentials are encrypted at rest. The Runtime control plane never decrypts them; only the regional provider connector handling an authorized request resolves and decrypts the selected credential.

## Failover preserves the credential source [#failover-preserves-the-credential-source]

Automatic failover stays within the original credential-source set:

* a BYOK attempt can fall back only to another provider for which your organization has a configured key;
* a managed attempt can fall back only to a provider without an organization key;
* [explicit routing](/relay/routing#explicit-mode) never falls back.

If no healthy compatible route remains in the same set, the request returns a provider-unavailable error instead of silently changing who bills you.


# Errors (/relay/errors)

The Router's single error envelope and closed error-code set.



## The envelope [#the-envelope]

Every non-2xx HTTP response, every SSE `error` event, and every WebSocket `error` frame carries the same JSON envelope:

```json
{
  "error": {
    "code": "insufficient_credit",
    "message": "the organization has insufficient credit for this request",
    "retryable": false,
    "request_id": "rreq_9f2c1a"
  }
}
```

<ResponseField name="code" type="string">
  One of the closed set below. New codes may be added over time, but codes are never repurposed.
</ResponseField>

<ResponseField name="retryable" type="boolean">
  Whether retrying the same request (same idempotency key) can succeed without you changing anything.
</ResponseField>

<ResponseField name="request_id" type="string">
  Present when the request was assigned an ID. On `request_already_started` it names the **original** request.
</ResponseField>

Raw provider error bodies are **never** forwarded; provider failures are normalized into the codes below with fixed messages.

## The code set [#the-code-set]

| HTTP status | Code                      | Meaning                                                                                        |
| ----------- | ------------------------- | ---------------------------------------------------------------------------------------------- |
| 400         | `invalid_request`         | Malformed body, missing `Idempotency-Key`, bad routing object, unknown fields                  |
| 400         | `capability_unsupported`  | No routable provider supports what the request needs (for example, tools)                      |
| 401         | `authentication_failed`   | Missing or invalid bearer token                                                                |
| 402         | `insufficient_credit`     | Organization credit cannot cover the request's ceiling                                         |
| 409         | `request_in_progress`     | Same idempotency key + content, original still admitting — retryable                           |
| 409         | `request_already_started` | Same key + content, original already dispatched; carries the original `request_id`             |
| 409         | `idempotency_conflict`    | Same key, **different** content                                                                |
| 413         | `payload_too_large`       | Body or audio part over the [limits](/relay/limits)                                            |
| 415         | `unsupported_media`       | Audio container could not be parsed                                                            |
| 429         | `rate_limited`            | Slow down                                                                                      |
| 429         | `concurrency_exhausted`   | Organization or edge concurrency slots, or batch-audio staging capacity, exhausted — retryable |
| 500         | `relay_error`             | Internal Router failure                                                                        |
| 502         | `provider_error`          | The provider failed after output started                                                       |
| 503         | `provider_unavailable`    | No provider currently available — retryable                                                    |
| —           | `budget_exhausted`        | Stream-only: a budget extension was refused mid-stream                                         |
| —           | `lease_expired`           | Stream-only: the session's lease could not be renewed                                          |

`budget_exhausted` and `lease_expired` have no HTTP status because they can only terminate an already-established stream — as the final WebSocket `error` frame or SSE `error` event.

## Retry guidance [#retry-guidance]

* Honor the `retryable` flag first; it is per-error truth.
* Retry with the **same idempotency key** so a request that actually started is not duplicated — you will get `request_already_started` with the original request ID instead of a second charge.
* Back off on `429` and `503`; they indicate pressure, not a broken request.
* `4xx` codes other than `409`/`429` mean the request itself must change.


# Idempotency (/relay/idempotency)

Every mutating Router call requires an idempotency key. Here is exactly how reuse behaves.



## The rule [#the-rule]

Send an `Idempotency-Key` header on **every POST and every WebSocket upgrade**:

```
Idempotency-Key: 5f3a1c9e-7b42-4b8a-9d55-0c6a1f2e8d31
```

The key is opaque to Speko — any non-blank string up to **256 bytes**. A UUID per logical request is the right default. Requests without a key are rejected with `400 invalid_request`.

<Warning>
  Browsers cannot set custom headers on WebSocket upgrades, so the streaming endpoints cannot be called directly from browser JavaScript. Terminate Router WebSockets from your backend.
</Warning>

## Content hashing [#content-hashing]

Idempotency compares your key **and** a SHA-256 hash of the request content (`sha256:` + 64 lowercase hex):

* **JSON bodies** — the raw body bytes exactly as sent.
* **Multipart bodies** (STT transcriptions) — the decoded payload bytes of the `request` part, then the `audio` part, concatenated in that order. Part headers and boundary strings are excluded, so honest retries with a new boundary still match.
* **WebSocket sessions** — the exact bytes of the `session.configure` text frame. Frames after configure are outside the hash.

## Reuse semantics [#reuse-semantics]

| You resend                      | While                                | Result                                                                                                                                                                  |
| ------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| same key, same content          | the original is still being admitted | `409 request_in_progress` — **retryable**; back off briefly and retry                                                                                                   |
| same key, same content          | the original was already dispatched  | `409 request_already_started`, carrying the **original** `request_id` in the error envelope. The Router is stateless per request and cannot replay the original output. |
| same key, **different** content | any time                             | `409 idempotency_conflict` — you reused a key for a different request; fix the key                                                                                      |

```json
{
  "error": {
    "code": "request_already_started",
    "message": "a request with this idempotency key has already started",
    "retryable": false,
    "request_id": "rreq_the_original_request"
  }
}
```

## Practical guidance [#practical-guidance]

* Generate a fresh key per logical operation and **reuse it on retries** of that operation — that is what makes network-level retries safe.
* Never reuse a key across different payloads; that is always a `409 idempotency_conflict`.
* Persist the key alongside your job record so crash-recovery retries stay idempotent.


# Speko Router (/relay)

One hosted API for speech-to-text, text-to-speech, and language models across every provider in the Speko catalog.



Speko Router is a hosted API at &#x2A;*`https://router.speko.dev`** (WebSockets at `wss://router.speko.dev`). You send one request shape; Speko routes it to the best provider, opens the provider connection with either a Speko-managed credential or [your configured provider key](/relay/byok), and streams the result back.

## Endpoints [#endpoints]

| Endpoint                                                                  | What it does                                                                |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [`GET /v1/models`](/relay/models)                                         | The catalog of currently routable models                                    |
| [`POST /v1/stt/transcriptions`](/relay/stt/batch)                         | Transcribe an audio file                                                    |
| [`POST /v1/stt/transcriptions/jobs`](/relay/stt/jobs)                     | Transcribe a recording of any length asynchronously, delivered to a webhook |
| [`GET /v1/stt/transcriptions/jobs/{job_id}`](/relay/stt/jobs#fetch-a-job) | Fetch a transcription job                                                   |
| [`GET /v1/stt/stream`](/relay/stt/streaming)                              | Live transcription over WebSocket                                           |
| [`POST /v1/tts/speech`](/relay/tts/speech)                                | Synthesize speech from text                                                 |
| [`GET /v1/tts/stream`](/relay/tts/streaming)                              | Streaming synthesis over WebSocket                                          |
| [`POST /v1/llm/responses`](/relay/llm/responses)                          | Generate a model response, optionally streamed as SSE                       |

## Why Router [#why-router]

* **One contract.** Providers differ in auth, framing, and error shapes. The Router normalizes all of it: one [routing object](/relay/routing), one [error envelope](/relay/errors), one [usage schema](/relay/usage).
* **Managed or BYOK.** Configure provider keys once in the dashboard. Each selected route automatically uses the appropriate credential source while preserving the same Router API.
* **Automatic failover.** In auto-routing mode, a provider failure before the first byte of output transparently retries on the next-best provider. Your request ID stays the same; the attempt ID changes.
* **Health-gated catalog.** Every route is continuously probed by Speko's canary in every region. A model only appears in `/v1/models` — and only receives auto-routed traffic — while its latest probe passed.
* **Anycast entry.** `router.speko.dev` resolves to static anycast IPs (AWS Global Accelerator) and lands your connection on the nearest healthy region. Responses carry a `Speko-Region` header naming the region that served you.

## The two rules every request follows [#the-two-rules-every-request-follows]

1. **Authenticate** with `Authorization: Bearer sk_speko_...` — see [Authentication](/relay/authentication).
2. **Send an `Idempotency-Key` header** on every POST and every WebSocket upgrade — see [Idempotency](/relay/idempotency). Requests without one are rejected.

## Health [#health]

`GET /healthz` and `GET /readyz` are public and unauthenticated:

```json
{"status":"ok"}
```

Start with the [quickstart](/relay/quickstart).


# Limits (/relay/limits)

Size caps, timeouts, and concurrency limits on the Router.



## Size limits [#size-limits]

| Limit                                                    | Value                                                                       | Exceeded →              |
| -------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- |
| JSON request body                                        | 1 MiB                                                                       | `413 payload_too_large` |
| STT `request` multipart part                             | 1 MiB                                                                       | `413 payload_too_large` |
| Batch STT audio (`/v1/stt/transcriptions`)               | Selected model's advertised batch limit, plus any deployment safety ceiling | `413 payload_too_large` |
| Transcription job upload (`/v1/stt/transcriptions/jobs`) | 2 GiB (deployment default); the model's limit is handled by chunking        | `413 payload_too_large` |
| WebSocket frame                                          | 1 MiB                                                                       | stream error            |
| `Idempotency-Key` header                                 | 256 bytes                                                                   | `400 invalid_request`   |

Batch transcription has no universal 25 MiB cap. Limits are provider- and
model-specific, and constrain decoded PCM bytes, recording duration, or both;
they are the bounds of each provider's pre-recorded API. See
[Batch transcription limits](/relay/stt/batch#limits) for the current table and
query `GET /v1/models?path=batch` for the authoritative catalog in your serving
region. Recordings over a model's limit belong on
[transcription jobs](/relay/stt/jobs), which split them into provider-sized
chunks.

## Time limits [#time-limits]

| Limit                                                    | Value                    |
| -------------------------------------------------------- | ------------------------ |
| Request body read deadline                               | 2 minutes                |
| WebSocket `session.configure` deadline                   | 10 seconds after connect |
| Keepalive cadence (WS pings, SSE `: heartbeat` comments) | every 20 seconds         |

There is deliberately no overall wall-clock cap on streaming sessions — liveness is enforced by heartbeats and by [budget and lease extension](/relay/usage#budgets-on-streams).

## Concurrency [#concurrency]

Three independent layers can refuse work with `429 concurrency_exhausted` (retryable):

1. **Per-organization slots** — your account's concurrent-request limit, enforced at admission. Contact Speko to raise it.
2. **Per-edge stream slots** — a local cap on any single Router edge task. Retrying lands on capacity elsewhere.
3. **Batch-audio staging capacity** — temporary disk reserved for in-flight transcription uploads. Retrying can succeed after capacity is released or on another task.

Transcription jobs add a fourth, per-organization ceiling: at most 64 jobs and 32 GiB of decoded audio in flight at once. See [job limits](/relay/stt/jobs#limits).

`429 rate_limited` is distinct: it is request-rate pressure rather than slot exhaustion. Back off in both cases.

## Regional behavior [#regional-behavior]

`router.speko.dev` is anycast (AWS Global Accelerator, static IPv4 addresses); connections land on the nearest healthy region and stay there for their lifetime. [`/v1/models`](/relay/models) reflects the serving region's catalog, and every response names its region in `Speko-Region`. If a region is drained for maintenance, new connections shift automatically; in-flight streams on a draining task are given a generous window to complete.


# Models (/relay/models)

The Router catalog, capability flags, and how canary probes gate what is routable.



## `GET /v1/models` [#get-v1models]

Returns the models **currently routable for your organization from the region serving you**:

```bash
curl -s https://router.speko.dev/v1/models \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

```json
{
  "models": [
    {
      "id": "claude-sonnet-5",
      "provider": "anthropic",
      "kind": "llm",
      "capabilities": {
        "tools": true, "structured_output": true, "cached_input": true, "reasoning": true,
        "diarization": false, "keywords": false, "noise_reduction": false,
        "word_timestamps": false, "word_timings": false, "character_timings": false
      },
      "regions": ["us-east-1"]
    },
    {
      "id": "sonic-3.5",
      "provider": "cartesia",
      "kind": "tts",
      "capabilities": {
        "tools": false, "structured_output": false, "cached_input": false, "reasoning": false,
        "diarization": false, "keywords": false, "noise_reduction": false,
        "word_timestamps": false, "word_timings": true, "character_timings": false
      },
      "regions": ["us-east-1"]
    }
  ],
  "catalog_digest": "sha256:..."
}
```

<ResponseField name="kind" type="string">
  `stt`, `tts`, or `llm`.
</ResponseField>

<ResponseField name="capabilities" type="object">
  Advisory capability flags. Every entry carries every flag, so the ones that
  do not apply to a model's `kind` are present and `false`. LLM entries set
  `tools`, `structured_output`, `cached_input`, `reasoning`. STT entries set
  `diarization`, `keywords`, `noise_reduction`, and `word_timestamps` — what
  the route can be asked for in the
  [`options` object](/relay/stt/batch#the-options-object); a
  request asking for a capability the route lacks is refused
  `capability_unsupported` rather than served without it. TTS entries set
  `word_timings` and `character_timings` — see
  [word timings](/relay/tts/streaming#word-timings). These two report what a
  route emits on its own rather than something you can ask for: `word_timings`
  means the route sends `utterance.timings`, and `character_timings` means its
  engine measures per character, which the Router groups into words before
  they reach you. A route with neither sends no timing frames, and no error.
</ResponseField>

<ResponseField name="regions" type="string[]">
  AWS region IDs naming **Speko Router locations** that can serve the model — not provider data-residency claims. The listing always reflects the region that served your request.
</ResponseField>

<ResponseField name="batch_audio_limits" type="object">
  Present on every STT entry from `GET /v1/models?path=batch`: the bounds of
  the model's pre-recorded API on one upload, as `max_pcm_bytes` (decoded PCM)
  and/or `max_duration_seconds`. The batch listing contains only models that
  have a pre-recorded route; realtime-only models (Deepgram Flux, Cartesia
  `ink-2`, OpenAI `gpt-live-transcribe`, Palabra) are omitted from it and are
  not candidates for transcription jobs.
</ResponseField>

<ResponseField name="catalog_digest" type="string">
  `sha256:` + 64 hex characters identifying the exact catalog release in effect.
</ResponseField>

Use `path=batch` when choosing a model for
[`POST /v1/stt/transcriptions`](/relay/stt/batch) or a
[transcription job](/relay/stt/jobs). On the synchronous endpoint automatic
routing applies the same `batch_audio_limits` and skips models that cannot
accept the parsed recording; jobs use them to plan chunks. These limits are
not returned for the default `path=stream` query.

## The live catalog [#the-live-catalog]

The catalog is dynamic. The authenticated `GET /v1/models` response and the dashboard's [Models page](https://platform.speko.ai/gateway/models) are the authoritative sources for currently available providers, model IDs, regions, and capabilities.

Representative entries include Deepgram speech recognition, Cartesia speech synthesis, and OpenAI or Anthropic language models. Do not copy those examples into allowlists: read the live catalog when validating a route or presenting model choices.

## Canary gating [#canary-gating]

Speko runs a scheduled canary in every region that exercises each route as an ordinary customer — a real transcription, a real synthesis, a real completion. A (region, provider, model) route is routable only while its **latest** probe is a pass that is recent enough; a newer failure always beats an older pass.

Consequences you can rely on:

* Models missing from `/v1/models` are not receiving auto-routed traffic in that region right now.
* The list is advisory and can be up to about 30 seconds stale; admission re-checks authoritatively, so a just-failed route may briefly still be listed and yet refuse work with [`no_eligible_route`-class errors](/relay/errors).
* Pinning an unlisted model with explicit routing does not bypass the health gate.


# Quickstart (/relay/quickstart)

Call Router with curl — transcribe, synthesize, and generate in five minutes.



## 1. Get an API key [#1-get-an-api-key]

Create a key in the dashboard's [Gateway keys](https://platform.speko.ai/gateway/keys) page and export it:

```bash
export SPEKO_API_KEY=sk_speko_...
```

## 2. List routable models [#2-list-routable-models]

```bash
curl -s https://router.speko.dev/v1/models \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

```json
{
  "models": [
    {
      "id": "deepgram:flux-general-en",
      "provider": "deepgram",
      "kind": "stt",
      "capabilities": { "tools": false, "structured_output": false, "cached_input": false, "reasoning": false },
      "regions": ["us-east-1"]
    }
  ],
  "catalog_digest": "sha256:..."
}
```

## 3. Transcribe an audio file [#3-transcribe-an-audio-file]

The request is multipart with exactly two parts, `request` then `audio`, in that order:

```bash
curl -s https://router.speko.dev/v1/stt/transcriptions \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request={"routing":{"mode":"auto","objective":"balanced"},"language":"en"};type=application/json' \
  -F 'audio=@meeting.wav;type=audio/wav'
```

```json
{
  "text": "Good morning everyone, let's get started.",
  "segments": [{ "text": "Good morning everyone, let's get started.", "start_ms": 0, "end_ms": 2900 }],
  "route": { "provider": "deepgram", "model": "flux-general-en", "region": "us-east-1", "attempt_id": "ratt_..." },
  "usage": { "duration_ms": 3000 }
}
```

## 4. Synthesize speech [#4-synthesize-speech]

The response body is raw audio; the character count you were metered for comes back in the `Speko-Usage-Characters` header.

```bash
curl -s https://router.speko.dev/v1/tts/speech \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": { "mode": "auto", "objective": "latency" },
    "input": "Your table is ready.",
    "audio": { "encoding": "pcm_s16le", "sample_rate_hz": 24000, "channels": 1 }
  }' \
  --output speech.pcm
```

## 5. Generate a model response [#5-generate-a-model-response]

`max_output_tokens` is required — an unbounded generation cannot be priced up front.

```bash
curl -s https://router.speko.dev/v1/llm/responses \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": { "mode": "explicit", "provider": "anthropic", "model": "claude-sonnet-5" },
    "input": [
      { "type": "message", "role": "user", "content": [{ "type": "text", "text": "Say hello in French." }] }
    ],
    "max_output_tokens": 100
  }'
```

```json
{
  "id": "resp_rreq_...",
  "route": { "provider": "anthropic", "model": "claude-sonnet-5", "region": "us-east-1", "attempt_id": "ratt_..." },
  "output": [
    { "type": "message", "role": "assistant", "content": [{ "type": "text", "text": "Bonjour !" }] }
  ],
  "stop_reason": "stop",
  "usage": { "input_tokens": 21, "output_tokens": 5 }
}
```

## Next [#next]

* [Routing](/relay/routing) — objectives, allow/deny lists, and explicit provider pinning
* [Bring your own provider keys](/relay/byok) — provider billing and credential-source-preserving failover
* [Streaming STT](/relay/stt/streaming) and [streaming TTS](/relay/tts/streaming) over WebSocket
* [Errors](/relay/errors) — the closed error-code set and retry guidance


# Routing (/relay/routing)

The routing object, objectives, provider pinning, and automatic failover.



Every Router request carries a `routing` object that is a **closed tagged union** on `mode`. There are exactly two modes, and fields from one mode are rejected — never silently ignored — in the other.

## Auto mode [#auto-mode]

Speko picks the provider, ranked for your objective and filtered by route health:

```json
{
  "routing": {
    "mode": "auto",
    "objective": "latency",
    "allow_providers": ["deepgram", "cartesia"],
    "deny_providers": []
  }
}
```

<ParamField name="objective" type="string">
  One of `balanced`, `quality`, `latency`, `cost`. Defaults to `balanced` when omitted.
</ParamField>

<ParamField name="allow_providers" type="string[]">
  Optional. Restricts candidates to these provider IDs in preference order.
  Router tries the first healthy, capable provider first and falls through the
  ordered list before returning an error. Entries must be non-blank.
</ParamField>

<ParamField name="deny_providers" type="string[]">
  Optional. Excludes these provider IDs from consideration.
</ParamField>

Omitting the routing object entirely means `{"mode": "auto", "objective": "balanced"}`. A **partially specified** routing object is rejected rather than defaulted, and a present-but-empty list such as `"allow_providers": []` counts as having named the field.

## Explicit mode [#explicit-mode]

You pin the exact provider and model; Speko does not substitute:

```json
{
  "routing": { "mode": "explicit", "provider": "openai", "model": "gpt-5.2" }
}
```

Both `provider` and `model` are required. `objective`, `allow_providers`, and `deny_providers` are rejected in explicit mode — including as empty arrays.

## The route in the response [#the-route-in-the-response]

Every successful response reports what actually served it, in the `route` object and mirrored in response headers:

```json
{ "provider": "deepgram", "model": "flux-general-en", "region": "us-east-1", "attempt_id": "ratt_..." }
```

## Automatic failover [#automatic-failover]

In **auto mode**, if the chosen provider fails **before the first byte of output**, the Router transparently retries on the next-ranked provider:

* Your `Speko-Request-ID` stays the same; a new `Speko-Attempt-ID` is minted.
* Prices are frozen per attempt, so the new attempt is priced at its own provider's rates.
* Nothing fails over after output has started — a mid-stream provider failure terminates the stream with a [`provider_error`](/relay/errors).
* **Explicit mode never falls back.** If your pinned provider fails, you get the error.

Failover also preserves who supplies the credential. A request using one of [your provider keys](/relay/byok) can retry only on another BYOK-configured provider; a managed request retries only on managed providers. Router never changes the billing source during a request.

On LLM streams, the `response.created` event is deliberately *not* counted as output, so failover can still happen after you have seen it.

## What auto mode considers [#what-auto-mode-considers]

Candidates are ranked per objective, then filtered by your allow/deny lists, by [canary route health](/relay/models), and by capability requirements (for example, `tools`, `structured_output`, or the requested `reasoning_effort` on LLM requests). If filters empty the candidate set:

* `400 capability_unsupported` — routable providers existed, but none can do what the request needs.
* `503 provider_unavailable` (retryable) — nothing is currently routable.

Speech rankings come from Speko's continuously measured quality/latency boards. LLM rankings are launch-pinned editorial orderings per objective — quality favors frontier models, latency favors fast inference providers, cost favors the cheapest capable entries.


# Usage (/relay/usage)

The usage object, how each kind is metered, and how budgets behave on streams.



## The usage object [#the-usage-object]

Successful responses and stream `usage.updated` / terminal frames carry a usage object. All fields are optional and never negative:

```json
{
  "duration_ms": 61000,
  "characters": 512,
  "input_tokens": 1800,
  "cached_input_tokens": 900,
  "output_tokens": 240,
  "reasoning_tokens": 60
}
```

| Field                 | Kind | Meaning                                 |
| --------------------- | ---- | --------------------------------------- |
| `duration_ms`         | STT  | Audio duration transcribed              |
| `characters`          | TTS  | Characters accepted for synthesis       |
| `input_tokens`        | LLM  | Fresh (uncached) input tokens           |
| `cached_input_tokens` | LLM  | Input tokens served from provider cache |
| `output_tokens`       | LLM  | Visible output tokens                   |
| `reasoning_tokens`    | LLM  | Hidden reasoning tokens                 |

When a provider reports split usage, the lines are mutually exclusive: `cached_input_tokens` are not double-counted inside `input_tokens`, and `reasoning_tokens` are not inside `output_tokens`. If a provider does not report a reasoning split, its inclusive output count remains in `output_tokens`; Router does not estimate hidden tokens.

## How each kind meters [#how-each-kind-meters]

* **STT** — parsed audio duration, rounded up to whole seconds. Derived from the audio itself, never from a caller declaration.
* **TTS** — characters at the moment input is **accepted**. One-shot requests accept the whole `input`; streaming sessions accept per `input.append`. Cancelling later does not refund accepted characters.
* **LLM** — provider-reported token counts, normalized where the provider exposes a cache or reasoning split. `max_output_tokens` bounds reasoning plus visible output.

## Admission ceilings vs. billed usage [#admission-ceilings-vs-billed-usage]

Before work starts, Speko computes a conservative **ceiling** (the most the request could cost) and admits the request against your credit. You are billed for **reported usage**, not the ceiling. For LLM requests the output ceiling is exactly your `max_output_tokens` — another reason it is required.

## Budgets on streams [#budgets-on-streams]

Long-lived streams extend their budgets as they run:

* Streaming **TTS** admits an initial character budget and tops it up transparently as you append text.
* Streaming **STT** admits an initial duration slice and renews it while audio flows.

When an extension is refused — credit exhausted, or the session's lease could not be renewed — the stream terminates with a final `error` frame carrying `budget_exhausted` or `lease_expired`. These two codes never appear as HTTP statuses; they exist only on already-established streams.

## Correlating with your invoice [#correlating-with-your-invoice]

Every response and stream carries `Speko-Request-ID` and per-attempt `Speko-Attempt-ID` values. Usage is recorded per attempt with prices frozen at attempt start, so a [failover](/relay/routing#automatic-failover) mid-request produces attempts that are individually priced and individually visible in the dashboard's activity view.

For a [BYOK route](/relay/byok), the upstream provider bills your account and Speko does not charge provider usage for that attempt.


# callControl (/sdk/call-control)

Programmable human calling: dial, answer, and control browser + PSTN call legs through /v1/voice.



`speko.callControl` drives calls between **people** — your team on browser softphones, everyone else on the PSTN. It is modeled on Telnyx Call Control: every leg has an opaque `controlId`, and every verb is addressed to that handle. This page is the method reference; read the [human calling guide](/docs/guides/human-calling) for the full flows, the presence wire protocol, and the divergences from Telnyx worth knowing.

<Callout type="info">
  Human calling is in early access, enabled per workspace. Calls fail with `HUMAN_CALLING_DISABLED` (HTTP 503) until it is enabled for your organization.
</Callout>

`speko.voice.dial()` is a different product and is unchanged — it dials an **AI agent** out over the same telephony gateway.

## Authentication [#authentication]

Use your organization API key and configure the broker identity once when constructing the SDK. `dial`, `join`, `register`, `heartbeat`, `setStatus`, and `presenceToken` automatically send that `brokerId`.

```ts
const speko = new Speko({
  apiKey: process.env.SPEKO_API_KEY!,
  brokerId: 'broker-42',
});
```

The command surface and org-wide reads use the API key but do not send a broker id.

## Calls [#calls]

### `dial(params)` [#dialparams]

Place an outbound PSTN call. Resolves as soon as the call exists — the PSTN leg is still `initiating`/`ringing`; watch `events()` for `call.answered`. The browser leg belongs to the configured broker.

```ts
const { call, join } = await speko.callControl.dial({ to: '+12015551234' });
const mine = call.legs.find((leg) => leg.kind === 'browser')!;
// Connect your softphone with `join` immediately — you must be in the room
// before the far end answers, or the first moments are silence.
```

| Field      | Type                       | Description                                                                                     |
| ---------- | -------------------------- | ----------------------------------------------------------------------------------------------- |
| `to`       | `string`                   | Destination, E.164.                                                                             |
| `from`     | `string?`                  | Caller ID. Must be a number your org owns; defaults to the org's first outbound-capable number. |
| `metadata` | `Record<string, unknown>?` | Free-form, surfaced on the call resource.                                                       |

Returns `{ call: CallResource, join: CallJoinCredentials }` — the call with both legs attached, plus room credentials for your own browser leg.

### `get(callId)` / `list(params?)` / `events(callId)` [#getcallid--listparams--eventscallid]

```ts
const call = await speko.callControl.get('call_123');
const { calls } = await speko.callControl.list({ status: 'active', limit: 50 });
const { events } = await speko.callControl.events('call_123'); // oldest first
```

`list` filters (`status`, `direction`, `brokerId`, `limit` ≤ 200) are AND-ed and validated — an unknown `status` is a `VALIDATION_ERROR`, not an ignored filter. `events` is the durable record of the call; webhook deliveries for the same events are one-shot.

### `join(controlId)` [#joincontrolid]

Mint room credentials for one of the configured broker's browser legs. Tokens are short-lived and minted per join; re-join on reconnect instead of caching. A leg belonging to another broker returns `NOT_FOUND`, deliberately indistinguishable from a leg that does not exist.

## Commands [#commands]

Each command returns `CallCommandResult` — `{ leg, noop? }`, the leg's post-command state, so you never re-read to learn what you just did. Errors carry stable codes on `SpekoApiError.code`, exported as `VOICE_ERROR_CODES`.

| Method                                  | Notes                                                                                                                                                                                                                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `answer(controlId)`                     | Answer your ringing leg. Join the room first.                                                                                                                                                                                                                                        |
| `hangup(controlId, { reason? })`        | Drops this leg; the call ends when no live legs remain. `reason` becomes the leg's `endReason`.                                                                                                                                                                                      |
| `mute(controlId)` / `unmute(controlId)` | Stops/resumes this leg's outgoing audio. A muted leg still hears the call.                                                                                                                                                                                                           |
| `hold(controlId)` / `unhold(controlId)` | Parks/resumes the leg. **Held parties hear silence** — there is no hold-music source yet.                                                                                                                                                                                            |
| `dtmf(controlId, { digits })`           | Send tones toward a **`pstn` leg**. `0-9 * # , w`, ≤ 64 chars. Fails unless a browser leg is connected to relay the tones — see the [guide](/docs/guides/human-calling#dtmf-needs-a-connected-softphone).                                                                            |
| `bridge(controlId, { bridgeTo })`       | Pulls this leg into another live leg's conversation. `bridgeTo` is a `controlId`, not a call id.                                                                                                                                                                                     |
| `transfer(controlId, { to, mode })`     | `to`: E.164 or another leg's `controlId`. `blind` hands off and drops your leg (`call.transfer.completed`/`failed`); `warm` opens a consultation room that **you** complete with `bridge` (`call.bridged`). The far end is left un-held — `hold` them first if the UI should say so. |

## Presence [#presence]

All presence methods act as the `brokerId` configured on the SDK instance.

```ts
import { PRESENCE_STALE_AFTER_MS } from '@spekoai/sdk';

await speko.callControl.register(); // = setStatus('available')
const presence = await speko.callControl.presenceToken(); // { token, url, identity, roomName, expiresAt }
setInterval(() => speko.callControl.heartbeat(), PRESENCE_STALE_AFTER_MS / 3);
```

| Method              | Notes                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `presenceToken()`   | Registers **and** mints presence-room credentials in one round trip. Connect with `livekit-client`; ring offers and live call events arrive as JSON data messages on topic `speko.human_call`. |
| `heartbeat()`       | Keep-alive. Presence goes stale after `PRESENCE_STALE_AFTER_MS` (90 s) and a stale broker is skipped by inbound routing regardless of status.                                                  |
| `register()`        | Mark yourself `available`. Not a SIP registration — reachability comes from the open presence connection + heartbeat.                                                                          |
| `setStatus(status)` | `'available' \| 'busy' \| 'away' \| 'offline'`. `busy`/`away` divert inbound while staying online.                                                                                             |

The org-wide roster has no SDK method yet — read `GET /v1/voice/presence` directly (works with an API key): `{ brokers: BrokerPresenceResource[] }`, each with a computed `reachable`.

## Types and constants [#types-and-constants]

The contract ships with the SDK: `CallResource`, `CallLegResource`, `CallEventResource`, `CallJoinCredentials`, `CallCommandResult`, `BrokerPresenceResource`, `PresenceMessage` (`RingOffer | CallEventNotice`), plus `CALL_COMMANDS`, `CALL_EVENTS`, `DTMF_PATTERN`, `PRESENCE_STALE_AFTER_MS`, and `VOICE_ERROR_CODES` for branching on error codes without string-matching prose.


# callbacks (/sdk/callbacks)

Scheduled callback resources created from call analysis.



`speko.callbacks` lists and controls scheduled callbacks. Callbacks are usually created by post-call analysis when the caller requested a follow-up.

```ts
const { callbacks } = await speko.callbacks.list({ status: 'scheduled' });

await speko.callbacks.dispatch(callbacks[0]!.id);
```

## Methods [#methods]

| Method                        | Description                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------- |
| `list(params?)`               | List scheduled callbacks. Filter by `status`, `sourceSessionId`, and `limit`. |
| `get(callbackId)`             | Fetch one callback.                                                           |
| `cancel(callbackId, params?)` | Cancel a callback with an optional reason.                                    |
| `dispatch(callbackId)`        | Dispatch a callback immediately.                                              |

## ScheduledCallback [#scheduledcallback]

| Field                | Type                                                                      | Description                                    |
| -------------------- | ------------------------------------------------------------------------- | ---------------------------------------------- |
| `id`                 | `string`                                                                  | Callback id.                                   |
| `source_session_id`  | `string \| null`                                                          | Call that requested the callback.              |
| `created_session_id` | `string \| null`                                                          | Outbound call session created when dispatched. |
| `agent_id`           | `string \| null`                                                          | Agent to run.                                  |
| `phone_number_id`    | `string \| null`                                                          | Caller ID phone-number row.                    |
| `to_number`          | `string`                                                                  | Destination number.                            |
| `from_number`        | `string \| null`                                                          | Caller ID.                                     |
| `scheduled_at`       | `string`                                                                  | ISO timestamp.                                 |
| `status`             | `'scheduled' \| 'dispatching' \| 'dispatched' \| 'cancelled' \| 'failed'` | Callback state.                                |
| `pipeline_config`    | `Record<string, unknown>`                                                 | Resolved call pipeline.                        |
| `metadata`           | `Record<string, unknown>`                                                 | Free-form metadata and analysis context.       |


# calls (/sdk/calls)

Inspect calls, reports, events, recordings, and transfers.



`speko.calls` exposes operational data and live transfer controls for voice calls.

```ts
const detail = await speko.calls.get('call_123');
const { events } = await speko.calls.events('call_123');
const recording = await speko.calls.recording('call_123');
```

The call id is the Speko voice session id returned by `speko.voice.dial()` and surfaced in inbound call metadata and webhooks.

## Methods [#methods]

| Method                                              | Description                                                                            |
| --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `get(callId)`                                       | Fetch call detail, transcript, report, and transfer attempts.                          |
| `events(callId)`                                    | List lifecycle, SIP, and transfer events.                                              |
| `report(callId)`                                    | Fetch the post-call report.                                                            |
| `finalizeReport(callId, params?)`                   | Run or rerun analysis. New integrations redeliver through `speko.webhooks.deliveries`. |
| `recording(callId)`                                 | Return a signed recording URL.                                                         |
| `blindTransfer(callId, params)`                     | Transfer the active SIP participant directly.                                          |
| `warmTransfer(callId, params)`                      | Start a consultative transfer with optional sequential destinations.                   |
| `completeWarmTransfer(callId, transferId, params?)` | Bridge the screened recipient into the original room.                                  |
| `cancelWarmTransfer(callId, transferId, params?)`   | Cancel a warm transfer, optionally trying the next destination.                        |

## Agent call history [#agent-call-history]

Call listing is scoped through agents:

```ts
const page = await speko.agents.listCalls('agent_123', { limit: 25 });

if (page.next_cursor) {
  await speko.agents.listCalls('agent_123', { cursor: page.next_cursor });
}
```

## Warm transfer [#warm-transfer]

```ts
const transfer = await speko.calls.warmTransfer('call_123', {
  from: '+12015550199',
  destinations: [
    { to: '+12015551234', label: 'Front desk' },
    { to: '+12015554321', label: 'Overflow' },
  ],
  screeningPrompt: 'Confirm the recipient can help before bridging.',
  fallback: { strategy: 'take_message' },
  voicemailDetection: { mode: 'agent', timeoutSeconds: 10 },
});
```

Warm transfers return the active transfer plus `routing_attempts`. Cancelling with `tryNext: true` asks the server to continue with the next destination when one exists.

## Reports and webhooks [#reports-and-webhooks]

`report(callId)` returns the finalized post-call report when available: summary, outcome, structured data, transcript entries, cost breakdown, artifacts, metadata, scheduled callback context, and canonical per-endpoint `webhook_deliveries`. `finalizeReport(callId, { forceAnalysis: true })` reruns analysis. Use `speko.webhooks.deliveries` to inspect and redeliver a specific endpoint delivery; `retryWebhook` and the singular post-call webhook fields remain deprecated aggregate compatibility options.

Use `events(callId)` for the durable event stream. It includes Speko, LiveKit, Telnyx, SIP status, failure, and transfer events, which is the closest equivalent to a carrier status timeline.


# complete (/sdk/complete)

POST /v1/complete — LLM completion with automatic provider routing.



Run an LLM completion. The router picks the best LLM provider for your intent and fails over automatically.

```ts
const { text, provider } = await speko.complete({
  messages: [{ role: 'user', content: 'Hi!' }],
  intent: { language: 'en' },
});
```

## Signature [#signature]

```ts
speko.complete(
  params: CompleteParams,
  abortSignal?: AbortSignal,
): Promise<CompleteResult>

speko.completeStream(
  params: CompleteParams,
  abortSignal?: AbortSignal,
): AsyncIterable<CompleteStreamEvent>
```

## Parameters [#parameters]

### `params: CompleteParams` [#params-completeparams]

| Field               | Type                                                             | Description                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`          | `ChatMessage[]`                                                  | Conversation history. Roles: `system`, `user`, `assistant`, `tool`.                                                                         |
| `intent`            | `RoutingIntent`                                                  | `language`, optional `region` and `optimizeFor`.                                                                                            |
| `systemPrompt`      | `string?`                                                        | Shortcut for a leading system message. Providers that distinguish the system channel use it natively; others fold it into the message list. |
| `temperature`       | `number?`                                                        | Forwarded to the provider. Defaults to the provider's default.                                                                              |
| `maxTokens`         | `number?`                                                        | Max completion tokens. Defaults to the provider's default.                                                                                  |
| `reasoningEffort`   | `'none' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'xhigh'?` | OpenAI reasoning-model effort override. Defaults are tuned from `intent.optimizeFor`.                                                       |
| `constraints`       | `PipelineConstraints?`                                           | Allow-list constraints.                                                                                                                     |
| `tools`             | `ChatTool[]?`                                                    | JSON Schema tool definitions exposed to the model.                                                                                          |
| `toolChoice`        | `ChatToolChoice?`                                                | `auto`, `none`, `required`, or a specific function name.                                                                                    |
| `parallelToolCalls` | `boolean?`                                                       | Provider hint for whether multiple tool calls may be emitted in one turn.                                                                   |
| `maxToolHops`       | `number?`                                                        | Server-side hop cap for webhook or builtin tools. Defaults to 8.                                                                            |

### `ChatMessage` [#chatmessage]

```ts
interface ChatMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  toolCalls?: ChatToolCall[];
  toolCallId?: string;
  isError?: boolean;
}

interface ChatToolCall {
  id: string;
  name: string;
  args: string;
}

interface ChatTool {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
  executionMode?: 'inline' | 'webhook' | 'builtin' | 'integration';
  source?: ChatToolSource; // required for webhook, builtin, and integration
}
```

### `abortSignal?: AbortSignal` [#abortsignal-abortsignal]

Cancel an in-flight request.

## Returns [#returns]

### `CompleteResult` [#completeresult]

| Field                    | Type              | Description                                                               |
| ------------------------ | ----------------- | ------------------------------------------------------------------------- |
| `text`                   | `string`          | Assistant reply.                                                          |
| `provider`               | `string`          | Upstream LLM provider (e.g. `openai`, `anthropic`, `groq`).               |
| `model`                  | `string`          | Provider-specific model id.                                               |
| `usage.promptTokens`     | `number`          | Prompt token count.                                                       |
| `usage.completionTokens` | `number`          | Completion token count.                                                   |
| `failoverCount`          | `number`          | Providers tried before this one succeeded.                                |
| `scoresRunId`            | `string \| null`  | Scoring run id that selected this provider.                               |
| `toolCalls`              | `ChatToolCall[]?` | Tool calls emitted by the assistant when inline tool execution is needed. |

## Streaming [#streaming]

The wire response is `text/event-stream` with `meta`, `delta`, `tool_call`,
`server_tool_call`, `done`, and `error` events. `speko.complete()` consumes that
stream and returns the final `CompleteResult`; use `speko.completeStream()` to
render deltas or tool-call progress as it arrives.

## Tool execution [#tool-execution]

Tools can run inline in your worker, through Speko-managed webhooks, as builtins, or as org-installed integration actions. Omitting `executionMode` preserves the inline behavior: the model's tool calls return in `toolCalls`, and your app adds `role: 'tool'` messages before calling `complete()` again. Webhook, builtin, and integration tools are executed by Speko server-side and may emit `server_tool_call` streaming events before the final response. Server-executed kinds also need `source` — the webhook URL and secret ref, the builtin name, or the integration's `installationId`/`appKey`/`actionKey`; see [`ChatToolSource`](/sdk/types#complete).

## Example: multi-turn [#example-multi-turn]

```ts
const messages: ChatMessage[] = [
  { role: 'system', content: 'You are a concise voice assistant.' },
  { role: 'user',   content: 'Book me an appointment for Tuesday.' },
];

const first = await speko.complete({
  messages,
  intent: { language: 'en' },
  temperature: 0.3,
  maxTokens: 200,
});

messages.push({ role: 'assistant', content: first.text });
messages.push({ role: 'user',      content: '3pm, with Dr. Chen.' });

const second = await speko.complete({
  messages,
  intent: { language: 'en' },
});
```

## Example: pin a provider [#example-pin-a-provider]

```ts
await speko.complete({
  messages: [...],
  intent: { language: 'en' },
  constraints: { allowedProviders: { llm: ['anthropic'] } },
});
```


# credits (/sdk/credits)

Prepaid balance and append-only ledger.



Query the organization's prepaid credit balance and walk the ledger of every credit movement. Exposed via `speko.credits`.

Balances are returned in USD. Ledger amounts still use micro-USD strings because ledger entries are signed accounting units.

```ts
const { balanceUsd } = await speko.credits.getBalance();
if (balanceUsd < 0.5) showLowBalanceBanner();
```

## `speko.credits.getBalance()` [#spekocreditsgetbalance]

### Signature [#signature]

```ts
speko.credits.getBalance(): Promise<OrganizationBalance>
```

### Returns — `OrganizationBalance` [#returns--organizationbalance]

| Field        | Type     | Description                                  |
| ------------ | -------- | -------------------------------------------- |
| `balanceUsd` | `number` | Current prepaid balance in USD.              |
| `currency`   | `'USD'`  | Currency for `balanceUsd`.                   |
| `updatedAt`  | `string` | ISO-8601 timestamp of the last ledger event. |

## `speko.credits.getLedger(params?)` [#spekocreditsgetledgerparams]

Most-recent-first page of credit movements (grants, debits, topups, refunds, adjustments). Pass the previous response's `nextCursor` back as `cursor` to continue; `null` means the history is exhausted.

### Signature [#signature-1]

```ts
speko.credits.getLedger(
  params?: CreditLedgerQueryParams,
): Promise<CreditLedgerPage>
```

### `CreditLedgerQueryParams` [#creditledgerqueryparams]

| Field    | Type      | Description                                   |
| -------- | --------- | --------------------------------------------- |
| `limit`  | `number?` | Page size. Server default applies if omitted. |
| `cursor` | `string?` | `nextCursor` from a previous response.        |

### Returns — `CreditLedgerPage` [#returns--creditledgerpage]

| Field        | Type                  | Description                                              |
| ------------ | --------------------- | -------------------------------------------------------- |
| `entries`    | `CreditLedgerEntry[]` | Page contents.                                           |
| `nextCursor` | `string \| null`      | Pass back as `cursor` for the next page, `null` if done. |

### `CreditLedgerEntry` [#creditledgerentry]

| Field            | Type                                                        | Description                                                      |
| ---------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| `id`             | `string`                                                    | Ledger entry id.                                                 |
| `kind`           | `'grant' \| 'debit' \| 'topup' \| 'refund' \| 'adjustment'` | Movement type.                                                   |
| `amountMicroUsd` | `string`                                                    | Signed. Positive for grants/topups/refunds, negative for debits. |
| `metric`         | `string \| null`                                            | Metric when tied to a usage row.                                 |
| `provider`       | `string \| null`                                            | Upstream provider the debit was applied to.                      |
| `sessionId`      | `string \| null`                                            | Session the debit was applied against.                           |
| `createdAt`      | `string`                                                    | ISO-8601.                                                        |

## Example — paginate the ledger [#example--paginate-the-ledger]

```ts
let cursor: string | undefined = undefined;

do {
  const page = await speko.credits.getLedger({ limit: 50, cursor });
  for (const entry of page.entries) {
    console.log(entry.createdAt, entry.kind, entry.amountMicroUsd);
  }
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```


# Errors (/sdk/errors)

Exception classes thrown by @spekoai/sdk.



Every non-2xx API response is re-thrown as a typed error. Import from the package root:

```ts
import { SpekoApiError, SpekoAuthError, SpekoRateLimitError } from '@spekoai/sdk';
```

## `SpekoApiError` [#spekoapierror]

Base class for all API errors. Carries HTTP status plus a server-provided `code`.

```ts
class SpekoApiError extends Error {
  status: number;
  code: string;
}
```

Thrown on any non-2xx response that isn't a 401 or 429. `code` is parsed from the JSON body (`{ "error": "...", "code": "..." }`); falls back to `"UNKNOWN"` when the body isn't JSON.

## `SpekoAuthError` [#spekoautherror]

Thrown on HTTP 401. Extends `SpekoApiError` with `status: 401`, `code: 'AUTH_ERROR'`.

```ts
try {
  await speko.complete({ ... });
} catch (err) {
  if (err instanceof SpekoAuthError) {
    // Prompt the user to rotate their API key.
  }
}
```

## `SpekoRateLimitError` [#spekoratelimiterror]

Thrown on HTTP 429. Extends `SpekoApiError` with `code: 'RATE_LIMITED'` and a parsed `retryAfter` (seconds) from the `Retry-After` response header.

```ts
class SpekoRateLimitError extends SpekoApiError {
  retryAfter: number | null;
}
```

Example backoff:

```ts
async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn();
  } catch (err) {
    if (err instanceof SpekoRateLimitError) {
      const wait = (err.retryAfter ?? 1) * 1000;
      await new Promise((r) => setTimeout(r, wait));
      return fn();
    }
    throw err;
  }
}
```

## Timeouts and cancellation [#timeouts-and-cancellation]

When the internal timeout fires or an external `AbortSignal` is aborted, `fetch` rejects with a `DOMException` named `AbortError`. The SDK does **not** re-wrap these — callers can distinguish abort from API failure with a standard `instanceof` / `.name === 'AbortError'` check.


# @spekoai/sdk (/sdk/overview)

Official TypeScript SDK — one API, every voice provider.



`@spekoai/sdk` is the server-side TypeScript SDK for the Speko voice gateway. It wraps the one-shot proxy endpoints — `/v1/transcribe`, `/v1/synthesize`, `/v1/complete` — plus usage, credits, realtime S2S, outbound voice dialing, phone numbers, agents, registered tools, and knowledge bases. Speko benchmarks providers per `(language, region, optimizeFor)` and routes each STT, LLM, and TTS call to the best available option. Failover is handled server-side. You ship one integration; providers rotate without a code change.

## Install [#install]

```bash
npm install @spekoai/sdk
# or
pnpm add @spekoai/sdk
```

Runtime: Node 18+ (uses global `fetch` and `AbortController`). Also works in Bun, Deno, and any runtime with `fetch`.

## Quickstart [#quickstart]

```ts
import { Speko } from '@spekoai/sdk';
import { readFile } from 'node:fs/promises';

const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });

// Transcribe
const audio = await readFile('./call.wav');
const { text, provider, confidence } = await speko.transcribe(audio, {
  language: 'es-MX',
});

// Synthesize
const speech = await speko.synthesize('Hello world', {
  language: 'en',
});

// Complete
const { text: reply } = await speko.complete({
  messages: [{ role: 'user', content: 'Hi!' }],
  intent: { language: 'en' },
});
```

## What the router does [#what-the-router-does]

Every routed one-shot call takes a `RoutingIntent` (`language`, optional `region` and `optimizeFor`). Speko scores every provider for that intent against its continuously-updated benchmark set, picks the top-ranked one, and fails over to the next-best if the primary errors. Response headers (`X-Speko-Provider`, `X-Speko-Model`, `X-Speko-Failover-Count`, `X-Speko-Scores-Run-Id`) are surfaced on every result object so you can log what actually ran.

If you need to restrict the pool (for compliance, cost caps, or pinning a provider while debugging), pass `constraints.allowedProviders[modality]`. The router still ranks by score — it just picks the top-ranked candidate from your allow-list.

## Cancellation [#cancellation]

Every method accepts an optional `AbortSignal` as the last argument. The signal is composed with the client's timeout (30 s by default), so external cancellation wins whenever it fires first. Frameworks like `@spekoai/adapter-livekit` pass their own signals through when a session tears down mid-call.

## Errors [#errors]

All API failures throw `SpekoApiError` or one of its subclasses:

* `SpekoAuthError` — 401, bad or missing API key.
* `SpekoRateLimitError` — 429, carries `retryAfter` seconds parsed from `Retry-After`.
* `SpekoApiError` — any other non-2xx response. `status` and `code` are populated from the JSON body.

See [Errors](/sdk/errors) for details.

## Reference [#reference]

<Columns cols="2">
  <Card title="Speko client" icon="circle-dot" href="/sdk/speko-client">
    Constructor, options, concurrency, auth.
  </Card>

  <Card title="transcribe" icon="microphone" href="/sdk/transcribe">
    `POST /v1/transcribe`.
  </Card>

  <Card title="synthesize" icon="volume" href="/sdk/synthesize">
    `POST /v1/synthesize`.
  </Card>

  <Card title="complete" icon="brain" href="/sdk/complete">
    `POST /v1/complete`.
  </Card>

  <Card title="realtime" icon="waveform" href="/sdk/realtime">
    Provider-direct speech-to-speech sessions.
  </Card>

  <Card title="voice" icon="phone-call" href="/sdk/voice">
    Outbound phone calls.
  </Card>

  <Card title="phone numbers" icon="phone" href="/sdk/phone-numbers">
    Managed numbers, SIP imports, and business verification.
  </Card>

  <Card title="calls" icon="messages-square" href="/sdk/calls">
    Call detail, events, reports, recordings, and transfers.
  </Card>

  <Card title="callbacks" icon="calendar-clock" href="/sdk/callbacks">
    Scheduled follow-up calls.
  </Card>

  <Card title="usage" icon="chart-line" href="/sdk/usage">
    `GET /v1/usage`.
  </Card>

  <Card title="credits" icon="coin" href="/sdk/credits">
    Balance and ledger.
  </Card>

  <Card title="agents" icon="bot" href="/concepts/agents">
    Persisted voice personas and registered tools.
  </Card>

  <Card title="Types" icon="code" href="/sdk/types">
    Shared request / response types.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/sdk/errors">
    Exception classes.
  </Card>
</Columns>


# phone numbers (/sdk/phone-numbers)

Provision managed numbers, import SIP trunk numbers, and manage phone-number business verification.



`speko.phoneNumbers` manages caller IDs and inbound numbers for the authenticated organization.

```ts
const numbers = await speko.phoneNumbers.list();

const imported = await speko.phoneNumbers.importSipTrunk({
  e164: '+12015550199',
  sipConnectionInstallationId: '00000000-0000-4000-8000-000000000010',
  direction: 'both',
  agentId: 'agent_123',
});
```

Managed number purchase is the US-number path and requires phone-number business verification plus sufficient credits. For numbers you already own, or non-US carrier paths, import a SIP trunk number and link it to an agent.

Inbound routing is controlled by `direction`, `agentId`, and `dispatchMetadataTemplate`. A number that allows inbound calls must have either a linked agent or a dispatch metadata template. Linked agents hydrate the call prompt, routing intent, provider preferences, and tools; organization webhook endpoints resolve separately by the linked agent. Templates add static or token-substituted metadata.

## Methods [#methods]

| Method                     | Description                                                                  |
| -------------------------- | ---------------------------------------------------------------------------- |
| `list()`                   | List all organization phone numbers.                                         |
| `searchAvailable(params?)` | Search platform-managed numbers available to buy.                            |
| `get(id)`                  | Fetch one phone-number row.                                                  |
| `create(params)`           | Buy a managed number. Requires business verification and sufficient credits. |
| `importSipTrunk(params)`   | Register a customer-owned SIP-trunk number.                                  |
| `update(id, params)`       | Update direction, metadata template, label, or linked agent.                 |
| `delete(id)`               | Release or unregister a phone number.                                        |
| `getKyb()`                 | Read business verification state.                                            |
| `saveKybDraft(params)`     | Save a business verification draft.                                          |
| `submitKyb(params)`        | Submit business verification for review.                                     |

## PhoneNumberRow [#phonenumberrow]

| Field                                                       | Type                                | Description                                                                                                                                            |
| ----------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                                                        | `string`                            | Speko phone-number id.                                                                                                                                 |
| `e164`                                                      | `string`                            | E.164 phone number.                                                                                                                                    |
| `source`                                                    | `'managed' \| 'sip_trunk'`          | Platform-managed number or customer SIP-trunk number.                                                                                                  |
| `providerResourceId`                                        | `string \| null`                    | Platform-neutral managed provider id.                                                                                                                  |
| `sipConnectionInstallationId`                               | `string \| null`                    | Installed SIP connection used for productized SIP imports.                                                                                             |
| `sipProviderName`                                           | `string \| null`                    | Display label for the SIP provider/account.                                                                                                            |
| `direction`                                                 | `'inbound' \| 'outbound' \| 'both'` | Allowed call direction.                                                                                                                                |
| `agentId`                                                   | `string \| null`                    | Agent linked for inbound calls.                                                                                                                        |
| `dispatchMetadataTemplate`                                  | `Record<string, unknown> \| null`   | Optional template merged into inbound session metadata. Supports tokens such as `{{callerNumber}}`, `{{dialedNumber}}`, and `{{forwardedFromNumber}}`. |
| `setupStatus`                                               | `PhoneNumberSetupStatus`            | Readiness state for inbound/outbound use.                                                                                                              |
| `sms10dlcProfileId`, `smsCampaignId`, `smsAssignmentStatus` | nullable                            | SMS assignment state when applicable.                                                                                                                  |

Pass `null` to `update()` for `label`, `dispatchMetadataTemplate`, or `agentId` to clear them.

## Inbound forwarding [#inbound-forwarding]

When a carrier forwards a call, Speko attempts to normalize the original forwarding source from provider fields and SIP headers. The value is available as `forwardedFromNumber` in call metadata and as `forwarded_from_number` in pre-call webhooks.

## Business verification [#business-verification]

Managed phone-number purchases are gated by phone-number KYB.

```ts
const kyb = await speko.phoneNumbers.getKyb();

await speko.phoneNumbers.submitKyb({
  businessProfile: {
    legalName: 'Acme Inc.',
    displayName: 'Acme',
    entityType: 'Corporation',
    country: 'US',
    website: 'https://example.com',
    address: {
      street: '1 Market St',
      city: 'San Francisco',
      state: 'CA',
      postalCode: '94105',
      country: 'US',
    },
    useCase: 'Customer support calls and appointment reminders.',
    expectedUsage: '500 calls per month in the US.',
  },
  authorizedRepresentative: {
    name: 'Ava Martinez',
    title: 'Operations Lead',
    email: 'ava@example.com',
    phone: '+12015551234',
  },
  attestationAccepted: true,
});
```


# realtime (/sdk/realtime)

Provider-direct speech-to-speech with OpenAI Realtime, Gemini Live, and xAI Grok Voice.



Open a speech-to-speech (S2S) session. `speko.realtime.connect()` reserves a Speko entitlement and mints a short-lived provider credential via `POST /v1/sessions`, then connects directly to OpenAI Realtime, Gemini Live, or xAI Grok Voice. Audio never traverses a Speko media proxy.

<Info>
  Use this low-level resource only in a trusted runtime because it creates the session with your Speko API key. Browser apps should mint on their backend and pass the response to [`@spekoai/client`](/client/realtime-voice-conversation). OpenAI uses WebRTC; Gemini Live and xAI use WebSockets.
</Info>

```ts
import { Speko } from '@spekoai/sdk';

const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });

const session = await speko.realtime.connect({
  provider: 'openai',
  model: 'gpt-realtime-2.1',
  agentId: 'agent_123',
  webhookTags: { environment: 'production' },
});

session.on((frame) => {
  if (frame.type === 'audio') play(frame.pcm);
  else if (frame.type === 'transcript') console.log(frame.role, frame.text);
});

session.sendAudio(pcm16Chunk);
// ... end of user turn
session.commit();
```

## `speko.realtime.connect(params)` [#spekorealtimeconnectparams]

### Signature [#signature]

```ts
speko.realtime.connect(
  params: RealtimeConnectParams,
): Promise<RealtimeSessionHandle>
```

### `RealtimeConnectParams` [#realtimeconnectparams]

| Field              | Type                            | Description                                                                                                      |
| ------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `provider`         | `'openai' \| 'google' \| 'xai'` | S2S provider.                                                                                                    |
| `model`            | `string`                        | Provider-specific model id, such as `gpt-realtime-2.1`, `gemini-3.1-flash-live-preview`, or `grok-voice-latest`. |
| `voice`            | `string?`                       | Voice id override — interpreted per provider.                                                                    |
| `systemPrompt`     | `string?`                       | Initial system instruction.                                                                                      |
| `temperature`      | `number?`                       |                                                                                                                  |
| `inputSampleRate`  | `16000 \| 24000?`               | PCM rate you'll be sending.                                                                                      |
| `outputSampleRate` | `16000 \| 24000?`               | PCM rate you want back.                                                                                          |
| `tools`            | `RealtimeToolSpec[]?`           | Tool definitions the assistant may call.                                                                         |
| `agentId`          | `string?`                       | Agent used for workspace webhook routing.                                                                        |
| `webhookTags`      | `Record<string, string>?`       | Case-sensitive workspace webhook routing tags; requires `agentId`.                                               |
| `metadata`         | `Record<string, unknown>?`      | Free-form metadata attached to the session record.                                                               |
| `ttlSeconds`       | `number?`                       | Requested maximum session duration; the returned entitlement may impose a lower cap.                             |
| `idempotencyKey`   | `string?`                       | Stable bootstrap key to reuse after an ambiguous timeout. Generated when omitted.                                |

## `RealtimeSessionHandle` [#realtimesessionhandle]

| Property           | Type             | Description                                  |
| ------------------ | ---------------- | -------------------------------------------- |
| `sessionId`        | `string`         | Server-assigned session id.                  |
| `expiresAt`        | `string`         | ISO-8601 expiry of the delegated credential. |
| `inputSampleRate`  | `16000 \| 24000` | PCM rate the session accepts.                |
| `outputSampleRate` | `16000 \| 24000` | PCM rate the session returns.                |

### Methods [#methods]

| Method                                 | Description                                                 |
| -------------------------------------- | ----------------------------------------------------------- |
| `sendAudio(pcm: Uint8Array): void`     | Send a PCM16 audio chunk directly to the selected provider. |
| `commit(): void`                       | Signal an end-of-user-turn to the provider.                 |
| `interrupt(): void`                    | Cancel the assistant's in-flight response.                  |
| `sendToolResult(callId, output): void` | Return the result of a previously-issued `tool_call`.       |
| `on(handler): () => void`              | Subscribe to frames. Returns an unsubscribe callback.       |
| `close(code?, reason?): void`          | Close the socket. Idempotent.                               |

### `RealtimeFrame` variants [#realtimeframe-variants]

```ts
type RealtimeFrame =
  | { type: 'ready'; inputSampleRate: 16000 | 24000; outputSampleRate: 16000 | 24000 }
  | { type: 'audio'; pcm: Uint8Array; sampleRate: number }
  | { type: 'transcript'; role: 'user' | 'assistant'; text: string; final: boolean }
  | { type: 'tool_call'; callId: string; name: string; arguments: string }
  | { type: 'usage'; inputAudioTokens: number; outputAudioTokens: number }
  | { type: 'interruption'; at: 'user' | 'assistant' }
  | { type: 'server_tool_call'; id: string; name: string; status: 'started' | 'completed' | 'failed' }
  | { type: 'error'; code: string; message: string }
  | { type: 'close'; code: number; reason: string };
```

## Example — tool calls [#example--tool-calls]

```ts
const session = await speko.realtime.connect({
  provider: 'openai',
  model: 'gpt-realtime-2.1',
  tools: [
    {
      name: 'get_weather',
      description: 'Current weather for a city.',
      parameters: {
        type: 'object',
        properties: { city: { type: 'string' } },
        required: ['city'],
      },
    },
  ],
});

session.on(async (frame) => {
  if (frame.type === 'tool_call' && frame.name === 'get_weather') {
    const { city } = JSON.parse(frame.arguments);
    const result = await fetchWeather(city);
    session.sendToolResult(frame.callId, result);
  }
});
```

## Transport notes [#transport-notes]

* **Provider authentication.** OpenAI uses its ephemeral bearer credential during WebRTC setup; xAI uses its delegated credential as a WebSocket subprotocol; Gemini Live uses its scoped token on the provider URL.
* **Runtime support.** OpenAI requires WebRTC and Web Audio globals. Gemini Live and xAI require a `WebSocket` global; Node 22 can provide one with `globalThis.WebSocket = (await import('ws')).WebSocket;`.
* **WebSocket audio.** For Gemini Live and xAI, the SDK forces `binaryType = 'arraybuffer'`; normalized inbound audio is emitted as `Uint8Array`.
* **Missing PCM.** Until you call `sendAudio`, the provider sees no user input. Browser applications should normally use `@spekoai/client`, which owns microphone capture and playback.


# SMS (/sdk/sms)

Send, schedule, batch, and manage compliant SMS with the TypeScript SDK.



The SDK exposes the complete messaging API under `speko.sms`:

```ts
const message = await speko.sms.messages.send({
  from_phone_number_id: '8f0e9a96-...',
  to: '+12025550123',
  text: 'Acme: your appointment is confirmed.',
  recipient_timezone: 'America/New_York',
  idempotencyKey: 'appointment-982-confirmation',
});

const batch = await speko.sms.batches.create({
  from_phone_number_id: '8f0e9a96-...',
  recipients: [
    {
      to: '+12025550123',
      text: 'Reminder',
      recipient_timezone: 'America/New_York',
    },
  ],
  idempotencyKey: 'reminders-2026-09-01',
});
```

Use `messages.list/get/cancel`, `batches.get/messages/cancel`, `conversations.list/get/messages/send/update/markRead/addNote/redact`, `consents.list/create/import/revoke`, `suppressions.list`, and `settings.get/update`.

Live events are an async iterator:

```ts
for await (const event of speko.sms.stream({ signal: abortController.signal })) {
  console.log(event.event, event.message_id, event.status);
}
```


# Speko client (/sdk/speko-client)

Construct the SDK client and configure transport options.



The `Speko` class is the single entry point. Construct it once per process and reuse it — HTTP keep-alive, auth headers, and timeout state are all bound to the instance.

```ts
import { Speko } from '@spekoai/sdk';

const speko = new Speko({
  apiKey: process.env.SPEKO_API_KEY!,
  baseUrl: 'https://api.speko.dev', // optional
  timeout: 30_000, // optional, ms
});
```

## `new Speko(options)` [#new-spekooptions]

### `SpekoClientOptions` [#spekoclientoptions]

| Field     | Type      | Default                 | Description                                                                                                    |
| --------- | --------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `apiKey`  | `string`  | — (required)            | API key. Get one at [platform.speko.ai/agents/keys](https://platform.speko.ai/agents/keys). Throws if missing. |
| `baseUrl` | `string?` | `https://api.speko.dev` | Override the proxy base URL — useful for self-hosted deploys or local development.                             |
| `timeout` | `number?` | `30000`                 | Per-request timeout in milliseconds. Applied via an internal `AbortController` composed with external ones.    |

A trailing slash on `baseUrl` is stripped automatically.

### Instance properties [#instance-properties]

* `speko.usage` — a [`Usage`](/sdk/usage) resource for billing queries.
* `speko.credits` — a [`Credits`](/sdk/credits) resource for balance and ledger queries.
* `speko.realtime` — a [`Realtime`](/sdk/realtime) resource for opening speech-to-speech sessions.
* `speko.voice` — outbound phone-call helpers backed by [`/v1/sessions/phone`](/sdk/voice).
* `speko.phoneNumbers` — provision, list, update, release, and verify organization phone numbers.
* `speko.agents` — manage persisted voice personas and their registered tools.
* `speko.calls` — inspect calls, events, reports, recordings, and transfers.
* `speko.callbacks` — list, cancel, and dispatch scheduled callbacks.
* `speko.knowledgeBases` — manage per-agent knowledge bases and document uploads.

### Instance methods [#instance-methods]

* `speko.transcribe(audio, options, abortSignal?)` — see [transcribe](/sdk/transcribe).
* `speko.transcribeStream(audio, options, abortSignal?)` — transcript SSE events.
* `speko.synthesize(text, options, abortSignal?)` — see [synthesize](/sdk/synthesize).
* `speko.synthesizeStream(text, options, abortSignal?)` — chunked audio bytes.
* `speko.complete(params, abortSignal?)` — see [complete](/sdk/complete).
* `speko.completeStream(params, abortSignal?)` — completion SSE events.

All proxy methods accept a trailing `AbortSignal` and compose it with the client's timeout.

## Authentication [#authentication]

Requests send `Authorization: Bearer <apiKey>`. The SDK sets a package `User-Agent` on every request. Non-2xx responses are parsed as `{ error, code }` JSON when possible and re-thrown as [`SpekoApiError`](/sdk/errors) (or its `SpekoAuthError` / `SpekoRateLimitError` subclass).

## Concurrency [#concurrency]

The client is safe to share across concurrent requests — it holds no per-call mutable state. The internal `fetch` calls are fully independent; each builds its own `AbortController`.


# synthesize (/sdk/synthesize)

POST /v1/synthesize — text-to-speech with automatic provider routing.



Synthesize text into audio. The router picks the best TTS provider for your `(language, region, optimizeFor)` and fails over automatically.

```ts
const result = await speko.synthesize('Hello world', {
  language: 'en',
});
```

## Signature [#signature]

```ts
speko.synthesize(
  text: string,
  options: SynthesizeOptions,
  abortSignal?: AbortSignal,
): Promise<SynthesizeResult>

speko.synthesizeStream(
  text: string,
  options: SynthesizeOptions,
  abortSignal?: AbortSignal,
): Promise<SynthesizeStreamResult>
```

## Parameters [#parameters]

### `text: string` [#text-string]

The text to synthesize. The server-side cap is **50,000 characters per call** (raised from 10,000 to handle long-form audiobook / podcast content). The upstream provider may still apply its own limit; if you need longer than 50K, chunk the script and call `synthesize` per chunk.

### `options: SynthesizeOptions` [#options-synthesizeoptions]

Extends [`RoutingIntent`](/sdk/types#routingintent):

| Field         | Type                   | Description                                                                                                                                                                                                                                                                     |
| ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `language`    | `string` (BCP-47)      | e.g. `"en"`, `"es-MX"`.                                                                                                                                                                                                                                                         |
| `region`      | `string?`              | Region to rank streaming providers in. Defaults to `global` server-side.                                                                                                                                                                                                        |
| `optimizeFor` | `OptimizeFor?`         | `balanced`, `accuracy`, `latency`, `cost`.                                                                                                                                                                                                                                      |
| `voice`       | `string?`              | Voice id override. The router interprets it per provider (e.g. a Cartesia voice UUID). Browse the catalog with [`speko.voices.list()`](/sdk/voices).                                                                                                                            |
| `model`       | `string?`              | Upstream model name (e.g. `eleven_multilingual_v2`, `sonic-2`, `gpt-4o-mini-tts`, `qwen3-tts-flash`). Overrides the selector's choice on the primary candidate only — failover candidates use the selector's model so a model intended for provider A isn't sent to provider B. |
| `speed`       | `number?`              | Speech speed multiplier. Providers vary in what range they accept — `1.0` is always neutral.                                                                                                                                                                                    |
| `constraints` | `PipelineConstraints?` | Allow-list constraints.                                                                                                                                                                                                                                                         |

### `abortSignal?: AbortSignal` [#abortsignal-abortsignal]

Cancel an in-flight request.

## Returns [#returns]

### `SynthesizeResult` [#synthesizeresult]

| Field           | Type             | Description                                                                          |
| --------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `audio`         | `Uint8Array`     | Raw audio bytes. Format depends on the chosen provider — always check `contentType`. |
| `contentType`   | `string`         | MIME type. ElevenLabs returns `audio/mpeg`. Cartesia returns `audio/pcm;rate=24000`. |
| `provider`      | `string`         | Upstream provider that ran the request.                                              |
| `model`         | `string`         | Provider-specific model identifier (e.g. voice model name).                          |
| `failoverCount` | `number`         | Providers tried before this one succeeded.                                           |
| `scoresRunId`   | `string \| null` | Scoring run id that selected this provider.                                          |

## Wire format [#wire-format]

The SDK sends `POST /v1/synthesize` with a JSON body:

```json
{
  "text": "Hello world",
  "intent": { "language": "en", "region": "global", "optimizeFor": "latency" },
  "voice": "…",
  "speed": 1.0,
  "constraints": { "allowedProviders": { "tts": ["cartesia"] } }
}
```

The response is chunked binary audio. `provider`, `model`, `failoverCount`, and
`scoresRunId` are parsed from response headers (`X-Speko-Provider`,
`X-Speko-Model`, `X-Speko-Failover-Count`, `X-Speko-Scores-Run-Id`).
`speko.synthesize()` consumes the chunks into one `Uint8Array`; use
`speko.synthesizeStream()` to handle chunks as they arrive.

## Example: write to disk [#example-write-to-disk]

```ts
import { writeFile } from 'node:fs/promises';

const result = await speko.synthesize('Welcome to the clinic.', {
  language: 'en',
  voice: 'sonic-english',
});

const ext = result.contentType.includes('mpeg')
  ? 'mp3'
  : result.contentType.includes('pcm')
    ? 'pcm'
    : 'bin';

await writeFile(`greeting.${ext}`, result.audio);
```

## Example: pin a provider for deterministic output [#example-pin-a-provider-for-deterministic-output]

```ts
await speko.synthesize('…', {
  language: 'en',
  constraints: { allowedProviders: { tts: ['cartesia'] } },
});
```

## Example: pin a specific model [#example-pin-a-specific-model]

Useful for benchmarking (e.g. `eleven_v3` vs `eleven_multilingual_v2`) or for
long-form runs where you want to lock in a particular model's stability profile:

```ts
await speko.synthesize('…', {
  language: 'en',
  constraints: { allowedProviders: { tts: ['elevenlabs'] } },
  model: 'eleven_multilingual_v2',
});
```

## Provider params (API-level) [#provider-params-api-level]

`POST /v1/synthesize` also accepts `workload` (`conversation` | `transcription` | `narration`) and `providerOptions` (per-provider TTS params, e.g. ElevenLabs `voice_settings`) in the request body. `SynthesizeOptions` does not expose these yet - call the endpoint directly to use them:

```ts
const res = await fetch('https://api.speko.dev/v1/synthesize', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Chapter one...',
    intent: { language: 'en' },
    workload: 'narration',
    providerOptions: {
      elevenlabs: { voice_settings: { stability: 0.65 } },
    },
  }),
});
```

Applied params come back in the `X-Speko-Applied-Params` header; warnings in `X-Speko-Warnings`. Field semantics and the full param registry: [Provider params](/concepts/provider-params) and the [narration guide](/guides/narration).

## Format gotchas [#format-gotchas]

The return type depends on the provider Speko picks. If your downstream consumer only handles PCM (e.g. [`@spekoai/adapter-livekit`](/adapter-livekit/speko-tts) v1), either pin a PCM provider via `constraints` or branch on `contentType` before you decode.


# transcribe (/sdk/transcribe)

POST /v1/transcribe — speech-to-text with automatic provider routing.



Transcribe an audio payload. The router picks the best STT provider for your `(language, region, optimizeFor)` and fails over automatically.

```ts
const { text, provider, confidence } = await speko.transcribe(audio, {
  language: 'es-MX',
});
```

## Signature [#signature]

```ts
speko.transcribe(
  audio: Uint8Array,
  options: TranscribeOptions,
  abortSignal?: AbortSignal,
): Promise<TranscribeResult>

speko.transcribeStream(
  audio: Uint8Array,
  options: TranscribeOptions,
  abortSignal?: AbortSignal,
): AsyncIterable<TranscribeStreamEvent>
```

## Parameters [#parameters]

### `audio: Uint8Array` [#audio-uint8array]

Raw audio bytes. Default MIME is `audio/wav`; set `options.contentType` if you send something else. Providers handle resampling and format conversion downstream — you don't have to match a specific sample rate.

### `options: TranscribeOptions` [#options-transcribeoptions]

Extends [`RoutingIntent`](/sdk/types#routingintent):

| Field         | Type                                               | Description                                                                          |
| ------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `language`    | `string` (BCP-47)                                  | e.g. `"en"`, `"es-MX"`, `"ja-JP"`.                                                   |
| `region`      | `string?`                                          | Region to rank streaming providers in. Defaults to `global` server-side.             |
| `optimizeFor` | `'balanced' \| 'accuracy' \| 'latency' \| 'cost'?` | Bias the weighted score. Defaults to the server-side default (currently `balanced`). |
| `contentType` | `string?`                                          | MIME type for the body. Defaults to `audio/wav`.                                     |
| `constraints` | `PipelineConstraints?`                             | Allow-list constraints (see [Types](/sdk/types#pipelineconstraints)).                |
| `keywords`    | `readonly string[]?`                               | Domain words and proper nouns to bias STT output toward.                             |

### `abortSignal?: AbortSignal` [#abortsignal-abortsignal]

Cancel an in-flight request. Composed with the client-level timeout.

## Returns [#returns]

### `TranscribeResult` [#transcriberesult]

| Field           | Type             | Description                                                                               |
| --------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `text`          | `string`         | Transcribed text.                                                                         |
| `provider`      | `string`         | Upstream provider that ran the request (e.g. `deepgram`, `openai`).                       |
| `model`         | `string`         | Provider-specific model identifier.                                                       |
| `confidence`    | `number \| null` | Model-reported confidence when available, else `null`.                                    |
| `failoverCount` | `number`         | How many providers were tried before this one succeeded.                                  |
| `scoresRunId`   | `string \| null` | ID of the scoring run that selected this provider — useful for joining to benchmark data. |

## Wire format [#wire-format]

The SDK sends the audio as the raw HTTP body with:

* `Content-Type`: from `options.contentType` (default `audio/wav`).
* `X-Speko-Intent`: JSON-serialized `{ language, region?, optimizeFor? }`.
* `X-Speko-Constraints`: JSON-serialized `options.constraints` (only if set).
* `X-Speko-Stt-Options`: JSON-serialized `{ keywords, language }` (only if either is set).

The wire response is `text/event-stream` with `meta`, `transcript`, `done`,
and `error` events. `speko.transcribe()` consumes that stream and returns the
final `TranscribeResult`; use `speko.transcribeStream()` to receive partial
transcripts directly.

## Example: non-default MIME [#example-non-default-mime]

```ts
import { readFile } from 'node:fs/promises';

const audio = await readFile('./call.ogg');
const result = await speko.transcribe(audio, {
  language: 'en',
  contentType: 'audio/ogg',
  optimizeFor: 'accuracy',
});
```

## Example: restrict provider pool [#example-restrict-provider-pool]

```ts
const result = await speko.transcribe(audio, {
  language: 'en',
  constraints: {
    allowedProviders: { stt: ['deepgram', 'assemblyai'] },
  },
});
```

The router still ranks candidates by benchmark score and only picks from the allow-list.

## Example: bias proper nouns [#example-bias-proper-nouns]

```ts
const result = await speko.transcribe(audio, {
  language: 'en',
  keywords: ['Speko', 'Ava Martinez', 'Cartesia'],
});
```

## Provider params (API-level) [#provider-params-api-level]

`POST /v1/transcribe` also accepts `workload`, `diarization`, `speakersExpected`, `smartFormat`, `fillerWords`, `profanityFilter`, `wordTimestamps`, and `providerOptions` in the `X-Speko-Stt-Options` header. `TranscribeOptions` does not expose these yet - call the endpoint directly to use them:

```ts
const res = await fetch('https://api.speko.dev/v1/transcribe', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
    'Content-Type': 'audio/wav',
    'X-Speko-Intent': JSON.stringify({ language: 'en-US' }),
    'X-Speko-Stt-Options': JSON.stringify({
      workload: 'transcription',
      wordTimestamps: true, // done.words = [{ text, start, end }] in seconds
    }),
    // wordTimestamps is demote-class: pin the model that serves it, or the
    // request answers 422 no_capable_provider.
    'X-Speko-Constraints': JSON.stringify({
      allowedProviders: { stt: ['gemini:gemini-3.5-transcribe'] },
    }),
  },
  body: audio,
});
// Response is the SSE stream (meta / transcript / done events); the done
// event carries effectiveParams + warnings when these fields are used.
```

Field semantics, per-provider params, and failover behavior: [Provider params](/concepts/provider-params) and the [batch transcription guide](/guides/transcription).


# Types (/sdk/types)

Shared request / response types exported from @spekoai/sdk.



All types below are exported from the package root:

```ts
import type {
  SpekoClientOptions,
  KeySource,
  OptimizeFor,
  RoutingIntent,
  PipelineConstraints,
  TranscribeOptions,
  TranscribeResult,
  TranscribeStreamEvent,
  SynthesizeOptions,
  SynthesizeResult,
  SynthesizeStreamResult,
  ChatMessage,
  ChatTool,
  ChatToolCall,
  ChatToolChoice,
  CompleteParams,
  CompleteResult,
  CompleteStreamEvent,
  UsageSummary,
  UsageByProvider,
  UsageQueryParams,
  OrganizationBalance,
  CreditLedgerEntry,
  CreditLedgerKind,
  CreditLedgerPage,
  CreditLedgerQueryParams,
  RealtimeProvider,
  RealtimeToolSpec,
  RealtimeConnectParams,
  RealtimeFrame,
  RealtimeEventHandler,
  RealtimeSessionHandle,
  VoiceDialParams,
  VoiceDialResult,
  PhoneNumberRow,
  PhoneNumberKybOverview,
  PhoneNumberKybSubmission,
  CallDetail,
  CallEvent,
  CallReport,
  CallTransfer,
  ScheduledCallback,
  AgentCallListPage,
  AgentRow,
  AgentCreateParams,
  AgentToolRow,
  KnowledgeBaseRow,
  KnowledgeBaseDocumentRow,
} from '@spekoai/sdk';
```

## Routing primitives [#routing-primitives]

### `OptimizeFor` [#optimizefor]

```ts
type OptimizeFor = 'balanced' | 'accuracy' | 'latency' | 'cost';
```

Biases the weighted score the router uses to rank candidates. `balanced` is the default.

### `RoutingIntent` [#routingintent]

```ts
interface RoutingIntent {
  language: string; // BCP-47, e.g. "en" or "es-MX"
  region?: string; // e.g. "us-east4"; defaults to "global" server-side
  optimizeFor?: OptimizeFor;
}
```

Every proxy call takes one. `TranscribeOptions` and `SynthesizeOptions` extend it directly.

### `PipelineConstraints` [#pipelineconstraints]

```ts
interface PipelineConstraints {
  allowedProviders?: {
    stt?: string[];
    llm?: string[];
    tts?: string[];
  };
}
```

Optional allow-list layered on top of `RoutingIntent`. When set, the router still ranks by benchmark score but considers only candidates in the allow-list for that modality.

## Transcribe [#transcribe]

```ts
interface TranscribeOptions extends RoutingIntent {
  contentType?: string; // default "audio/wav"
  constraints?: PipelineConstraints;
  keywords?: readonly string[];
}

interface TranscribeResult {
  text: string;
  provider: string;
  model: string;
  confidence: number | null;
  failoverCount: number;
  scoresRunId: string | null;
}
```

## Synthesize [#synthesize]

```ts
interface SynthesizeOptions extends RoutingIntent {
  voice?: string;
  speed?: number;
  constraints?: PipelineConstraints;
}

interface SynthesizeResult {
  audio: Uint8Array;
  contentType: string; // e.g. "audio/pcm;rate=24000" or "audio/mpeg"
  provider: string;
  model: string;
  failoverCount: number;
  scoresRunId: string | null;
}
```

## Complete [#complete]

```ts
interface ChatMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  toolCalls?: ChatToolCall[];
  toolCallId?: string;
  isError?: boolean;
}

interface ChatToolCall {
  id: string;
  name: string;
  args: string;
}

type ChatToolChoice =
  | 'auto'
  | 'none'
  | 'required'
  | { type: 'function'; function: { name: string } };

interface ChatTool {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
  executionMode?: 'inline' | 'webhook' | 'builtin' | 'integration';
  source?:
    | { kind: 'inline' }
    | {
        kind: 'webhook';
        url: string;
        secretRef: string;
        headers?: Record<string, string>;
        authHeaders?: Array<{ name: string; secretRef: string }>;
        timeoutMs?: number; // 100-4000; clamped to 4000ms by the executor
        responseMode?: 'sync' | 'async';
        asyncAck?: string;
      }
    | { kind: 'builtin'; name: string; config?: unknown }
    | {
        kind: 'integration';
        installationId: string;
        appKey: string;
        actionKey: string;
        config?: unknown;
      };
}

interface CompleteParams {
  messages: ChatMessage[];
  intent: RoutingIntent;
  systemPrompt?: string;
  temperature?: number;
  maxTokens?: number;
  reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
  constraints?: PipelineConstraints;
  tools?: ChatTool[];
  toolChoice?: ChatToolChoice;
  parallelToolCalls?: boolean;
  maxToolHops?: number;
}

interface CompleteResult {
  text: string;
  provider: string;
  model: string;
  usage: {
    promptTokens: number;
    completionTokens: number;
  };
  failoverCount: number;
  scoresRunId: string | null;
  toolCalls?: ChatToolCall[];
}
```

## Usage [#usage]

```ts
type KeySource = 'BYOK' | 'MANAGED';

interface UsageQueryParams {
  from?: string; // ISO-8601
  to?: string; // ISO-8601
}

interface UsageSummary {
  totalSessions: number;
  totalMinutes: number;
  totalCost: number;
  breakdown: UsageByProvider[];
  balanceUsd: number;
  currency: 'USD';
}

interface UsageByProvider {
  provider: string;
  type: 'stt' | 'llm' | 'tts';
  metric: string;
  keySource: KeySource;
  quantity: number;
  cost: number;
}
```

## Credits [#credits]

```ts
interface OrganizationBalance {
  balanceUsd: number;
  currency: 'USD';
  updatedAt: string;
}

type CreditLedgerKind = 'grant' | 'debit' | 'topup' | 'refund' | 'adjustment';

interface CreditLedgerEntry {
  id: string;
  kind: CreditLedgerKind;
  /** Signed. Positive for grants/topups/refunds, negative for debits. */
  amountMicroUsd: string;
  metric: string | null;
  provider: string | null;
  sessionId: string | null;
  createdAt: string;
}

interface CreditLedgerPage {
  entries: CreditLedgerEntry[];
  nextCursor: string | null;
}

interface CreditLedgerQueryParams {
  limit?: number;
  cursor?: string;
}
```

## Realtime (S2S) [#realtime-s2s]

```ts
type RealtimeProvider = 'openai' | 'google' | 'xai';

interface RealtimeToolSpec {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
}

interface RealtimeConnectParams {
  agentId?: string;
  provider: RealtimeProvider;
  model: string;
  voice?: string;
  systemPrompt?: string;
  temperature?: number;
  inputSampleRate?: 16000 | 24000;
  outputSampleRate?: 16000 | 24000;
  tools?: RealtimeToolSpec[];
  metadata?: Record<string, unknown>;
  webhookTags?: Record<string, string>;
  /** Requested maximum duration; the returned entitlement may impose a lower cap. */
  ttlSeconds?: number;
  /** Reuse after an ambiguous bootstrap timeout. Generated when omitted. */
  idempotencyKey?: string;
}

type RealtimeFrame =
  | { type: 'ready'; inputSampleRate: 16000 | 24000; outputSampleRate: 16000 | 24000 }
  | { type: 'audio'; pcm: Uint8Array; sampleRate: number }
  | {
      type: 'transcript';
      role: 'user' | 'assistant';
      text: string;
      final: boolean;
    }
  | {
      type: 'tool_call';
      callId: string;
      name: string;
      arguments: string;
    }
  | {
      type: 'usage';
      inputAudioTokens: number;
      outputAudioTokens: number;
    }
  | { type: 'interruption'; at: 'user' | 'assistant' }
  | {
      type: 'server_tool_call';
      id: string;
      name: string;
      status: 'started' | 'completed' | 'failed';
    }
  | { type: 'error'; code: string; message: string }
  | { type: 'close'; code: number; reason: string };

type RealtimeEventHandler = (frame: RealtimeFrame) => void;

interface RealtimeSessionHandle {
  readonly sessionId: string;
  readonly expiresAt: string;
  readonly inputSampleRate: 16000 | 24000;
  readonly outputSampleRate: 16000 | 24000;

  sendAudio(pcm: Uint8Array): void;
  commit(): void;
  interrupt(): void;
  sendToolResult(callId: string, output: string): void;
  on(handler: RealtimeEventHandler): () => void;
  close(code?: number, reason?: string): void;
}
```

## Voice, Phone Numbers, Agents, and Knowledge Bases [#voice-phone-numbers-agents-and-knowledge-bases]

These resource types are also exported from the package root. The full shapes live in TypeScript and are intended to be consumed from your editor, but the high-level entry points are:

```ts
interface VoiceDialParams {
  to: string;
  from?: string;
  intent: RoutingIntent;
  constraints?: PipelineConstraints;
  voice?: string;
  systemPrompt?: string;
  llm?: { temperature?: number; maxTokens?: number };
  ttsOptions?: { sampleRate?: number; speed?: number };
  metadata?: Record<string, unknown>;
  webhookTags?: Record<string, string>;
}

interface VoiceDialResult {
  sessionId: string;
  callControlId: string;
  roomName: string;
  status: 'dialing' | 'dialing-stub';
  to: string;
  from: string;
}

interface PhoneNumberRow {
  id: string;
  e164: string;
  direction: 'inbound' | 'outbound' | 'both';
  label: string | null;
  agentId: string | null;
  createdAt: string;
  updatedAt: string;
}

interface AgentRow {
  id: string;
  name: string;
  systemPrompt: string;
  voice: string | null;
  intent: { language: string; optimizeFor?: 'latency' | 'quality' | 'cost' };
  llmOptions: { temperature?: number; maxTokens?: number; model?: string } | null;
  stackPreferences: {
    allowedProviders?: { stt?: string[]; llm?: string[]; tts?: string[]; s2s?: string[] };
  } | null;
  sttOptions: { keywords?: string[]; prompt?: string; language?: string } | null;
  createdAt: string;
  updatedAt: string;
}

interface KnowledgeBaseRow {
  id: string;
  agentId: string;
  name: string;
  description: string | null;
  embeddingModel: string;
  documentCount: number;
  chunkCount: number;
  createdAt: string;
  updatedAt: string;
}
```

## Client [#client]

```ts
interface SpekoClientOptions {
  apiKey: string;
  brokerId?: string; // required by human-calling presence, dial, and join
  baseUrl?: string; // default "https://api.speko.dev"
  timeout?: number; // default 30000
}
```


# usage (/sdk/usage)

GET /v1/usage — billing and usage reporting.



Get a usage summary for a billing period. Exposed via `speko.usage`.

```ts
const usage = await speko.usage.get();
console.log(usage.totalSessions, usage.totalMinutes, usage.totalCost);
```

## `speko.usage.get(params?)` [#spekousagegetparams]

### Signature [#signature]

```ts
speko.usage.get(params?: UsageQueryParams): Promise<UsageSummary>
```

### `UsageQueryParams` [#usagequeryparams]

| Field  | Type      | Description                                                        |
| ------ | --------- | ------------------------------------------------------------------ |
| `from` | `string?` | ISO-8601 start date. Omit to default to the current billing start. |
| `to`   | `string?` | ISO-8601 end date. Omit to default to now.                         |

### Returns — `UsageSummary` [#returns--usagesummary]

| Field           | Type                | Description                                |
| --------------- | ------------------- | ------------------------------------------ |
| `totalSessions` | `number`            | Distinct sessions in range.                |
| `totalMinutes`  | `number`            | Total audio minutes billed.                |
| `totalCost`     | `number`            | Total cost in USD.                         |
| `breakdown`     | `UsageByProvider[]` | Per-provider rollup (see below).           |
| `balanceUsd`    | `number`            | Current organization balance in USD.       |
| `currency`      | `'USD'`             | Currency for `balanceUsd` and `totalCost`. |

### `UsageByProvider` [#usagebyprovider]

| Field       | Type                      | Description                                                                      |
| ----------- | ------------------------- | -------------------------------------------------------------------------------- |
| `provider`  | `string`                  | Upstream provider id.                                                            |
| `type`      | `'stt' \| 'llm' \| 'tts'` | Modality.                                                                        |
| `metric`    | `string`                  | The billable metric (e.g. `minutes`, `characters`, `tokens`).                    |
| `keySource` | `'BYOK' \| 'MANAGED'`     | `BYOK` = customer key, no Speko margin. `MANAGED` = platform key, billed to org. |
| `quantity`  | `number`                  | Billed quantity in the metric's unit.                                            |
| `cost`      | `number`                  | Cost in USD.                                                                     |

## Example: last 24 hours [#example-last-24-hours]

```ts
const now = new Date();
const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);

const usage = await speko.usage.get({
  from: yesterday.toISOString(),
  to: now.toISOString(),
});

for (const row of usage.breakdown) {
  console.log(`${row.type}\t${row.provider}\t${row.quantity}${row.metric}\t$${row.cost}`);
}
```


# voice (/sdk/voice)

Outbound phone calls through POST /v1/sessions/phone.



Use `speko.voice.dial()` to place an outbound PSTN call. The API creates a voice session, dispatches the configured worker, and dials the destination over LiveKit SIP.

```ts
const call = await speko.voice.dial({
  to: '+12015551234',
  from: '+12015550199',
  agentId: 'agent_123',
  webhookTags: { environment: 'production' },
  telephony: {
    region: 'us-east',
    amd: { mode: 'agent', timeoutSeconds: 8 },
  },
});

console.log(call.sessionId, call.status);
```

## Signature [#signature]

```ts
speko.voice.dial(params: VoiceDialParams): Promise<VoiceDialResult>
```

## Parameters [#parameters]

| Field          | Type                                                                                                 | Description                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`           | `string`                                                                                             | Destination in E.164 format.                                                                                                                                                                                                                                                                                                                        |
| `from`         | `string?`                                                                                            | Caller ID. Must be registered to the organization unless it is the server default.                                                                                                                                                                                                                                                                  |
| `agentId`      | `string?`                                                                                            | Persisted agent to run. Required unless `intent` is supplied.                                                                                                                                                                                                                                                                                       |
| `intent`       | `RoutingIntent?`                                                                                     | Routing intent for ad hoc calls. Required unless `agentId` is supplied.                                                                                                                                                                                                                                                                             |
| `constraints`  | `PipelineConstraints?`                                                                               | Provider allow-list constraints.                                                                                                                                                                                                                                                                                                                    |
| `voice`        | `string?`                                                                                            | TTS voice id override.                                                                                                                                                                                                                                                                                                                              |
| `systemPrompt` | `string?`                                                                                            | Agent instructions for this call.                                                                                                                                                                                                                                                                                                                   |
| `firstMessage` | `string?`                                                                                            | Optional first utterance.                                                                                                                                                                                                                                                                                                                           |
| `llm`          | `{ temperature?: number; maxTokens?: number }?`                                                      | LLM tuning.                                                                                                                                                                                                                                                                                                                                         |
| `ttsOptions`   | `{ sampleRate?: number; speed?: number }?`                                                           | TTS options.                                                                                                                                                                                                                                                                                                                                        |
| `sttOptions`   | `{ keywords?: string[]; prompt?: string; language?: string }?`                                       | STT keyword hints, an optional free-text transcription `prompt` (domain/context prose, max 2000 chars — used only by prompt-capable models such as OpenAI GPT transcribe and AssemblyAI Universal-3 Pro), and a stream-language override — pass `'auto'` to let the provider detect the spoken language (Soniox auto-detects when no hint is sent). |
| `telephony`    | `{ region?: string; amd?: { mode?: 'agent' \| 'carrier' \| 'disabled'; timeoutSeconds?: number } }?` | SIP routing and voicemail-detection hints.                                                                                                                                                                                                                                                                                                          |
| `webhookTags`  | `Record<string, string>?`                                                                            | Case-sensitive workspace webhook routing tags; requires `agentId`.                                                                                                                                                                                                                                                                                  |
| `metadata`     | `Record<string, unknown>?`                                                                           | Free-form metadata surfaced in webhooks and call events.                                                                                                                                                                                                                                                                                            |

## Returns [#returns]

| Field           | Type                          | Description                                                             |
| --------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `sessionId`     | `string`                      | Voice session id.                                                       |
| `callControlId` | `string`                      | LiveKit SIP participant identity for the outbound leg.                  |
| `roomName`      | `string`                      | LiveKit room name.                                                      |
| `status`        | `'dialing' \| 'dialing-stub'` | Dial status. Stub appears when SIP is not configured in the deployment. |
| `to`            | `string`                      | Destination number.                                                     |
| `from`          | `string`                      | Resolved caller ID.                                                     |


# voices (/sdk/voices)

GET /v1/voices — read-only catalog of TTS voices grouped by provider.



Browse the curated voice catalog before calling `synthesize`. Handy for picking
a voice id without reading every TTS provider's API docs.

```ts
const { voices, providers } = await speko.voices.list();
```

## Signature [#signature]

```ts
speko.voices.list(params?: VoicesListParams): Promise<VoicesListResult>
```

## Parameters [#parameters]

### `params.provider: string?` [#paramsprovider-string]

Filter to a single provider's voices. Accepts either the routing key
(`cartesia`, `xai`, `alibaba`, `openai`, `inworld`, `elevenlabs`) or the catalog
suffix form (`xai-tts`, `alibaba-tts`, `openai-tts`).

## Returns [#returns]

### `VoicesListResult` [#voiceslistresult]

| Field       | Type                    | Description                                            |
| ----------- | ----------------------- | ------------------------------------------------------ |
| `voices`    | `VoiceCatalogEntry[]`   | Curated voice roster across the included providers.    |
| `providers` | `VoicesProviderEntry[]` | TTS providers Speko routes to, with their model lists. |

### `VoiceCatalogEntry` [#voicecatalogentry]

| Field    | Type     | Description                                                  |
| -------- | -------- | ------------------------------------------------------------ |
| `vendor` | `string` | Routing-key vendor (matches `allowedProviders.tts` entries). |
| `id`     | `string` | Voice id forwarded verbatim to the provider's TTS API.       |
| `name`   | `string` | Human-readable label, e.g. `"Katie (American female)"`.      |

### `VoicesProviderEntry` [#voicesproviderentry]

| Field               | Type       | Description                                                                             |
| ------------------- | ---------- | --------------------------------------------------------------------------------------- |
| `key`               | `string`   | Catalog key, e.g. `cartesia`, `elevenlabs`, `alibaba-tts`.                              |
| `name`              | `string`   | Human-readable provider name.                                                           |
| `models`            | `string[]` | Models available for the `model` field on `synthesize`.                                 |
| `voicesFetchedLive` | `boolean`  | `true` when the provider's voice library is account-scoped (currently only ElevenLabs). |

## ElevenLabs [#elevenlabs]

ElevenLabs voices are account-scoped, so they are **not** included in
`voices` — the corresponding `providers` entry sets `voicesFetchedLive: true`
as a hint to fetch them directly from
[`https://api.elevenlabs.io/v1/voices`](https://elevenlabs.io/docs/api-reference/voices/get-all)
with the org's key.

## Example: pick a voice and synthesize [#example-pick-a-voice-and-synthesize]

```ts
const { voices } = await speko.voices.list({ provider: 'cartesia' });
const sonia = voices.find((v) => v.name.startsWith('Sonia')) ?? voices[0]!;

await speko.synthesize('Hello world', {
  language: 'en',
  voice: sonia.id,
  constraints: { allowedProviders: { tts: ['cartesia'] } },
});
```


# webhooks (/sdk/webhooks)

Workspace lifecycle endpoints and delivery logs.



Use `speko.webhooks` to configure organization-level lifecycle routing. Endpoint secrets are write-only.

```ts
const endpoint = await speko.webhooks.create({
  name: 'Production events',
  url: 'https://hooks.example.com/speko',
  events: ['call.status', 'call.report'],
  allAgents: true,
  filterTags: { environment: 'production' },
});

await speko.webhooks.update(endpoint.id, {
  events: ['call.status', 'call.report', 'call.recording'],
});

const failures = await speko.webhooks.deliveries.list({
  endpointId: endpoint.id,
  status: 'failed',
});

if (failures.data[0]) {
  const detail = await speko.webhooks.deliveries.get(failures.data[0].id);
  console.log(detail.attempts);
  await speko.webhooks.deliveries.redeliver(detail.id);
}
```

## Endpoint methods [#endpoint-methods]

| Method                             | Returns                      |
| ---------------------------------- | ---------------------------- |
| `speko.webhooks.list()`            | `Promise<WebhookEndpoint[]>` |
| `speko.webhooks.create(input)`     | `Promise<WebhookEndpoint>`   |
| `speko.webhooks.get(id)`           | `Promise<WebhookEndpoint>`   |
| `speko.webhooks.update(id, patch)` | `Promise<WebhookEndpoint>`   |
| `speko.webhooks.delete(id)`        | `Promise<void>`              |

## Delivery methods [#delivery-methods]

| Method                                     | Returns                                      |
| ------------------------------------------ | -------------------------------------------- |
| `speko.webhooks.deliveries.list(filters?)` | Cursor-paginated `WebhookDeliveryPage`       |
| `speko.webhooks.deliveries.get(id)`        | Sanitized payload and chronological attempts |
| `speko.webhooks.deliveries.redeliver(id)`  | The new manual attempt result                |

List filters include `endpointId`, `event`, `agentId`, `status`, `sessionId`, `eventId`, `from`, `to`, `cursor`, and `limit`. The event filter includes both `call.*` lifecycle events and private phone API `imessage.*` subscriber events. Delivery data expires after 30 days. Manual redelivery is disabled for pre-call, expired, deleted-endpoint, and provider-retried iMessage deliveries; check `canRedeliver` before calling it.

See [Workspace webhooks](/docs/guides/webhooks) for routing, signing, retry, and tag semantics.


# complete (/sdk-python/complete)

POST /v1/complete — LLM completion with automatic provider routing.



Run a single-shot LLM completion. The router picks the best LLM provider for your intent and fails over automatically.

```python
from spekoai import ChatMessage, RoutingIntent

reply = speko.complete(
    messages=[ChatMessage(role="user", content="Hi!")],
    intent=RoutingIntent(language="en"),
)
print(reply.text, reply.provider, reply.usage.prompt_tokens)
```

## Signature [#signature]

<CodeGroup>
  ```python sync
  Speko.complete(
      *,
      messages: list[ChatMessage | dict],
      intent: RoutingIntent | dict,
      system_prompt: str | None = None,
      temperature: float | None = None,
      max_tokens: int | None = None,
      constraints: PipelineConstraints | dict | None = None,
  ) -> CompleteResult
  ```

  ```python async
  await AsyncSpeko.complete(
      *,
      messages: list[ChatMessage | dict],
      intent: RoutingIntent | dict,
      system_prompt: str | None = None,
      temperature: float | None = None,
      max_tokens: int | None = None,
      constraints: PipelineConstraints | dict | None = None,
  ) -> CompleteResult
  ```
</CodeGroup>

## Parameters [#parameters]

<ParamField path="messages" type="list[ChatMessage | dict]">
  Conversation history. Roles: `system`, `user`, `assistant`. Dicts are validated against `ChatMessage` on the way in.
</ParamField>

<ParamField path="intent" type="RoutingIntent | dict">
  Routing intent — `language`, optional `optimize_for`.
</ParamField>

<ParamField path="system_prompt" type="string">
  Shortcut for a leading system message. Providers with a native system channel use it directly; others fold it into the message list.
</ParamField>

<ParamField path="temperature" type="float">
  Forwarded to the provider. Omit to use the provider's default.
</ParamField>

<ParamField path="max_tokens" type="int">
  Max completion tokens. Omit to use the provider's default.
</ParamField>

<ParamField path="constraints" type="PipelineConstraints | dict" />

## Returns — `CompleteResult` [#returns--completeresult]

<ResponseField name="text" type="string">
  Assistant reply.
</ResponseField>

<ResponseField name="provider" type="string" />

<ResponseField name="model" type="string" />

<ResponseField name="usage.prompt_tokens" type="int" />

<ResponseField name="usage.completion_tokens" type="int" />

<ResponseField name="failover_count" type="int" />

<ResponseField name="scores_run_id" type="string | None" />

<Info>
  `/v1/complete` streams over the wire. The Python SDK consumes the stream and
  returns the final `CompleteResult`; explicit Python streaming helpers are not
  exposed yet.
</Info>

## Example — multi-turn [#example--multi-turn]

```python
messages = [
    {"role": "system", "content": "You are a concise voice assistant."},
    {"role": "user", "content": "Book me an appointment for Tuesday."},
]

first = speko.complete(
    messages=messages,
    intent={"language": "en"},
    temperature=0.3,
    max_tokens=200,
)

messages.append({"role": "assistant", "content": first.text})
messages.append({"role": "user", "content": "3pm, with Dr. Chen."})

second = speko.complete(
    messages=messages,
    intent={"language": "en"},
)
```

## Example — pin a provider [#example--pin-a-provider]

```python
from spekoai import AllowedProviders, PipelineConstraints

reply = speko.complete(
    messages=[{"role": "user", "content": "…"}],
    intent={"language": "en"},
    constraints=PipelineConstraints(
        allowed_providers=AllowedProviders(llm=["anthropic"]),
    ),
)
```


# credits (/sdk-python/credits)

Prepaid credit balance and append-only ledger.



Query the organization's prepaid credit balance and walk the ledger of every credit movement (grants, debits, topups, refunds, adjustments). Exposed via `speko.credits`.

Balances are returned in USD. Ledger amounts still use micro-USD strings because ledger entries are signed accounting units.

## `get_balance` [#get_balance]

<CodeGroup>
  ```python sync
  Speko.credits.get_balance() -> OrganizationBalance
  ```

  ```python async
  await AsyncSpeko.credits.get_balance() -> OrganizationBalance
  ```
</CodeGroup>

Returns the current balance for the caller's organization.

```python
balance = speko.credits.get_balance()
if balance.balance_usd < 0.5:
    print("Top up before running long sessions.")
```

### `OrganizationBalance` [#organizationbalance]

<ResponseField name="balance_usd" type="float" />

<ResponseField name="currency" type="'USD'" />

<ResponseField name="updated_at" type="string">
  ISO-8601 timestamp of the last ledger event.
</ResponseField>

## `get_ledger` [#get_ledger]

<CodeGroup>
  ```python sync
  Speko.credits.get_ledger(
      *,
      limit: int | None = None,
      cursor: str | None = None,
  ) -> CreditLedgerPage
  ```

  ```python async
  await AsyncSpeko.credits.get_ledger(
      *,
      limit: int | None = None,
      cursor: str | None = None,
  ) -> CreditLedgerPage
  ```
</CodeGroup>

Most-recent-first page of credit movements. Pass `next_cursor` from one response back in as `cursor` to fetch the next page; `next_cursor is None` means the history is exhausted.

```python
page = speko.credits.get_ledger(limit=50)
while True:
    for entry in page.entries:
        print(entry.created_at, entry.kind, entry.amount_micro_usd, entry.provider)
    if page.next_cursor is None:
        break
    page = speko.credits.get_ledger(limit=50, cursor=page.next_cursor)
```

### `CreditLedgerEntry` [#creditledgerentry]

<ResponseField name="id" type="string" />

<ResponseField name="kind" type="'grant' | 'debit' | 'topup' | 'refund' | 'adjustment'" />

<ResponseField name="amount_micro_usd" type="string">
  Signed — positive for grants/topups/refunds, negative for debits. String-encoded to survive JSON for values beyond 2^53.
</ResponseField>

<ResponseField name="metric" type="string | None">
  Billable metric when the entry ties to a specific usage row.
</ResponseField>

<ResponseField name="provider" type="string | None" />

<ResponseField name="session_id" type="string | None">
  Session the debit was applied against.
</ResponseField>

<ResponseField name="created_at" type="string" />

### `CreditLedgerPage` [#creditledgerpage]

<ResponseField name="entries" type="list[CreditLedgerEntry]" />

<ResponseField name="next_cursor" type="string | None">
  Cursor for the next page, or `None` when history is exhausted.
</ResponseField>


# Errors (/sdk-python/errors)

Typed exceptions raised by the Python SDK.



Every non-2xx API response is raised as a typed exception. Import from the package root:

```python
from spekoai import SpekoApiError, SpekoAuthError, SpekoRateLimitError
```

| Exception             | When              | Attributes                                                                 |
| --------------------- | ----------------- | -------------------------------------------------------------------------- |
| `SpekoAuthError`      | HTTP `401`        | `message`, `status=401`, `code="AUTH_ERROR"`                               |
| `SpekoRateLimitError` | HTTP `429`        | `message`, `status=429`, `code="RATE_LIMITED"`, `retry_after: int \| None` |
| `SpekoApiError`       | any other non-2xx | `message`, `status`, `code`                                                |

`message` and `code` are parsed from the JSON error body when present (`{"error": "...", "code": "..."}`); otherwise they fall back to `response.text` and `"UNKNOWN"`.

## Example — targeted handling [#example--targeted-handling]

```python
import time

from spekoai import Speko, SpekoApiError, SpekoAuthError, SpekoRateLimitError

speko = Speko(api_key="sk_live_...")

try:
    speko.complete(
        messages=[{"role": "user", "content": "Hi"}],
        intent={"language": "en"},
    )
except SpekoAuthError:
    raise
except SpekoRateLimitError as err:
    time.sleep(err.retry_after or 1)
except SpekoApiError as err:
    log.exception("speko call failed: %s (%s)", err.code, err.status)
```

<Note>
  `SpekoAuthError` and `SpekoRateLimitError` both inherit from `SpekoApiError`, so a bare `except SpekoApiError` catches all three. Always branch from most specific to most general.
</Note>

## Realtime errors [#realtime-errors]

`connect_realtime` raises the same three exceptions from the initial `POST /v1/sessions` call. Once the provider connection is open, WebRTC or WebSocket failures surface as frames with `type == "error"`:

```python
async for frame in session:
    if frame["type"] == "error":
        log.error("realtime: %s — %s", frame["code"], frame["message"])
        break
```


# spekoai (Python) (/sdk-python/overview)

Official Python SDK for the Speko voice gateway — sync + async.



`spekoai` is the Python counterpart to `@spekoai/sdk`. The surface mirrors the TypeScript client one-to-one: `transcribe`, `synthesize`, `complete`, `usage`, `credits`, plus an async-only `connect_realtime` for speech-to-speech sessions.

Speko benchmarks every STT, LLM, and TTS provider per `(language, optimize_for)` and routes each call to the best one in real time. Failover is server-side — you ship one integration; providers rotate without a code change.

## Install [#install]

```bash
pip install spekoai
# or
uv add spekoai
```

Python 3.9+. Depends on `httpx`, `pydantic`, and `websockets`.

## Quickstart [#quickstart]

<CodeGroup>
  ```python sync
  import os
  from pathlib import Path

  from spekoai import Speko

  speko = Speko(api_key=os.environ["SPEKO_API_KEY"])

  audio = Path("call.wav").read_bytes()
  result = speko.transcribe(
  audio,
  language="es-MX",
  )
  print(result.text, result.provider, result.confidence)

  ```

  ```python async
  import asyncio
  import os
  from pathlib import Path

  from spekoai import AsyncSpeko

  async def main():
      async with AsyncSpeko(api_key=os.environ["SPEKO_API_KEY"]) as speko:
          audio = Path("call.wav").read_bytes()
          result = await speko.transcribe(
              audio,
              language="es-MX",
          )
          print(result.text, result.provider, result.confidence)

  asyncio.run(main())
  ```
</CodeGroup>

## What the router does [#what-the-router-does]

Every proxy call takes a `RoutingIntent` (`language`, optional `optimize_for`). Speko scores every provider for that intent against its continuously-updated benchmark set, picks the top-ranked one, and fails over to the next-best if the primary errors. The returned result carries `provider`, `model`, `failover_count`, and `scores_run_id` so you can log what actually ran.

To restrict the pool — for compliance, cost caps, or pinning a provider while debugging — pass `constraints=PipelineConstraints(allowed_providers=AllowedProviders(stt=[...], llm=[...], tts=[...]))`. The router still ranks by score but only considers candidates on the allow-list.

## Pydantic models, camelCase wire [#pydantic-models-camelcase-wire]

All request/response models use camelCase aliases over the wire and snake\_case attributes in Python. You can pass plain `dict`s wherever a model is accepted — the SDK validates them.

```python
from spekoai import ChatMessage, RoutingIntent

# Typed form
speko.complete(
    messages=[ChatMessage(role="user", content="Hi")],
    intent=RoutingIntent(language="en"),
)

# Dict form — validated on the way in
speko.complete(
    messages=[{"role": "user", "content": "Hi"}],
    intent={"language": "en"},
)
```

## Reference [#reference]

<Columns cols="2">
  <Card title="transcribe" icon="microphone" href="/sdk-python/transcribe">
    `POST /v1/transcribe` — speech to text.
  </Card>

  <Card title="synthesize" icon="volume" href="/sdk-python/synthesize">
    `POST /v1/synthesize` — text to speech.
  </Card>

  <Card title="complete" icon="brain" href="/sdk-python/complete">
    `POST /v1/complete` — LLM completion.
  </Card>

  <Card title="connect_realtime" icon="waveform" href="/sdk-python/realtime">
    Provider-direct speech-to-speech sessions (async only).
  </Card>

  <Card title="usage" icon="chart-line" href="/sdk-python/usage">
    `GET /v1/usage` — billing summary.
  </Card>

  <Card title="credits" icon="coin" href="/sdk-python/credits">
    Prepaid balance and append-only ledger.
  </Card>

  <Card title="errors" icon="triangle-exclamation" href="/sdk-python/errors">
    `SpekoApiError`, `SpekoAuthError`, `SpekoRateLimitError`.
  </Card>
</Columns>

## Client options [#client-options]

| Option     | Default                 | Description                                                                                       |
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
| `api_key`  | — (required)            | Your API key. Mint one at [platform.speko.ai/agents/keys](https://platform.speko.ai/agents/keys). |
| `base_url` | `https://api.speko.dev` | Override for local development or self-hosted deployments. Trailing slash is stripped.            |
| `timeout`  | `30.0`                  | Per-request timeout in seconds.                                                                   |

Both clients are safe to share across concurrent calls. `Speko` is a sync context manager (`__enter__` / `__exit__` / `close()`); `AsyncSpeko` is an async context manager (`__aenter__` / `__aexit__` / `await close()`).


# connect_realtime (/sdk-python/realtime)

Provider-direct speech-to-speech sessions, async only.



Open a speech-to-speech (S2S) session. Speko reserves the entitlement and mints a short-lived provider credential; the SDK then connects straight to OpenAI Realtime, Gemini Live, or xAI Grok Voice. Audio never traverses a Speko media proxy.

<Info>
  Realtime sessions are only available on `AsyncSpeko`. OpenAI uses an `aiortc` WebRTC connection; Gemini Live and xAI use asynchronous provider WebSockets.
</Info>

```python
import asyncio
from spekoai import AsyncSpeko, RealtimeConnectParams

async def main():
    async with AsyncSpeko(api_key=os.environ["SPEKO_API_KEY"]) as speko:
        session = await speko.connect_realtime(
            RealtimeConnectParams(provider="openai", model="gpt-realtime-2.1"),
        )
        async with session:
            await session.send_audio(pcm_chunk)
            async for frame in session:
                if frame["type"] == "audio":
                    play(frame["pcm"])
                elif frame["type"] == "transcript":
                    print(frame["text"])

asyncio.run(main())
```

## Signature [#signature]

```python
await AsyncSpeko.connect_realtime(
    params: RealtimeConnectParams,
) -> AsyncRealtimeSession
```

## `RealtimeConnectParams` [#realtimeconnectparams]

<ParamField path="provider" type="'openai' | 'google' | 'xai'" />

<ParamField path="model" type="string">
  Provider-specific model id, such as `gpt-realtime-2.1`, `gemini-3.1-flash-live-preview`, or `grok-voice-latest`.
</ParamField>

<ParamField path="voice" type="string">
  Voice id override — interpreted per provider.
</ParamField>

<ParamField path="system_prompt" type="string" />

<ParamField path="temperature" type="float" />

<ParamField path="input_sample_rate" type="16000 | 24000" />

<ParamField path="output_sample_rate" type="16000 | 24000" />

<ParamField path="tools" type="list[RealtimeToolSpec]">
  Tool definitions the assistant may call. Receive `tool_call` frames and respond with `send_tool_result`.
</ParamField>

<ParamField path="metadata" type="dict[str, object]">
  Free-form metadata attached to the session record.
</ParamField>

<ParamField path="ttl_seconds" type="int">
  Requested maximum session duration. The returned entitlement and provider limits may impose a lower cap.
</ParamField>

<ParamField path="idempotency_key" type="string">
  Stable bootstrap key to reuse after an ambiguous timeout. The SDK generates one when omitted.
</ParamField>

## `AsyncRealtimeSession` [#asyncrealtimesession]

The returned session is both an async context manager and an async iterator.

### Properties [#properties]

| Property             | Type  | Description                                   |
| -------------------- | ----- | --------------------------------------------- |
| `session_id`         | `str` | Server-assigned session identifier.           |
| `expires_at`         | `str` | ISO-8601 expiry for the delegated credential. |
| `input_sample_rate`  | `int` | Provider input PCM sample rate.               |
| `output_sample_rate` | `int` | Provider output PCM sample rate.              |

### Methods [#methods]

<ParamField path="send_audio(pcm: bytes)" type="coroutine">
  Send a PCM16 chunk directly to the selected provider.
</ParamField>

<ParamField path="commit()" type="coroutine">
  Signal an end-of-user-turn to the provider.
</ParamField>

<ParamField path="interrupt()" type="coroutine">
  Cancel the assistant's current response mid-generation.
</ParamField>

<ParamField path="send_tool_result(call_id: str, output: str)" type="coroutine">
  Return the result of a previously-issued tool call.
</ParamField>

<ParamField path="close(code=1000, reason='client_closed')" type="coroutine">
  Close the socket. Safe to call multiple times; the context manager calls it for you on exit.
</ParamField>

### Frame types [#frame-types]

Iterating the session yields dicts tagged by `type`:

| Frame `type` | Payload fields                                            |
| ------------ | --------------------------------------------------------- |
| `audio`      | `pcm: bytes`, `sample_rate: 24000`                        |
| `transcript` | `role: 'user' \| 'assistant'`, `text: str`, `final: bool` |
| `tool_call`  | `call_id: str`, `name: str`, `arguments: str` (JSON)      |
| `usage`      | `input_audio_tokens: int`, `output_audio_tokens: int`     |
| `error`      | `code: str`, `message: str`                               |
| `close`      | `reason: str`                                             |

## Example — tool calling [#example--tool-calling]

```python
import json
from spekoai import AsyncSpeko, RealtimeConnectParams, RealtimeToolSpec

async with AsyncSpeko(api_key=os.environ["SPEKO_API_KEY"]) as speko:
    session = await speko.connect_realtime(
        RealtimeConnectParams(
            provider="openai",
            model="gpt-realtime-2.1",
            tools=[
                RealtimeToolSpec(
                    name="get_weather",
                    description="Current weather for a city.",
                    parameters={
                        "type": "object",
                        "properties": {"city": {"type": "string"}},
                        "required": ["city"],
                    },
                ),
            ],
        ),
    )

    async with session:
        async for frame in session:
            if frame["type"] == "tool_call" and frame["name"] == "get_weather":
                args = json.loads(frame["arguments"])
                result = fetch_weather(args["city"])
                await session.send_tool_result(frame["call_id"], result)
```


# SMS (/sdk-python/sms)

Send, schedule, batch, and manage compliant SMS with Python.



Sync and async clients expose matching resources under `sms`:

```python
message = speko.sms.messages.send(
    {
        "from_phone_number_id": "8f0e9a96-...",
        "to": "+12025550123",
        "text": "Acme: your appointment is confirmed.",
        "recipient_timezone": "America/New_York",
    },
    idempotency_key="appointment-982-confirmation",
)
```

Use `messages`, `batches`, `conversations`, `consents`, `suppressions`, and `settings` for the complete REST surface. `speko.sms.stream()` yields typed live events; `AsyncSpeko` exposes the same methods as coroutines and an async event iterator.


# synthesize (/sdk-python/synthesize)

POST /v1/synthesize — text-to-speech with automatic provider routing.



Synthesize text into audio. The router picks the best TTS provider for your `(language, optimize_for)` and fails over automatically.

```python
speech = speko.synthesize(
    "Hello world",
    language="en",
)
Path("out.mp3").write_bytes(speech.audio)
```

## Signature [#signature]

<CodeGroup>
  ```python sync
  Speko.synthesize(
      text: str,
      *,
      language: str,
      optimize_for: OptimizeFor | None = None,
      voice: str | None = None,
      speed: float | None = None,
      constraints: PipelineConstraints | dict | None = None,
  ) -> SynthesizeResult
  ```

  ```python async
  await AsyncSpeko.synthesize(
      text: str,
      *,
      language: str,
      optimize_for: OptimizeFor | None = None,
      voice: str | None = None,
      speed: float | None = None,
      constraints: PipelineConstraints | dict | None = None,
  ) -> SynthesizeResult
  ```
</CodeGroup>

## Parameters [#parameters]

<ParamField path="text" type="string">
  The text to synthesize. No client-side length limit — the upstream provider applies its own.
</ParamField>

<ParamField path="language" type="string">
  BCP-47 language tag.
</ParamField>

<ParamField path="optimize_for" type="'balanced' | 'accuracy' | 'latency' | 'cost'" />

<ParamField path="voice" type="string">
  Voice id override. Interpreted per provider (e.g. a Cartesia voice UUID, an ElevenLabs voice id). Omit to use each provider's default.
</ParamField>

<ParamField path="speed" type="float">
  Speech speed multiplier. Providers vary in accepted ranges — `1.0` is always neutral.
</ParamField>

<ParamField path="constraints" type="PipelineConstraints | dict">
  Allow-list constraints.
</ParamField>

## Returns — `SynthesizeResult` [#returns--synthesizeresult]

<ResponseField name="audio" type="bytes">
  Raw audio bytes. Format depends on the chosen provider — always branch on `content_type`.
</ResponseField>

<ResponseField name="content_type" type="string">
  MIME type. ElevenLabs returns `audio/mpeg`. Cartesia returns `audio/pcm;rate=24000`.
</ResponseField>

<ResponseField name="provider" type="string" />

<ResponseField name="model" type="string" />

<ResponseField name="failover_count" type="int">
  Providers tried before this one succeeded.
</ResponseField>

<ResponseField name="scores_run_id" type="string | None" />

## Example — write to disk [#example--write-to-disk]

```python
from pathlib import Path

speech = speko.synthesize(
    "Welcome to the clinic.",
    language="en",
    voice="sonic-english",
)

ext = "mp3" if "mpeg" in speech.content_type else "pcm"
Path(f"greeting.{ext}").write_bytes(speech.audio)
```

## Example — pin a PCM provider [#example--pin-a-pcm-provider]

```python
from spekoai import AllowedProviders, PipelineConstraints

speech = speko.synthesize(
    "Hello",
    language="en",
    constraints=PipelineConstraints(
        allowed_providers=AllowedProviders(tts=["cartesia"]),
    ),
)
# speech.content_type == "audio/pcm;rate=24000"
```

<Warning>
  Downstream consumers that only handle PCM (e.g. older LiveKit pipelines) should pin a PCM provider via `constraints` — or branch on `content_type` before decoding. MP3 from ElevenLabs will otherwise hit your decoder unexpectedly.
</Warning>


# transcribe (/sdk-python/transcribe)

POST /v1/transcribe — speech-to-text with automatic provider routing.



Transcribe an audio payload. The router picks the best STT provider for your `(language, optimize_for)` and fails over automatically.

```python
result = speko.transcribe(
    audio_bytes,
    language="es-MX",
)
print(result.text, result.provider, result.confidence)
```

## Signature [#signature]

<CodeGroup>
  ```python sync
  Speko.transcribe(
      audio: bytes,
      *,
      language: str,
      optimize_for: OptimizeFor | None = None,
      content_type: str = "audio/wav",
      constraints: PipelineConstraints | dict | None = None,
  ) -> TranscribeResult
  ```

  ```python async
  await AsyncSpeko.transcribe(
      audio: bytes,
      *,
      language: str,
      optimize_for: OptimizeFor | None = None,
      content_type: str = "audio/wav",
      constraints: PipelineConstraints | dict | None = None,
  ) -> TranscribeResult
  ```
</CodeGroup>

## Parameters [#parameters]

<ParamField path="audio" type="bytes">
  Raw audio bytes. Providers handle resampling and format conversion — any sample rate works. Wrap `bytearray` / `memoryview` with `bytes(...)` at the call site.
</ParamField>

<ParamField path="language" type="string">
  BCP-47 language tag, e.g. `"en"`, `"es-MX"`, `"ja-JP"`.
</ParamField>

<ParamField path="optimize_for" type="'balanced' | 'accuracy' | 'latency' | 'cost'">
  Preset that biases the weighted score. Server default is `balanced`.
</ParamField>

<ParamField path="content_type" type="string" default="audio/wav">
  MIME type for the request body.
</ParamField>

<ParamField path="constraints" type="PipelineConstraints | dict">
  Allow-list constraints. The router still ranks by score but only considers listed providers.
</ParamField>

## Returns — `TranscribeResult` [#returns--transcriberesult]

<ResponseField name="text" type="string">
  Transcribed text.
</ResponseField>

<ResponseField name="provider" type="string">
  Upstream provider that ran the request.
</ResponseField>

<ResponseField name="model" type="string">
  Provider-specific model identifier.
</ResponseField>

<ResponseField name="confidence" type="float | None">
  Model-reported confidence when available.
</ResponseField>

<ResponseField name="failover_count" type="int">
  Number of providers tried before this one succeeded.
</ResponseField>

<ResponseField name="scores_run_id" type="string | None">
  ID of the scoring run that selected this provider — useful for joining to benchmark data.
</ResponseField>

## Example — non-default MIME + allow-list [#example--non-default-mime--allow-list]

```python
from pathlib import Path

from spekoai import AllowedProviders, PipelineConstraints, Speko

speko = Speko(api_key="sk_live_...")

audio = Path("call.ogg").read_bytes()
result = speko.transcribe(
    audio,
    language="en",
    optimize_for="accuracy",
    content_type="audio/ogg",
    constraints=PipelineConstraints(
        allowed_providers=AllowedProviders(stt=["deepgram", "assemblyai"]),
    ),
)
```

## Wire format [#wire-format]

The audio ships as the raw HTTP body. The routing intent and constraints travel in two headers so no server-side re-parsing of the body is needed:

* `Content-Type`: value of `content_type` (default `audio/wav`).
* `X-Speko-Intent`: compact JSON `{"language", "optimizeFor"?}`.
* `X-Speko-Constraints`: compact JSON when `constraints` is set.

The response is a JSON `TranscribeResult`.

## Provider params (API-level) [#provider-params-api-level]

`POST /v1/transcribe` also accepts `workload`, `diarization`, `speakersExpected`, `smartFormat`, `fillerWords`, `profanityFilter`, `wordTimestamps`, and `providerOptions` in the `X-Speko-Stt-Options` header. The typed client does not expose these yet - call the endpoint directly to use them:

```python
import httpx, json

res = httpx.post(
    "https://api.speko.dev/v1/transcribe",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "audio/wav",
        "X-Speko-Intent": json.dumps({"language": "en-US"}),
        "X-Speko-Stt-Options": json.dumps(
            {"workload": "transcription", "wordTimestamps": True}  # done.words = [{text, start, end}] in seconds
        ),
        # wordTimestamps is demote-class: pin the model that serves it, or the
        # request answers 422 no_capable_provider.
        "X-Speko-Constraints": json.dumps(
            {"allowedProviders": {"stt": ["gemini:gemini-3.5-transcribe"]}}
        ),
    },
    content=audio,
)
# Response is the SSE stream (meta / transcript / done events); the done
# event carries effectiveParams + warnings when these fields are used.
```

Field semantics, per-provider params, and failover behavior: [Provider params](/concepts/provider-params) and the [batch transcription guide](/guides/transcription).


# usage (/sdk-python/usage)

GET /v1/usage — billing and usage reporting.



Usage summary for the current billing period. Exposed via `speko.usage`.

```python
summary = speko.usage.get()
print(summary.total_sessions, summary.total_minutes, summary.total_cost)
print(summary.balance_usd)
```

## Signature [#signature]

<CodeGroup>
  ```python sync
  Speko.usage.get(
      *,
      from_date: str | None = None,
      to_date: str | None = None,
  ) -> UsageSummary
  ```

  ```python async
  await AsyncSpeko.usage.get(
      *,
      from_date: str | None = None,
      to_date: str | None = None,
  ) -> UsageSummary
  ```
</CodeGroup>

Both parameters accept ISO-8601 dates or datetimes. Omit either to default to the current billing period.

## Returns — `UsageSummary` [#returns--usagesummary]

<ResponseField name="total_sessions" type="int" />

<ResponseField name="total_minutes" type="float" />

<ResponseField name="total_cost" type="float">
  Total cost in USD over the range.
</ResponseField>

<ResponseField name="breakdown" type="list[UsageByProvider]">
  Per-provider rollup — see below.
</ResponseField>

<ResponseField name="balance_usd" type="float">
  Current organization balance in USD.
</ResponseField>

<ResponseField name="currency" type="'USD'" />

### `UsageByProvider` [#usagebyprovider]

<ResponseField name="provider" type="string" />

<ResponseField name="type" type="'stt' | 'llm' | 'tts'">
  Modality.
</ResponseField>

<ResponseField name="metric" type="string">
  Billable unit (e.g. `minutes`, `characters`, `tokens`).
</ResponseField>

<ResponseField name="key_source" type="'BYOK' | 'MANAGED'">
  `BYOK` = customer key, no Speko margin. `MANAGED` = platform key, billed to the org.
</ResponseField>

<ResponseField name="quantity" type="float" />

<ResponseField name="cost" type="float">
  Cost in USD for this row.
</ResponseField>

## Example — last 24 hours [#example--last-24-hours]

```python
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
yesterday = now - timedelta(hours=24)

summary = speko.usage.get(
    from_date=yesterday.isoformat(),
    to_date=now.isoformat(),
)

for row in summary.breakdown:
    print(f"{row.type}\t{row.provider}\t{row.quantity}{row.metric}\t${row.cost}")
```


# Agents (/concepts/agents)

Reusable voice personas — system prompt, voice, and intent defaults that any session can be started against.



An **Agent** is a persisted persona record on Speko. It bundles the values you'd otherwise have to repeat on every session create:

* `systemPrompt` — the agent's instructions
* `voice` — TTS voice id (provider-specific)
* `intent` — `language` and optional `optimizeFor` (`latency` / `quality` / `cost`)
* `llmOptions` — optional `temperature`, `maxTokens`, `model`
* `stackPreferences` — optional per-layer allowlists (which STT, LLM, TTS, or S2S providers the router is allowed to pick)
* `languageRouting` — optional per-language greetings, mailbox lines, prompts, and voices

Once created, an agent is referenced by id (e.g. `agent_a1b2c3d4e5f60718`) when starting a voice session. Per-call body fields still override the agent's stored defaults — agents are sensible defaults, not a wall.

## When to use an agent [#when-to-use-an-agent]

Use one when the same persona is starting more than one session — that is, almost always in production. Without an agent, every `POST /v1/sessions` ships the full config inline; with an agent, you ship just `{ agentId }`.

```diff
- POST /v1/sessions
- { "mode": "cascade", "intent": { "language": "en" }, "voice": "...", "systemPrompt": "...", ... }
+ POST /v1/sessions
+ { "mode": "cascade", "agentId": "agent_a1b2c3d4e5f60718" }
```

Per-call overrides are still allowed and still win, so you can pin the persona without giving up per-call tweaks (a different voice for a single VIP user, a longer system prompt for a high-stakes call, etc.).

## Stack preferences [#stack-preferences]

Speko's default behavior is auto-routing — for each session, the highest-scoring provider per pipeline layer (STT, LLM, TTS) is picked from every benchmarked option. **Stack preferences** narrow that pool per agent, so you can express opinions like "this agent's STT must be Deepgram or AssemblyAI" or "LLM must be OpenAI or Anthropic" without giving up auto-routing or failover within the allowed set.

```json
{
  "stackPreferences": {
    "allowedProviders": {
      "stt": ["deepgram", "assemblyai"],
      "llm": ["openai", "anthropic"],
      "tts": ["cartesia", "elevenlabs"],
      "s2s": ["openai", "google", "xai"]
    }
  }
}
```

### Vendor vs model entries [#vendor-vs-model-entries]

Each entry in an `allowedProviders` list is either a vendor id (allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Both forms can be mixed in the same array. Failover stays active across all entries in the layer.

```json
{
  "stackPreferences": {
    "allowedProviders": {
      "stt": ["deepgram:nova-3", "assemblyai"],
      "llm": ["openai:gpt-5", "anthropic"],
      "tts": ["elevenlabs:eleven_flash_v2_5"],
      "s2s": ["openai:gpt-realtime-2.1", "google:gemini-3.1-flash-live-preview"]
    }
  }
}
```

Reading that example: STT must be Deepgram's Nova-3 specifically, or any model from AssemblyAI. LLM must be OpenAI's GPT-5 specifically, or any model from Anthropic. TTS must be ElevenLabs' `eleven_flash_v2_5`. Provider-direct S2S may use OpenAI `gpt-realtime-2.1` or Gemini Live `gemini-3.1-flash-live-preview`.

`["deepgram:nova-3", "deepgram:nova-2"]` is also valid — that pins to two specific Deepgram models, with no fallback to other Deepgram models within the vendor (failover to other allowed vendors still applies). Use `GET /v1/providers/known` to enumerate every `(vendor, model)` pair the router knows about — the `id` field on each entry is the verbatim string to put here.

Rules of thumb:

* **Empty / missing layer = no constraint.** A `stt` allowlist of `[]` (or absent entirely) means the router has full freedom for STT.
* **Failover stays active within the allowed set.** If you allowlist Deepgram + AssemblyAI for STT, and Deepgram errors mid-call, the router will fail over to AssemblyAI rather than to a non-allowed provider. The same holds across model-level entries — `["deepgram:nova-3", "assemblyai"]` will fail over from Nova-3 to AssemblyAI.
* **Per-call overrides win per layer.** When you start a session with both an `agentId` *and* an inline `constraints.allowedProviders.stt`, the per-call `stt` list replaces the agent's `stt` list — but the agent's `llm` and `tts` lists still apply unless those are also overridden.
* **Empty allowlist with no fallback fails to route.** If you allowlist a provider that has no benchmark data, the router can't rank it; the session will error rather than silently picking an alternative.

Stack preferences are configured per agent — either via the dashboard's **Stack preferences** section on the Persona tab, or via `stackPreferences` in `POST /v1/agents` / `PATCH /v1/agents/{id}`.

## Languages [#languages]

An agent's `intent.language` sets its base language. Add `languageRouting` when one agent has to handle more than one. Each entry in `languageRouting.languages[]` carries that language's greeting, mailbox line, system prompt, voice and provider pins, for up to four languages. Mid-call switching is a separate control: `enabled` arms it, and the text table still applies with it off.

[Multilingual agents](/guides/multilingual-agents) has the worked example.

## Session history [#session-history]

Every session started with `agentId` in `POST /v1/sessions` is linked to that agent at create time. The dashboard surfaces them under the **Sessions** tab on the agent's detail page; the API equivalent is `GET /v1/sessions?agent=<id>`, which scopes the standard sessions list down to that agent's calls and combines with the existing `cursor`, `status`, `kind`, and `limit` filters.

The link is read-only — sessions are not retroactively attached to an agent, only at create time.

## Tools live under agents [#tools-live-under-agents]

Every tool you register is scoped to a specific agent — the unique key is `(organization, agentId, toolName)`. This means:

* Different agents in the same org can register tools with the same name (`lookup_user`, `book_appointment`) without colliding.
* Adding a tool to one agent doesn't expose it to your other agents.
* The voice worker fetches `GET /v1/agents/{agentId}/tools` at session start to assemble the tool list.

Manage tools from the **Tools** tab inside an agent's detail page in the dashboard, or via the `/v1/agents/{id}/tools` API.

## Lifecycle [#lifecycle]

| Operation | Endpoint                 | Notes                                                                                              |
| --------- | ------------------------ | -------------------------------------------------------------------------------------------------- |
| Create    | `POST /v1/agents`        | Returns the new id. Names are display-only and need not be unique — the `id` identifies the agent. |
| List      | `GET /v1/agents`         | Returns every agent in the calling key's organization.                                             |
| Read      | `GET /v1/agents/{id}`    | 404 if not found / not in your org.                                                                |
| Update    | `PATCH /v1/agents/{id}`  | Partial — send only the fields you want to change.                                                 |
| Delete    | `DELETE /v1/agents/{id}` | Also removes the agent's tools. The organization's only remaining agent cannot be deleted.         |

## The `Default` agent [#the-default-agent]

When your organization is created, Speko seeds a single agent named `Default` so you have something to point at on day one. It's a regular agent in every respect — rename it, edit its system prompt, voice, and intent, or delete it after you create another agent. Speko only prevents deleting the last remaining agent in an organization.

## Where to next [#where-to-next]

<CardGroup cols="2">
  <Card title="Browser SDK" icon="react" href="/client/voice-conversation">
    Browser-side WebRTC using a short-lived session token minted by your server.
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://platform.speko.ai/agents">
    Manage agents and their tools from the web dashboard.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference/agents-create">
    Full request/response shapes for the `/v1/agents` endpoints.
  </Card>
</CardGroup>


# Bring your own keys (/concepts/byok)

Use your own provider credentials. Speko routes; providers bill you directly.



By default, calls run against Speko-managed provider credentials and roll up to a single Speko bill. With BYOK (Bring Your Own Keys) you supply your own API keys per provider — Speko still picks the best provider per call, but the provider charges *you*.

## Why BYOK [#why-byok]

* **Existing volume discount.** You already have negotiated rates with Deepgram, OpenAI, ElevenLabs, etc.
* **Compliance.** You hold the contract / DPA / BAA with the provider directly.
* **Spend visibility.** Provider invoices land in your existing billing.

## Configure [#configure]

Open [Provider keys](https://platform.speko.ai/settings/provider-keys). Paste each provider's API key. Speko stores secrets encrypted at rest and uses them only for your organization's traffic.

Programmatic equivalent: `PUT /v1/providers` with `{ provider, apiKey }`.

```bash
curl -X PUT https://api.speko.dev/v1/providers \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "deepgram", "apiKey": "..." }'
```

Remove a key with `DELETE /v1/providers/:provider`. The provider falls back to platform-managed credentials.

## How the router resolves credentials [#how-the-router-resolves-credentials]

For each call, the router picks the highest-ranked provider for the intent (subject to constraints), then asks the secrets store: "do we have an org-scoped key for this provider?"

* **Yes** → use the BYOK key. Failover candidates that lack BYOK keys fall through to platform-managed credentials if those exist.
* **No** → use platform-managed credentials. If none configured, that candidate is skipped.

## Inspect status [#inspect-status]

`GET /v1/providers` returns each known provider plus a `configured` flag and a `source` of `null` (platform-managed) or `"BYOK"`. The same status is shown in [Provider keys](https://platform.speko.ai/settings/provider-keys).

## Supported providers [#supported-providers]

* **STT**: Deepgram, AssemblyAI
* **LLM**: OpenAI
* **TTS**: ElevenLabs, Cartesia

The list grows. `GET /v1/providers/known` is the source of truth.


# Failover (/concepts/failover)

How Speko transparently retries against runner-up providers when the primary fails.



Every routing decision returns a primary `SelectedCandidate` plus an ordered `runnersUp` list — the next-best providers for the same intent. If the primary throws, Speko retries against the next candidate. From the caller's perspective: one request, one response. From the response: `failoverCount` tells you how many providers it tried before one succeeded.

## What counts as a failure [#what-counts-as-a-failure]

A candidate is considered failed if it:

* Throws a network or 5xx error.
* Returns no transcript / no audio / no completion text.
* Errors mid-stream.

Auth errors against BYOK keys also fail — Speko advances to the next candidate without retrying the current one.

## What does not retry [#what-does-not-retry]

* **4xx caller errors** (bad audio, malformed request, missing intent header) — returned to the caller immediately. Failover doesn't help when the input is wrong.
* **Auth errors against the Speko gateway itself** — your API key is invalid; that's not a routing problem.

## All candidates exhausted [#all-candidates-exhausted]

If every candidate in the failover chain fails, Speko returns `ALL_PROVIDERS_FAILED` with a list of the underlying errors. This is rare in practice and usually signals a wide-scale outage or an over-restrictive `constraints.allowedProviders` list.

## Observability [#observability]

* Response body: `failoverCount`, `provider`, `model`, `scoresRunId`.
* Response headers: `X-Speko-Failover-Count`, `X-Speko-Provider`, `X-Speko-Model`, `X-Speko-Scores-Run-Id`.
* Server logs: `[transcribe] failover deepgram/nova-2 → assemblyai/best: <error>`.

If you see consistent non-zero `failoverCount` for a specific intent, check the dashboard provider grid — a BYOK key might be misconfigured, or a provider might be degraded for your region.


# Provider params (/concepts/provider-params)

Canonical STT/TTS fields, provider-scoped providerOptions, workload defaults, and how params behave across failover.



Routing picks the provider; provider params tune what that provider does. There are two layers:

* **Canonical fields (L1)** - one cross-provider name, translated to each vendor's wire param by Speko.
* **`providerOptions` (L2)** - provider-scoped passthrough, validated against Speko's param registry. A provider's options apply only when that provider serves the request.

## Where params are accepted [#where-params-are-accepted]

| Surface                                                                          | Fields                                                                                                                                          | Validated as |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `POST /v1/transcribe` - `X-Speko-Stt-Options` header (JSON, max 4 KB)            | `workload`, `diarization`, `speakersExpected`, `smartFormat`, `fillerWords`, `profanityFilter`, `providerOptions` (plus `keywords`, `language`) | `batch`      |
| `WS /v1/transcribe/stream` - config frame                                        | same STT request fields; `diarization` has no streaming mapping yet                                                                             | `streaming`  |
| `POST /v1/synthesize` - body                                                     | `workload`, `providerOptions`                                                                                                                   | `streaming`  |
| `/v1/sessions`, `/v1/sessions/phone`, `/v1/agents` - `sttOptions` / `ttsOptions` | same STT request fields; `diarization` is batch-only; TTS: `workload`, `providerOptions` (`providerOptions` capped at 2 KB serialized)          | `streaming`  |

Each `providerOptions` param in the registry declares the surfaces it supports. Sending one on the wrong surface is rejected with `unsupported_surface` - for example Deepgram's streaming-only `endpointing` on `/v1/transcribe`. Canonical fields use the failover rules below; `diarization` currently has batch mappings only.

## Canonical fields (L1) [#canonical-fields-l1]

| Field              | Type    | Meaning                                                      | When a candidate cannot serve it |
| ------------------ | ------- | ------------------------------------------------------------ | -------------------------------- |
| `diarization`      | boolean | Separate speakers in a batch transcript                      | demote (candidate excluded)      |
| `speakersExpected` | integer | Hint of how many speakers to expect                          | drop                             |
| `smartFormat`      | boolean | Provider-side formatting (punctuation, casing, numbers)      | drop                             |
| `fillerWords`      | boolean | Keep filler words ("um", "uh") instead of removing them      | drop                             |
| `profanityFilter`  | boolean | Mask profanity in the transcript                             | drop                             |
| `wordTimestamps`   | boolean | Per-word `start`/`end` timings in the `done` frame's `words` | demote (candidate excluded)      |

Per-provider wire mapping:

| Field              | Provider   | Wire param                                              | Surfaces         |
| ------------------ | ---------- | ------------------------------------------------------- | ---------------- |
| `diarization`      | Deepgram   | `diarize`                                               | batch            |
| `diarization`      | AssemblyAI | `speaker_labels`                                        | batch            |
| `diarization`      | ElevenLabs | `diarize`                                               | batch            |
| `diarization`      | Soniox     | `enable_speaker_diarization`                            | batch            |
| `diarization`      | Google     | `diarizationConfig`                                     | batch            |
| `speakersExpected` | AssemblyAI | `speakers_expected`                                     | batch            |
| `speakersExpected` | ElevenLabs | `num_speakers`                                          | batch            |
| `speakersExpected` | Google     | `diarizationConfig.maxSpeakerCount`                     | batch            |
| `smartFormat`      | Deepgram   | `smart_format`                                          | streaming, batch |
| `smartFormat`      | AssemblyAI | `format_text` + `punctuate` (streaming: `format_turns`) | batch            |
| `smartFormat`      | Google     | `features.enableAutomaticPunctuation`                   | streaming, batch |
| `smartFormat`      | xAI        | `format`                                                | batch            |
| `fillerWords`      | Deepgram   | `filler_words`                                          | streaming, batch |
| `fillerWords`      | AssemblyAI | `disfluencies`                                          | batch            |
| `profanityFilter`  | Deepgram   | `profanity_filter`                                      | streaming, batch |
| `profanityFilter`  | AssemblyAI | `filter_profanity`                                      | batch            |
| `wordTimestamps`   | Gemini     | `mode.timestamp_granularities: ["word"]`                | batch            |

`diarization` and `wordTimestamps` are batch-only. Either one makes the `done` frame carry `words`: an array of `{ text, start, end, confidence?, speaker? }` with `start`/`end` in **seconds** from the start of the audio (multiply by 1000 for subtitle cue times). `wordTimestamps` is served by `gemini-3.5-transcribe` today; Gemini cannot combine it (or diarization) with `keywords`, so the term list is dropped for that request, and Google caps timestamped audio at 30 minutes. &#x2A;*Pin that model to use it.** A demote-class field excludes candidates that cannot serve it rather than selecting one that can, and automatic routing does not rank the pre-recorded Gemini row, so an unpinned request answers `422 no_capable_provider`:

```bash
-H 'X-Speko-Stt-Options: {"wordTimestamps":true}' \
-H 'X-Speko-Constraints: {"allowedProviders":{"stt":["gemini:gemini-3.5-transcribe"]}}'
```

The [Router](/relay/stt/batch) needs no pin — its automatic routing filters candidates on the capability itself. Streaming speaker forwarding is not exposed yet. Speaker labels from diarization-capable providers are normalized to `S0`, `S1`, ... on word-level output, regardless of the vendor's native labeling.

Deepgram Flux models deliberately accept none of the canonical or provider-specific params in these tables.

## providerOptions (L2) [#provideroptions-l2]

```json
{
  "providerOptions": {
    "deepgram": { "dictation": true },
    "elevenlabs": { "timestamps_granularity": "word" }
  }
}
```

* Keys are provider ids; each inner object is validated against the registry tables below.
* Unknown providers, unknown params, wrong types, invalid enum values, and numbers outside a strict 0-1 range return `400` `invalid_provider_options` with per-param details.
* Numbers outside a documented non-unit range pass through with an `out_of_range` warning - the provider decides.
* A provider's options apply only when that provider serves the request. On failover they never cross to the winning provider; the losing provider's dict is discarded.
* Options for a provider outside your `allowedProviders` pins produce a `provider_not_pinned` warning; they still apply if routing picks that provider.
* Spelling a canonical field inside `providerOptions` while also setting it at the top level (for example `providerOptions.deepgram.diarize` next to `diarization`, or `voice_settings.speed` next to `speed`) is rejected as `canonical_collision` - set one spelling.

### STT params [#stt-params]

| Provider   | Param                                    | Type    | Values              | Surfaces         | Effect                                                              |
| ---------- | ---------------------------------------- | ------- | ------------------- | ---------------- | ------------------------------------------------------------------- |
| Deepgram   | `punctuate`                              | boolean |                     | streaming, batch | Adds punctuation and capitalization to transcripts.                 |
| Deepgram   | `numerals`                               | boolean |                     | streaming, batch | Formats spoken numbers as numerals in supported languages.          |
| Deepgram   | `endpointing`                            | integer | 10-2000             | streaming        | Silence duration in milliseconds before speech finalization.        |
| Deepgram   | `utterance_end_ms`                       | integer | 1000-5000           | streaming        | Word-gap duration in milliseconds before an UtteranceEnd event.     |
| Deepgram   | `vad_events`                             | boolean |                     | streaming        | Emits speech-start voice activity events.                           |
| Deepgram   | `detect_language`                        | boolean |                     | batch            | Detects the dominant language of each channel.                      |
| Deepgram   | `dictation`                              | boolean |                     | streaming, batch | Converts spoken dictation commands into punctuation and layout.     |
| Deepgram   | `measurements`                           | boolean |                     | streaming, batch | Formats spoken measurement units as abbreviations.                  |
| AssemblyAI | `end_of_turn_confidence_threshold`       | number  | 0-1                 | streaming        | Sets the confidence threshold for semantic end-of-turn detection.   |
| AssemblyAI | `min_end_of_turn_silence_when_confident` | integer | 0-5000              | streaming        | Sets the minimum confident end-of-turn silence in milliseconds.     |
| AssemblyAI | `max_turn_silence`                       | integer | 100-10000           | streaming        | Sets the maximum silence in milliseconds before forcing a turn end. |
| AssemblyAI | `format_turns`                           | boolean |                     | streaming        | Formats final streaming turns with punctuation and casing.          |
| AssemblyAI | `multichannel`                           | boolean |                     | batch            | Transcribes each channel of a recording separately.                 |
| AssemblyAI | `language_detection`                     | boolean |                     | batch            | Detects the language of a prerecorded transcript.                   |
| ElevenLabs | `vad_silence_threshold_secs`             | number  | 0.3-3               | streaming        | Sets the VAD silence duration in seconds before committing a turn.  |
| ElevenLabs | `tag_audio_events`                       | boolean |                     | batch            | Includes non-speech audio event tags in the transcript.             |
| ElevenLabs | `timestamps_granularity`                 | enum    | `word`, `character` | batch            | Selects word- or character-level transcript timestamps.             |
| Soniox     | `enable_language_identification`         | boolean |                     | streaming, batch | Includes detected language information on transcript tokens.        |

Google and xAI expose only the canonical fields above. OpenAI and Cartesia expose no tunable STT params yet.

### TTS params [#tts-params]

| Provider   | Param                      | Type    | Values              | Effect                                                              |
| ---------- | -------------------------- | ------- | ------------------- | ------------------------------------------------------------------- |
| ElevenLabs | `voice_settings`           | object  | see below           | Overrides the selected voice's per-request generation settings.     |
| ElevenLabs | `apply_text_normalization` | enum    | `auto`, `on`, `off` | Controls provider-side text normalization.                          |
| MiniMax    | `volume`                   | number  | 0.5-2               | Controls output volume multiplier.                                  |
| MiniMax    | `pitch`                    | integer | -12 to 12           | Shifts pitch by semitones.                                          |
| Cartesia   | `speed`                    | number  | 0.6-1.5             | Controls speaking-rate multiplier. Collides with top-level `speed`. |
| Cartesia   | `volume`                   | number  | 0.5-2               | Controls output volume multiplier.                                  |
| Fish Audio | `latency`                  | enum    | `normal`, `low`     | Selects normal quality or low-latency generation.                   |
| Bland      | `expressiveness`           | number  | 0-1                 | Controls expressive variation in generated speech.                  |
| Bland      | `stability`                | number  | 0-1                 | Controls consistency in generated speech.                           |

`voice_settings` (ElevenLabs) properties:

| Property            | Type    | Values  | Effect                                                               |
| ------------------- | ------- | ------- | -------------------------------------------------------------------- |
| `stability`         | number  | 0-1     | Controls consistency versus expressive variation.                    |
| `similarity_boost`  | number  | 0-1     | Controls similarity to the source voice.                             |
| `style`             | number  | 0-1     | Controls style exaggeration.                                         |
| `use_speaker_boost` | boolean |         | Enables additional speaker-similarity processing.                    |
| `speed`             | number  | 0.7-1.2 | Speaking-rate multiplier. Collides with top-level `speed` - set one. |

## Failover behavior [#failover-behavior]

* **Drop-class params** are omitted for a candidate that cannot serve them. The request still runs; the omission is reported as a `param_dropped` warning and the param is absent from `applied`.
* **Demote-class params** (`diarization`) remove incapable candidates from the failover ladder before the first attempt, each reported as a `candidate_excluded` warning. If no candidate remains, the request fails with `422` `{ "error": "no_capable_provider", "param": "diarization" }` instead of silently running without the capability.

When a request carries any of the new fields, the response reports what actually applied:

* `/v1/transcribe`: the final `done` SSE event gains `effectiveParams: { provider, model, applied, defaultsVersion }`, plus `warnings` when non-empty.
* `/v1/transcribe/stream`: a `metadata` frame after `ready` carries the same object.
* `/v1/synthesize`: response headers `X-Speko-Applied-Params` (JSON array of param names) and `X-Speko-Warnings` (JSON array, capped at 2 KB).

Requests without any of the new fields get byte-identical responses to before these fields existed.

## Workload defaults [#workload-defaults]

`workload: 'conversation' | 'transcription' | 'narration'` applies per-provider defaults from the registry. Defaults are presence-keyed: no `workload`, no defaults. Explicit fields always override defaults. Responses echo `defaultsVersion` (currently `2026-08-06`) so a registry change is visible.

| Modality | Provider   | Workload        | Defaults applied                                                                      |
| -------- | ---------- | --------------- | ------------------------------------------------------------------------------------- |
| STT      | Deepgram   | `conversation`  | `smartFormat: false`, `punctuate: true`, `fillerWords: true`, `vad_events: true`      |
| STT      | Deepgram   | `transcription` | `smartFormat: true`                                                                   |
| STT      | AssemblyAI | `conversation`  | `format_turns: true`                                                                  |
| STT      | AssemblyAI | `transcription` | `smartFormat: true`                                                                   |
| STT      | ElevenLabs | `transcription` | `timestamps_granularity: "word"`, `tag_audio_events: false`                           |
| TTS      | ElevenLabs | `narration`     | `voice_settings: { stability: 0.5, similarity_boost: 0.75, use_speaker_boost: true }` |

A default only applies when the candidate's surface and model support the param. On `/v1/synthesize`, `workload: "narration"` additionally prefers a 24 kHz output ladder when the request sets no `sampleRate` and at least one candidate serves that rate.

## Use-case vocabulary [#use-case-vocabulary]

Three vocabularies coexist on different surfaces:

| Router key `useCase`                            | Platform `workload` | Vertical `useCaseId` (`/v1/recommend-stack`) |
| ----------------------------------------------- | ------------------- | -------------------------------------------- |
| `phone_agent`                                   | `conversation`      | any of the 10 vertical profiles              |
| `realtime_agent` (UI: "In-app voice assistant") | `conversation`      | any of the 10 vertical profiles              |
| `transcription`                                 | `transcription`     | -                                            |
| `voice_content` (UI: "Narration")               | `narration`         | -                                            |
| `translation`, `other` (legacy, API-only)       | -                   | -                                            |

Vertical profiles: `customer-support`, `sales-outbound`, `healthcare`, `telephony-receptionist`, `voice-assistant`, `education-tutoring`, `restaurant-ordering`, `mental-health-coaching`, `legal-intake`, `financial-banking-ivr`.

Guides: [Batch transcription](/guides/transcription), [Narration](/guides/narration).


# How routing works (/concepts/routing)

Intent + benchmark scores → ranked candidates → live failover. The model behind every Speko call.



Speko continuously benchmarks every supported STT, LLM, TTS, and S2S provider across language and region. Every API call carries a `RoutingIntent`. The router applies hard filters, normalizes the surviving candidates against each other, picks the top-ranked provider, and falls back through runners-up if the primary fails.

## Intent [#intent]

```ts
type RoutingIntent = {
  language: string;          // BCP-47, e.g. "en-US", "es-MX"
  region?: string;           // 'global' | 'us-east4' | 'europe-west3' | 'asia-southeast1' (default: 'global')
  optimizeFor?: 'balanced' | 'accuracy' | 'latency' | 'cost'; // default: balanced
};
```

`language` is required. `region` selects which streaming-latency measurements the router uses; it defaults to `'global'`. If a provider only published a `global` row (typical for batch endpoints), Speko falls back to that row when no per-region data matches your intent. The TypeScript SDK exposes `region` on `RoutingIntent`; raw HTTP callers send the same value in `X-Speko-Intent`.

`optimizeFor` chooses a weight preset that biases the per-modality composite. Defaults are tuned for production-leaning balance:

| Modality | Quality axis                      | Latency axis            | Cost axis                                                  |
| -------- | --------------------------------- | ----------------------- | ---------------------------------------------------------- |
| **STT**  | WER (lower is better)             | TTFP p50 by region      | $/min                                                      |
| **TTS**  | Round-trip CER                    | TTFB p50 by region      | $/min (chars-billed providers converted via 900 chars/min) |
| **LLM**  | Quality score                     | TTFT p50                | Blended $/1M tokens                                        |
| **S2S**  | Task-success % (higher is better) | Tool-call p50 by region | $/min                                                      |

`balanced` weights for STT/TTS are `0.5 quality / 0.3 latency / 0.2 cost`. S2S is `0.4 / 0.4 / 0.2` (success and turn-latency carry equal weight). LLM is `0.5 / 0.3 / 0.2`. The other presets shift weight toward their named axis.

## Selection [#selection]

For each modality the selector:

1. Filters to providers with measurements for `(language, region)`. If no region-specific row exists, falls back to `region='global'` rows.
2. Applies hard filters from the active routing policy: e.g. STT drops anything above `max_ttfp_p50_ms = 3000`; all modalities exclude providers with `status='warned'`.
3. Min-max-inverts each axis over the surviving candidate set, so scores are relative to who's still in the running, not to a fixed scale.
4. Computes the weighted composite, sorts, and returns the top candidate plus an ordered `runnersUp` list.

Providers shipping with `status='provisional'` (scaffolded but not measured) and `status='warned'` (measured but flagged unsafe to route to) are visible in the admin UI but excluded from selector output.

Each call returns `scoresRunId` — the benchmark snapshot the decision was based on. Useful for audit and bug repro.

## Failover [#failover]

The runners-up are the next-best providers for your exact intent. If the primary throws, Speko transparently retries the same request against the next candidate. The response includes `failoverCount` (how many providers it tried before one succeeded) and `provider` / `model` (what actually ran).

If every candidate fails, the call returns `ALL_PROVIDERS_FAILED`.

## Constraints [#constraints]

Pin or restrict the candidate pool per modality:

```json
{
  "constraints": {
    "allowedProviders": {
      "stt": ["deepgram"],
      "tts": ["cartesia"],
      "s2s": ["openai"]
    }
  }
}
```

Speko still ranks by composite — it just picks the highest-ranking candidate that's in your allow-list. Use this to:

* Pin a provider while debugging.
* Honor compliance constraints (data residency, BAA coverage).
* Cap costs by excluding premium providers.

Allowlists are model-aware. Each entry is either a vendor id (`"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (`"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Failover stays active across all entries in the layer. Enumerate the valid `id` strings via `GET /v1/providers/known`.

## Voice-aware routing [#voice-aware-routing]

On `/v1/synthesize`, if you pass a `voice` listed by `GET /v1/voices` and did not pin a TTS provider, routing is constrained to the provider or providers that actually offer that voice. Previously the router walked its ranked list and handed the voice id to providers that did not own it. An explicit `allowedProviders.tts` always wins; a voice never overrides your pin, while an unknown custom or cloned voice id routes normally by score. If several providers list the same voice id, all of them stay in the failover ladder.

## Preview before you ship [#preview-before-you-ship]

`GET /v1/benchmarks/stack?language=en&region=us-east4&optimize_for=balanced` returns the current pick per modality plus runners-up, `scoresRunId`, and a `filtered_out[]` list explaining why each excluded candidate was dropped (warned status, missed latency cutoff, missing region data, etc.). No usage is recorded.

## Headers on every response [#headers-on-every-response]

Every `/v1/transcribe`, `/v1/synthesize`, `/v1/complete` response carries:

* `X-Speko-Provider` — provider that handled the request
* `X-Speko-Model` — specific model
* `X-Speko-Failover-Count` — how many providers we tried
* `X-Speko-First-Byte-Ms` - on `/v1/synthesize`, time to first audio from the winning provider only
* `X-Speko-Request-First-Byte-Ms` - on `/v1/synthesize`, time to first audio for the whole request; budget client timeouts against this value
* `X-Speko-Scores-Run-Id` — benchmark snapshot id

Log these. They're how you correlate prod behavior with the routing decision.


# Benchmarks and scoring (/concepts/scoring)

How provider scores are computed and refreshed.



Provider rankings come from a continuously-running benchmark suite. Each provider/model is scored per `(language, region)` on a per-modality basis:

| Modality | Quality axis                          | Latency axis            | Cost axis                                                  |
| -------- | ------------------------------------- | ----------------------- | ---------------------------------------------------------- |
| **STT**  | Word Error Rate (WER)                 | TTFP p50 by region      | $/min (tier-priced)                                        |
| **TTS**  | Round-trip Character Error Rate (CER) | TTFB p50 by region      | $/min (chars-billed providers converted via 900 chars/min) |
| **LLM**  | Quality score                         | TTFT p50                | Blended $/1M tokens                                        |
| **S2S**  | Task-success %                        | Tool-call p50 by region | $/min                                                      |

Composites are computed at query time using **min-max-inverted normalization** over the active candidate set after hard filters. Two consequences worth understanding:

* A provider's score is *relative to the rest of the candidates for your intent*, not a fixed ranking. Adding or removing a candidate (via `constraints.allowedProviders`, status changes, or new ingest) can shift everyone's normalized score.
* Lower-is-better axes (WER, CER, latency, cost) are inverted so higher composite is always better. S2S `task_success_pct` is already higher-is-better and is carried through unchanged.

See [routing](/concepts/routing) for weights per `optimizeFor` preset.

## Provider status [#provider-status]

Every benchmark row carries a `status`:

* **`production`** — measured, in good standing. Eligible for routing.
* **`warned`** — measured, but flagged for a known issue (transcription drift, output instability, etc.). Visible in admin tooling, excluded from routing.
* **`provisional`** — scaffolded but not yet measured. Visible in admin tooling, excluded from routing.

Hard filters drop `warned` and `provisional` candidates before scoring; they never appear in your `runnersUp` list.

## Refresh cadence [#refresh-cadence]

Benchmarks rerun on a schedule and on every benchmark suite update. The active snapshot is identified by `scoresRunId`, returned with every routing decision. Two calls with identical intent within the same snapshot route the same way; across snapshots, a re-ranking can move a different provider into the top spot.

## Health gating [#health-gating]

Hard filters per modality include latency cutoffs (e.g. STT drops candidates above `max_ttfp_p50_ms = 3000`) and the `status != 'warned'` rule above. These run before normalization, so they don't pull other candidates' relative scores around.

## Routing policy [#routing-policy]

Weights and hard filters live in code as defaults (`DEFAULT_STT_POLICY`, `DEFAULT_TTS_POLICY`, `DEFAULT_S2S_POLICY`, `DEFAULT_LLM_POLICY`) and can be overridden per `request_type` via the `routing_policy` table. There can be at most one active policy per modality at a time. Policy changes take effect on the next selector refresh — no re-ingest required.

## Why benchmarks beat a single eval [#why-benchmarks-beat-a-single-eval]

Production traffic is heterogeneous: Spanish healthcare dictation has different leaders than English casual chat, and a provider that wins in `us-east4` can lose badly in `asia-southeast1`. A static "best STT" decision under-serves anything outside the benchmarked happy path. Speko's routing layer means you get the leader *per call*, not per integration choice.

## Inspecting scores [#inspecting-scores]

`GET /v1/benchmarks/stack?language=en&region=us-east4&optimize_for=accuracy` returns the same ranking the router would use, plus `runnersUp[].score` and `filtered_out[]` (with reasons). Use it to debug "why did Speko pick X for this intent?".

## Custom benchmarks [#custom-benchmarks]

Not in v1. Reach out if your traffic doesn't fit our published benchmark suite.


# Sessions vs one-shot (/concepts/sessions)

When to mint a session and when to call a one-shot endpoint directly.



Speko supports two integration shapes. Pick based on whether your call is real-time interactive or single-turn batch.

## One-shot endpoints [#one-shot-endpoints]

`POST /v1/transcribe`, `POST /v1/synthesize`, `POST /v1/complete`. Each is a single round-trip:

* Caller sends input + intent.
* Speko picks a provider, runs the call (with failover), returns the result.

Use for:

* Batch transcription of recorded audio.
* Server-side TTS for notifications, IVR prompts, exports.
* LLM completions in a non-voice flow.

No state is held between calls. There is nothing to clean up.

## Real-time sessions [#real-time-sessions]

`POST /v1/sessions` creates one of two different media paths. Set `mode` explicitly so your client knows which response shape to expect.

### Provider-direct S2S [#provider-direct-s2s]

`mode: "s2s"` reserves a bounded Speko entitlement and returns a scoped, short-lived credential for OpenAI Realtime, Gemini Live, or xAI Grok Voice. The browser passes that response to [`RealtimeVoiceConversation`](/client/realtime-voice-conversation) and connects directly to the selected provider.

The response has `transport: "provider_direct"`, `providerTransport`, `endpoint`, `credential`, `telemetry`, and `reservation` fields. It does not contain LiveKit credentials:

```text
your backend ── create session ──▶ Speko control plane
                                       │
                                       └── scoped credential + entitlement
                                                     │
browser ───────────── WebRTC / WebSocket ───────────▶ provider
```

OpenAI uses WebRTC. Gemini Live and xAI use provider WebSockets. Speko stores content-free lifecycle and billing evidence. The OpenAI sideband observes provider control events but never receives media.

For S2S, `ttlSeconds` requests the maximum session horizon (default 1,800s, max 3,600s). The returned `reservation.authorizedDurationSeconds` may be lower because provider credentials can have shorter lifetimes. Gemini returns renewable slices; the browser client renews and resumes them while the requested horizon and credit authorization permit it.

`Idempotency-Key` is required. Reuse it after an ambiguous bootstrap timeout to recover the same reservation without minting a duplicate credential.

See [Provider-direct speech-to-speech](/guides/realtime-conversation) for a complete browser integration.

### Cascade [#cascade]

`mode: "cascade"` returns a `transportToken`, `transportUrl`, and room name. The browser uses [`VoiceConversation`](/client/voice-conversation) to join LiveKit; Speko dispatches an agent worker into the same room to run the routed STT → LLM → TTS pipeline.

Two separate time controls apply to cascade sessions:

* **`ttlSeconds`** (default 900s, max 86400s) bounds the **join token** only. It does not limit an already-connected session.
* **`maxDurationSeconds`** (default 3600s, min 30s, max 14400s) is the hard cap on **session lifetime**, measured from session creation. Speko force-ends the LiveKit room at the deadline.

The agent worker leaves when the room empties or the max-duration deadline hits. The session row is retained for usage and audit.

### Ending a session [#ending-a-session]

For a cascade session, `POST /v1/calls/{sessionId}/end` tears down the LiveKit room and runs the normal close and metering flow. It is idempotent; ending an already-ended session returns `status: "already_ended"`. SDK: `client.sessions.end(sessionId)` or `client.calls.end(sessionId)`.

For provider-direct S2S, call `RealtimeVoiceConversation.endSession()` (or close the low-level realtime handle) to close the provider connection. The credential and entitlement stay time-bounded even if the client disappears without a final telemetry event.

## Phone sessions [#phone-sessions]

`POST /v1/sessions/phone` creates the same kind of voice session, then dials a PSTN destination over LiveKit SIP. Inbound calls follow the reverse path: a registered phone number receives the carrier webhook, Speko creates the voice session, hydrates the linked agent or dispatch metadata template, and bridges the caller into the room.

Use phone sessions for:

* Outbound appointment reminders, sales calls, and scheduled callbacks.
* Inbound receptionists and support lines.
* Calls that need carrier lifecycle events, forwarded-number metadata, post-call reports, recordings, or live transfers.

See [Build a phone agent](/guides/phone-agents) for the end-to-end phone flow.

## Choosing [#choosing]

| Need                                              | Use                                                                           |
| ------------------------------------------------- | ----------------------------------------------------------------------------- |
| Transcribe a file, return text                    | `/v1/transcribe`                                                              |
| Formatted transcript with diarization             | `/v1/transcribe` + `workload: transcription` ([guide](/guides/transcription)) |
| Generate audio for a notification                 | `/v1/synthesize`                                                              |
| Long-form narration audio                         | `/v1/synthesize` + `workload: narration` ([guide](/guides/narration))         |
| Single LLM reply, no voice                        | `/v1/complete`                                                                |
| Lowest-latency provider-native voice in a browser | `/v1/sessions` with `mode: "s2s"` + `RealtimeVoiceConversation`               |
| Routed STT → LLM → TTS voice agent in a browser   | `/v1/sessions` with `mode: "cascade"` + `VoiceConversation`                   |
| Outbound PSTN voice call                          | `/v1/sessions/phone` or `speko.voice.dial()`                                  |
| Inbound PSTN receptionist                         | `/v1/phone-numbers` linked to an agent                                        |
| Inspect reports, events, recordings, or transfers | `/v1/calls/{id}`                                                              |
| Real-time voice in a self-hosted framework worker | `@spekoai/adapter-livekit` directly, when using LiveKit                       |

## What sessions don't do [#what-sessions-dont-do]

* They aren't a chat history store. Cascade turn context lives in the worker; provider-direct context lives on the provider connection.
* They don't proxy audio through the REST API. S2S audio goes directly to the provider; cascade audio uses the LiveKit media transport.
* Provider-direct S2S reserves and settles a bounded duration entitlement. Cascade usage is recorded from its connected lifetime and underlying routed stages.

## Recording [#recording]

Cascade and phone sessions are recorded by default. The agent worker captures both speakers — caller and agent — into a single mixed-mono Opus file, persisted to Google Cloud Storage at the end of the call. There is no separate "enable recording" call for those modes.

Provider-direct S2S sessions are not recorded by Speko because their media never enters a Speko or LiveKit data path. Their `recordingStatus` is `null`, and `GET /v1/sessions/{id}/recording` has no artifact to return.

What gets captured:

* **Mixed mono Opus.** Both sides of the conversation in one file, \~24 kbps. Stereo / per-speaker tracks are not produced — assume one combined audio stream per session.
* **The full call.** Recording starts when the first participant joins the room and ends when the room empties (participants leave, the session is ended via the API, or the max-duration deadline hits).
* **Audio only.** Tool-call payloads and transcripts are not in the audio file; those live on the session row and the per-turn entries.

How to fetch one:

```bash
curl -L \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  https://api.speko.dev/v1/sessions/$SESSION_ID/recording \
  --output session.opus
```

The endpoint 302-redirects to a short-lived (5 minute) signed GCS URL — pass `-L` so curl follows it. The signed URL is single-use within its TTL window; refetch the endpoint to get a fresh one rather than caching the URL itself.

### The status field [#the-status-field]

Each session entry carries a `recordingStatus` that walks through:

* `pending` — the call ended; the agent worker is assembling the file.
* `uploading` — the file is being pushed to GCS.
* `ready` — fully persisted and downloadable. `recordingObjectPath` and `recordingDurationMs` are populated.
* `failed` — the upload errored. The recording is unrecoverable; the session itself is unaffected.
* `suppressed` — the organization has `recordingEnabled` set to false, so no file was ever produced. This is the terminal state for opted-out orgs; it's not a transient one.
* `discarded` — the call never connected (the session's `endReason` is `sip_dial_rejected` or `sip_no_answer`), so the capture held only an empty room. The file is withheld and `GET /v1/sessions/{id}/recording` returns 404; there was no conversation to play back.

`null` on `recordingStatus` appears on provider-direct S2S sessions and legacy entries that predate recording. Treat it as "not available" and don't expect a download.

### Retention [#retention]

Recordings are kept for **30 days** after the session ends, then deleted automatically by a GCS lifecycle policy. There is no in-product way to extend retention — if you need long-term storage, follow the redirect, download the file, and store it in your own bucket. If you need shorter retention, see the per-org opt-out below.

### Per-org opt-out [#per-org-opt-out]

Recording is governed at the organization level by `organization.recordingEnabled` (default `true`). Flipping it to `false`:

* Stops new sessions from producing files. Their `recordingStatus` becomes `suppressed` and `GET /v1/sessions/{id}/recording` returns 404.
* Does **not** retroactively delete prior recordings — those expire on the normal 30-day timer.

The flag is exposed in the dashboard under the **Record voice sessions** toggle on the Settings page. Per-call opt-out (skipping recording for a single session even when the org default is on) is out of scope for this round.

### HIPAA mode [#hipaa-mode]

Organizations on a HIPAA-mode plan are forced into `recordingEnabled: false` regardless of the dashboard toggle, and the toggle is locked. This is the current bridge until an end-to-end customer-managed-key path lands; see the compliance issue tracker for the full story.

### API endpoint [#api-endpoint]

`GET /v1/sessions/{id}/recording` is the only supported way to retrieve a recording. It authenticates with the same bearer key as every other endpoint and 302-redirects to a 5-minute signed URL on success, or 404 when the session is unknown, the recording is not ready, failed, suppressed, or absent for provider-direct S2S. Inspect the parent session entry's `recordingStatus` to disambiguate. Never construct GCS URLs from `recordingObjectPath` directly — those URLs are not publicly addressable, and the field exists only as an internal handle.

## Transcript [#transcript]

Every finalized STT and LLM turn during a cascade session is persisted server-side. The dashboard's session detail page surfaces them under a Transcript card; the API equivalent is `GET /v1/sessions/{id}/transcript`, which returns turns sorted by index.

The worker batches and debounces (\~200ms) finalized turns and POSTs them to `/v1/sessions/{id}/turns`. The ingest endpoint is idempotent on `(session_id, index)` so retries on transient errors are safe.

Interim STT partials are not persisted — only finalized turns make it into the transcript.

Provider-direct S2S transcripts are available to the connected client through provider events, but Speko does not currently persist them. `GET /v1/sessions/{id}/transcript` therefore returns no S2S turns.


# Workflows (/concepts/workflows)

Steps the agent walks through, and intents that interrupt them from anywhere in the call.



A **workflow** is a graph the agent walks while it talks: named steps, each with a line to say and the branches leading out of it. It replaces the flat system prompt as the source of truth for what happens next.

The difference shows up under pressure. A flat prompt asks a model to remember its agenda while improvising. A workflow makes the agenda structural: the same call runs the same way twice, and every branch is inspectable before you dial.

## Steps [#steps]

Each step carries a `say` line delivered verbatim and an `instruction` for what to do with the answer. Most also declare `slots` — small typed values the model extracts from the caller's reply.

```json
{
  "id": "confirm_time",
  "kind": "message",
  "say": "Does Thursday at 2pm still work for you?",
  "slots": [
    { "key": "keeps_slot", "type": "enum", "enum": ["yes", "no", "question"] }
  ]
}
```

A `say` line is delivered verbatim, so no instruction can make it come out in another language. A step that has to speak in more than one carries `sayByLanguage` and `instructionByLanguage` alongside the base text — see [Multilingual agents](/guides/multilingual-agents#translate-a-step-that-speaks).

Slots are what the step routes on. An edge is a condition plus a destination:

```json
{ "id": "e_ask", "from": "confirm_time", "to": "answer_question",
  "condition": { "type": "expression", "expr": "keeps_slot == 'question'" } }
```

Each step also has one unconditional edge — where the call goes when nothing more specific matches.

## Globals: intents from any step [#globals-intents-from-any-step]

A normal edge belongs to one step. A **global edge** has no `from`, so it is evaluated from every step in the workflow. Declare an intent once and it is live for the whole call.

```json
{
  "globalEdges": [
    { "id": "g_cancel", "to": "cancel_booking",
      "condition": { "type": "llm", "when": "asks to cancel the appointment" } },
    { "id": "g_human", "to": "transfer",
      "condition": { "type": "llm", "when": "asks to speak to a person" } }
  ]
}
```

Without one, a caller can only cancel at the step that happens to ask about it:

```text
agent   Please arrive ten minutes early and bring your insurance card…
caller  Actually, I need to cancel it.
agent   Parking is behind the building, and the entrance is on Oak Street…  ← kept reading its script
caller  I need to cancel the appointment.
agent   Does Thursday at 2pm still work for you?                            ← finally the step that asks
```

With `g_cancel` declared, the same sentence lands wherever it is said:

```text
agent   Please arrive ten minutes early and bring your insurance card…
caller  Actually, I need to cancel it.
agent   No problem — Thursday at 2pm is cancelled. You'll get a text confirming it.
```

A workflow may declare up to **8** global edges.

### Which wins, the step or the global [#which-wins-the-step-or-the-global]

The step's own edges are resolved first, but only on a turn that actually filled one of its slots. If the caller answered the step's question, the step keeps the turn. If they said something else, a matching global takes it.

That ordering matters in both directions. Globals evaluated last are unreachable mid-script. Globals evaluated first steal turns the step understood perfectly well — a caller answering "no" to &#x2A;do you have a referral?* is not cancelling the appointment.

<Note>
  An expression edge pointing at the same step your unconditional edge already
  points at changes no routing, but it does claim the turn — which silently
  suppresses every global from that step. Delete it; the default already goes there.
</Note>

### Excluding a step [#excluding-a-step]

Where a global would misread a step's own answers, name that step in `exceptNodeIds` and the global stops firing there.

```json
{ "id": "g_cancel", "to": "cancel_booking",
  "condition": { "type": "llm", "when": "asks to cancel the appointment" },
  "exceptNodeIds": ["answer_question", "cancel_booking"] }
```

## Reading and writing a workflow [#reading-and-writing-a-workflow]

`GET /v1/agents/{id}/graph` returns the live workflow, its `version`, and a `revision` you send back on write. `PUT` publishes a new one:

```bash
curl -X PUT https://api.speko.ai/v1/agents/$AGENT_ID/graph \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "version": 12, "ifRevision": 3, "graph": { "entryNodeId": "intro", "nodes": [], "edges": [] } }'
```

`version` is the version you edited from. Publishing cuts a new agent version, so a workflow change moves the same number a config change does — which is how `rollback` can reach a previous workflow. A stale `ifRevision` answers `412` rather than overwriting whoever published in between.

## Where to next [#where-to-next]

<CardGroup cols="2">
  <Card title="Agents" icon="user" href="/concepts/agents">
    The persona a workflow runs inside — voice, model and routing defaults.
  </Card>

  <Card title="Tool calling" icon="wrench" href="/guides/tool-calling">
    Give a step a tool so it can read or write your systems mid-call.
  </Card>
</CardGroup>


# List agent calls (/api-reference/agent-calls)

GET /v1/agents/{id}/calls — list recent calls for an agent.



## GET /v1/agents/{id}/calls

List calls for an agent

Returns recent calls whose session pipeline config references this agent. Results are newest first and support cursor pagination.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Agent id.
- `limit` (integer, in query, optional): Default: `50`. Min: 1. Max: 100.
- `cursor` (string (date-time), in query, optional): Use `next_cursor` from the previous page.
- `since` (string (date-time), in query, optional): Only include calls created at or after this timestamp.

### Responses

#### 200: Page of calls

Content type: `application/json`

- `calls` (array of object, required)
  - `id` (string, required)
  - `call_id` (string, required)
  - `resource_uri` (string, required)
  - `agent_id` (string, required)
  - `status` (string, required)
  - `kind` (string, required)
  - `room_name` (string | null, optional)
  - `language` (string, optional)
  - `created_at` (string (date-time), required)
  - `ended_at` (string (date-time) | null, optional)
  - `duration_seconds` (integer | null, optional)
  - `recording_status` (string | null, optional)
- `entries` (array of object, required)
  - `id` (string, required)
  - `call_id` (string, required)
  - `resource_uri` (string, required)
  - `agent_id` (string, required)
  - `status` (string, required)
  - `kind` (string, required)
  - `room_name` (string | null, optional)
  - `language` (string, optional)
  - `created_at` (string (date-time), required)
  - `ended_at` (string (date-time) | null, optional)
  - `duration_seconds` (integer | null, optional)
  - `recording_status` (string | null, optional)
- `next_cursor` (string (date-time) | null, required)

Example:

```json
{
  "calls": [
    {
      "id": "string",
      "call_id": "string",
      "resource_uri": "string",
      "agent_id": "string",
      "status": "string",
      "kind": "string",
      "room_name": "string",
      "language": "string",
      "created_at": "2026-01-01T00:00:00Z",
      "ended_at": "2026-01-01T00:00:00Z",
      "duration_seconds": 0,
      "recording_status": "string"
    }
  ],
  "entries": [
    {
      "id": "string",
      "call_id": "string",
      "resource_uri": "string",
      "agent_id": "string",
      "status": "string",
      "kind": "string",
      "room_name": "string",
      "language": "string",
      "created_at": "2026-01-01T00:00:00Z",
      "ended_at": "2026-01-01T00:00:00Z",
      "duration_seconds": 0,
      "recording_status": "string"
    }
  ],
  "next_cursor": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No agent with this id exists in the authenticated organization.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/agents/{id}/calls' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Agent iMessage (/api-reference/agent-imessage)

Send outbound iMessage-first messages as one of your agents, from its dedicated number.



Agents can be reachable over iMessage: enabling iMessage for an agent on its dashboard page provisions everything automatically, and the agent answers inbound texts on its own. This API adds **outbound** sending — your backend asks a specific agent to message someone first, from the dedicated number that agent answers on.

Use a Speko bearer API key on every request:

```http
Authorization: Bearer sk_live_...
Content-Type: application/json
```

## Prerequisites [#prerequisites]

* iMessage is enabled for the agent (dashboard → agent → iMessage), and
* the agent answers on a **dedicated number** picked from your workspace's number pool (ask Speko to add numbers to your pool).

An agent on the shared router cannot send first — recipients must connect to it before it can reply, and those replies are handled by the agent itself, not this API.

## Send a message [#send-a-message]

```http
POST /v1/imessage/{agentId}/messages
```

```json
{
  "to": "+12015551234",
  "text": "Load 42 is ready for pickup."
}
```

The message is sent as the agent, from its dedicated number. Inkbox attempts iMessage first and may downgrade to SMS asynchronously when the destination has no Apple ID. The response is the same shape as the legacy phone-number send endpoint:

```json
{
  "messageId": "76528fd0-9aeb-43d0-a851-b813fdfaeae0",
  "conversationId": "37f30c7f-565b-45fa-b04c-df29b5af2068",
  "phoneNumberId": "2b3fb8b3-17ef-4e78-b742-69a4ef55c223",
  "to": "+12015551234",
  "attemptedChannel": "imessage",
  "channel": null,
  "fallbackApplied": null,
  "deliveryFinal": false,
  "status": "pending"
}
```

`channel` and `fallbackApplied` stay `null` while the iMessage attempt is unresolved, then become the confirmed transport (`imessage`, `sms`, or `rcs`) and whether a downgrade happened. `deliveryFinal` becomes `true` on `delivered`, `declined`, or `error`. The recipient's reply goes to the **agent**, which answers on its own — no webhook wiring is needed for the conversation to continue.

Do not send a second message when the request succeeds: a pending asynchronous delivery retried through another path can duplicate the send. Retry only failed HTTP requests.

## Errors [#errors]

| Status    | Code                        | Meaning                                                                             |
| --------- | --------------------------- | ----------------------------------------------------------------------------------- |
| `400`     | —                           | Malformed body (`to` must be E.164, `text` 1–18996 chars).                          |
| `403`     | —                           | iMessage integration is not enabled for this workspace.                             |
| `404`     | —                           | The agent does not exist in your workspace.                                         |
| `409`     | `IMESSAGE_NOT_ENABLED`      | The agent has iMessage turned off — enable it first.                                |
| `409`     | `DEDICATED_NUMBER_REQUIRED` | The agent is on the shared router; outbound sends need a dedicated pool number.     |
| `422`     | `UNSUPPORTED_BACKEND`       | The workspace's iMessage backend does not support API sends.                        |
| `4xx/502` | `MESSAGE_SEND_FAILED`       | The provider rejected the send; `providerStatus`/`providerDetail` carry the reason. |

## Sender name [#sender-name]

```http
PUT /v1/imessage/{agentId}/display-name
```

```json
{ "displayName": "Acme Support" }
```

Sets the name recipients see on the thread from this agent. Until they save the number, iPhones show it as **Maybe: Acme Support**; without a name the thread shows only the number. The name lives on the agent's iMessage identity, so it applies to the shared router and to whichever dedicated number the agent holds — switching numbers keeps it. Send `{ "displayName": null }` to clear it. Names are trimmed and limited to 80 characters. The response echoes the stored value:

```json
{ "displayName": "Acme Support" }
```

The same field is accepted on the dashboard's enable call, and the current value is returned as `displayName` on the agent's iMessage status. Setting a name requires the agent's identity to exist — enable iMessage for the agent first (a `409 IMESSAGE_NOT_ENABLED` otherwise). Inkbox is updated before the name is stored, so a `502` means nothing changed.

## Relationship to the phone-number API [#relationship-to-the-phone-number-api]

`POST /v1/imessage-phone-numbers/{phoneNumberId}/messages` is **deprecated** in favor of this endpoint and will be removed on **August 14, 2026**. The agent-scoped form names the agent instead of the raw number, so the conversation and its replies stay with the agent that owns the number.


# Create agent (/api-reference/agents-create)

Persists a reusable voice persona — `systemPrompt`, optional `voice`, routing `intent`, and optional `llmOptions` — keyed by `name` within the authenticated organization. Pass the returned `id` as `agentId` on `POST /v1/sessions` to seed a session from this agent.



## POST /v1/agents

Create an agent

Persists a reusable voice persona — `systemPrompt`, optional `voice`, routing `intent`, and optional `llmOptions` — keyed by `name` within the authenticated organization. Pass the returned `id` as `agentId` on `POST /v1/sessions` to seed a session from this agent.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `name` (string, required): Human-readable display name. Does not need to be unique — agents are identified by `id`.
- `systemPrompt` (string, required): Initial agent instructions used as the session-level `systemPrompt` default.
- `voice` (string, optional): Default TTS voice id. Omit to let the router pick per provider.
- `intent` (object, required): Routing defaults stored on an agent row. Hydrated into a session's `RoutingIntent` when the session is created with `agentId` and no inline `intent`. Note: agents accept a smaller `optimizeFor` enum than the per-session `RoutingIntent`.
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`.
  - `optimizeFor` (string, optional): One of: `"latency"`, `"quality"`, `"cost"`.
- `llmOptions` (object, optional): Optional LLM tuning defaults stored on an agent. Strict object — only these three keys are accepted.
  - `temperature` (number, optional): Min: 0. Max: 2.
  - `maxTokens` (integer, optional): Min: 1.
  - `model` (string, optional): Pin a specific LLM model id. When omitted, the router picks per intent.
- `stackPreferences` (object, optional): Per-agent stack preferences. Empty / missing layers leave the router unconstrained for that layer; failover stays active within the allowed set.
  - `allowedProviders` (object, optional): Per-pipeline-layer provider allowlists (e.g. STT must be Deepgram or AssemblyAI). Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
    - `stt` (array of string, optional): Allowed STT provider entries. Empty / absent = no constraint.
      - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
    - `llm` (array of string, optional): Allowed LLM provider entries. Empty / absent = no constraint.
      - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
    - `tts` (array of string, optional): Allowed TTS provider entries. Empty / absent = no constraint.
      - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
    - `s2s` (array of string, optional): Allowed S2S provider entries. Empty / absent = no constraint.
      - Allowed provider-direct S2S entry. Use a provider id or an exact provider:model pair.
- `turnHandling` (object, optional): Per-agent turn-taking posture, stored on the agent and forwarded to every call it runs. A per-call `turnHandling` on `POST /v1/sessions` or `POST /v1/sessions/phone` REPLACES this object wholesale — the two are not merged per field.
  - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
  - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
    - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
    - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
  - `interruption` (object, optional)
    - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
    - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
    - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
  - `turnDetection` (boolean | string, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection; `"stt"` commits on final transcripts without waiting for acoustic end-of-speech (experimental).
  - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
  - `dtmfToolDescription` (string, optional): Replaces the built-in description the model sees on the `send_dtmf` keypad tool — for steering when and what the agent presses on a specific menu. Only meaningful with the `ivr` profile, which is what creates the tool.
  - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
  - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
  - `onMachine` (string, optional): What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
  - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.
- `backgroundAudio` (object, optional)
  - `ambient` (object, optional)
    - `clip` (string, required): One of: `"office-ambience"`, `"city-ambience"`, `"forest-ambience"`, `"crowded-room"`, `"keyboard-typing"`, `"keyboard-typing2"`.
    - `volume` (number, optional): Min: 0. Max: 16.
- `endCall` (object, optional)
  - `enabled` (boolean, required)
- `firstMessage` (string, optional)
- `idleRePrompts` (object, optional)
  - `enabled` (boolean, required)
  - `delayMs` (integer, optional): Min: 1000. Max: 600000.
  - `maxPrompts` (integer, optional): Min: 1. Max: 10.
  - `messages` (array of string, optional)
- `inboundFirstMessage` (string, optional)
- `languageRouting` (object, optional)
  - `enabled` (boolean, required)
  - `maxDetectionTurns` (integer, optional): Min: 1. Max: 6.
  - `languages` (array of object, required)
    - `language` (string, required)
    - `allowedProviders` (object, optional)
      - `stt` (array of string, optional)
      - `llm` (array of string, optional)
      - `tts` (array of string, optional)
    - `voice` (string, optional)
    - `systemPrompt` (string, optional)
- `outboundFirstMessage` (string, optional)
- `promptVariables` (array of object, optional)
  - `name` (string, required): Pattern: `^[\w-]+(\.[\w-]+)*$`.
  - `defaultValue` (string, optional)
  - `description` (string, optional)
- `runMode` (string, optional): One of: `"cascade"`, `"s2s"`.
- `speechNormalization` (object, optional)
  - `pronunciationDictionary` (object, optional)
  - `textReplacements` (object, optional)
- `sttMissRecovery` (object, optional)
  - `message` (string, optional)
- `sttOptions` (object, optional)
  - `keywords` (array of string, optional)
  - `prompt` (string, optional)
  - `language` (string, optional): Pattern: `^[a-zA-Z][a-zA-Z0-9-]{1,15}$`.
  - `workload` (string, optional): One of: `"conversation"`, `"transcription"`, `"narration"`.
  - `diarization` (boolean, optional)
  - `speakersExpected` (integer, optional): Min: 1. Max: 10.
  - `smartFormat` (boolean, optional)
  - `fillerWords` (boolean, optional)
  - `profanityFilter` (boolean, optional)
  - `providerOptions` (object, optional)
- `ttsOptions` (object, optional)
  - `speed` (number, optional): Min: 0.5. Max: 2.
  - `model` (string, optional)
  - `workload` (string, optional): One of: `"conversation"`, `"transcription"`, `"narration"`.
  - `providerOptions` (object, optional)
- `voiceInstructions` (string, optional)
- `webhooks` (object, optional)
  - `preCall` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
  - `postCall` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
    - `extractionFields` (array of object, optional)
      - `name` (string, required): Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`.
      - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
      - `description` (string, required)
      - `options` (array of string, optional)
  - `status` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
  - `analysis` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
  - `recording` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
- `timezone` (string, optional)
- `extractionFields` (array of object, optional)
  - `name` (string, required): Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)

Example body:

```json
{
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 0,
    "model": "string"
  },
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  },
  "backgroundAudio": {
    "ambient": {
      "clip": "office-ambience",
      "volume": 0
    }
  },
  "endCall": {
    "enabled": true
  },
  "firstMessage": "string",
  "idleRePrompts": {
    "enabled": true,
    "delayMs": 0,
    "maxPrompts": 0,
    "messages": [
      "string"
    ]
  },
  "inboundFirstMessage": "string",
  "languageRouting": {
    "enabled": true,
    "maxDetectionTurns": 0,
    "languages": [
      {
        "language": "string",
        "allowedProviders": {
          "stt": [
            null
          ],
          "llm": [
            null
          ],
          "tts": [
            null
          ]
        },
        "voice": "string",
        "systemPrompt": "string"
      }
    ]
  },
  "outboundFirstMessage": "string",
  "promptVariables": [
    {
      "name": "string",
      "defaultValue": "string",
      "description": "string"
    }
  ],
  "runMode": "cascade",
  "speechNormalization": {
    "pronunciationDictionary": {},
    "textReplacements": {}
  },
  "sttMissRecovery": {
    "message": "string"
  },
  "sttOptions": {
    "keywords": [
      "string"
    ],
    "prompt": "string",
    "language": "string",
    "workload": "conversation",
    "diarization": true,
    "speakersExpected": 0,
    "smartFormat": true,
    "fillerWords": true,
    "profanityFilter": true,
    "providerOptions": {}
  },
  "ttsOptions": {
    "speed": 0,
    "model": "string",
    "workload": "conversation",
    "providerOptions": {}
  },
  "voiceInstructions": "string",
  "webhooks": {
    "preCall": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    },
    "postCall": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0,
      "extractionFields": [
        {
          "name": "string",
          "type": "string",
          "description": "string",
          "options": [
            null
          ]
        }
      ]
    },
    "status": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    },
    "analysis": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    },
    "recording": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    }
  },
  "timezone": "string",
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ]
}
```

### Responses

#### 201: Agent created

Content type: `application/json`

- `id` (string, required): Agent id, prefixed `agent_`.
- `organizationId` (string, required): Owning organization. Always equal to the authenticated org — agents are never visible across orgs.
- `name` (string, required): Human-readable name. Unique within an organization.
- `systemPrompt` (string, required): Initial agent instructions. Hydrated as the session's `systemPrompt` default when no per-call value is supplied.
- `voice` (string | null, required): Default TTS voice id. `null` when unset — the router picks a sane default per provider.
- `intent` (object, required): Routing defaults stored on an agent row. Hydrated into a session's `RoutingIntent` when the session is created with `agentId` and no inline `intent`. Note: agents accept a smaller `optimizeFor` enum than the per-session `RoutingIntent`.
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`.
  - `optimizeFor` (string, optional): One of: `"latency"`, `"quality"`, `"cost"`.
- `llmOptions` (object | null, required): Optional LLM tuning defaults. `null` when unset.
  - Variant (object):
    - `temperature` (number, optional): Min: 0. Max: 2.
    - `maxTokens` (integer, optional): Min: 1.
    - `model` (string, optional): Pin a specific LLM model id. When omitted, the router picks per intent.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)
- `stackPreferences` (object | null, required): Per-agent stack preferences. `null` when the agent has no preferences set.
  - Variant (object):
    - `allowedProviders` (object, optional): Per-pipeline-layer provider allowlists (e.g. STT must be Deepgram or AssemblyAI). Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
      - `stt` (array of string, optional): Allowed STT provider entries. Empty / absent = no constraint.
        - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
      - `llm` (array of string, optional): Allowed LLM provider entries. Empty / absent = no constraint.
        - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
      - `tts` (array of string, optional): Allowed TTS provider entries. Empty / absent = no constraint.
        - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
      - `s2s` (array of string, optional): Allowed S2S provider entries. Empty / absent = no constraint.
        - Allowed provider-direct S2S entry. Use a provider id or an exact provider:model pair.
- `turnHandling` (object | null, required): Per-agent turn-taking posture. `null` when the agent runs the platform defaults.
  - Variant (object):
    - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
    - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
      - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
      - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
    - `interruption` (object, optional)
      - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
      - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
      - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
    - `turnDetection` (boolean | string, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection; `"stt"` commits on final transcripts without waiting for acoustic end-of-speech (experimental).
    - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
    - `dtmfToolDescription` (string, optional): Replaces the built-in description the model sees on the `send_dtmf` keypad tool — for steering when and what the agent presses on a specific menu. Only meaningful with the `ivr` profile, which is what creates the tool.
    - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
    - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
    - `onMachine` (string, optional): What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
    - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.

Example:

```json
{
  "id": "agent_01HW...",
  "organizationId": "string",
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 0,
    "model": "string"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  }
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/agents' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","systemPrompt":"string","voice":"string","intent":{"language":"en-US","optimizeFor":"latency"},"llmOptions":{"temperature":0,"maxTokens":0,"model":"string"},"stackPreferences":{"allowedProviders":{"stt":["deepgram"],"llm":["openai"],"tts":["elevenlabs"],"s2s":["openai:gpt-realtime-2.1"]}},"turnHandling":{"profile":"conversational","endpointing":{"minDelay":0,"maxDelay":0},"interruption":{"mode":"adaptive","minDuration":0,"minWords":0},"turnDetection":true,"contextThreshold":true,"dtmfToolDescription":"string","amdPrompt":"string","waitForCallee":true,"onMachine":"agent_decides","voicemailMessage":"string"},"backgroundAudio":{"ambient":{"clip":"office-ambience","volume":0}},"endCall":{"enabled":true},"firstMessage":"string","idleRePrompts":{"enabled":true,"delayMs":0,"maxPrompts":0,"messages":["string"]},"inboundFirstMessage":"string","languageRouting":{"enabled":true,"maxDetectionTurns":0,"languages":[{"language":"string","allowedProviders":{"stt":[null],"llm":[null],"tts":[null]},"voice":"string","systemPrompt":"string"}]},"outboundFirstMessage":"string","promptVariables":[{"name":"string","defaultValue":"string","description":"string"}],"runMode":"cascade","speechNormalization":{"pronunciationDictionary":{},"textReplacements":{}},"sttMissRecovery":{"message":"string"},"sttOptions":{"keywords":["string"],"prompt":"string","language":"string","workload":"conversation","diarization":true,"speakersExpected":0,"smartFormat":true,"fillerWords":true,"profanityFilter":true,"providerOptions":{}},"ttsOptions":{"speed":0,"model":"string","workload":"conversation","providerOptions":{}},"voiceInstructions":"string","webhooks":{"preCall":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0},"postCall":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0,"extractionFields":[{"name":"string","type":"string","description":"string","options":[null]}]},"status":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0},"analysis":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0},"recording":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0}},"timezone":"string","extractionFields":[{"name":"string","type":"string","description":"string","options":["string"]}]}'
```


# Delete agent (/api-reference/agents-delete)

Removes the agent and its registered tools. The organization's only remaining agent cannot be deleted and returns 409.



## DELETE /v1/agents/{id}

Delete an agent

Removes the agent and its registered tools. The organization's only remaining agent cannot be deleted and returns 409.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Agent id, prefixed `agent_`.

### Responses

#### 200: Agent deleted

Content type: `application/json`

- `deleted` (boolean, required): One of: `true`.

Example:

```json
{
  "deleted": true
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No agent with this id exists in the authenticated organization.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

#### 409: The organization's only remaining agent cannot be deleted.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Cannot delete the only agent in this organization",
  "code": "LAST_AGENT"
}
```

### Example request

```bash
curl -X DELETE 'https://api.speko.dev/v1/agents/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Get agent (/api-reference/agents-get)

Fetch a single agent by id. Scoped to the authenticated organization — agents owned by another org always return 404.



## GET /v1/agents/{id}

Get an agent

Fetch a single agent by id. Scoped to the authenticated organization — agents owned by another org always return 404.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Agent id, prefixed `agent_`.

### Responses

#### 200: Agent

Content type: `application/json`

- `id` (string, required): Agent id, prefixed `agent_`.
- `organizationId` (string, required): Owning organization. Always equal to the authenticated org — agents are never visible across orgs.
- `name` (string, required): Human-readable name. Unique within an organization.
- `systemPrompt` (string, required): Initial agent instructions. Hydrated as the session's `systemPrompt` default when no per-call value is supplied.
- `voice` (string | null, required): Default TTS voice id. `null` when unset — the router picks a sane default per provider.
- `intent` (object, required): Routing defaults stored on an agent row. Hydrated into a session's `RoutingIntent` when the session is created with `agentId` and no inline `intent`. Note: agents accept a smaller `optimizeFor` enum than the per-session `RoutingIntent`.
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`.
  - `optimizeFor` (string, optional): One of: `"latency"`, `"quality"`, `"cost"`.
- `llmOptions` (object | null, required): Optional LLM tuning defaults. `null` when unset.
  - Variant (object):
    - `temperature` (number, optional): Min: 0. Max: 2.
    - `maxTokens` (integer, optional): Min: 1.
    - `model` (string, optional): Pin a specific LLM model id. When omitted, the router picks per intent.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)
- `stackPreferences` (object | null, required): Per-agent stack preferences. `null` when the agent has no preferences set.
  - Variant (object):
    - `allowedProviders` (object, optional): Per-pipeline-layer provider allowlists (e.g. STT must be Deepgram or AssemblyAI). Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
      - `stt` (array of string, optional): Allowed STT provider entries. Empty / absent = no constraint.
        - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
      - `llm` (array of string, optional): Allowed LLM provider entries. Empty / absent = no constraint.
        - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
      - `tts` (array of string, optional): Allowed TTS provider entries. Empty / absent = no constraint.
        - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
      - `s2s` (array of string, optional): Allowed S2S provider entries. Empty / absent = no constraint.
        - Allowed provider-direct S2S entry. Use a provider id or an exact provider:model pair.
- `turnHandling` (object | null, required): Per-agent turn-taking posture. `null` when the agent runs the platform defaults.
  - Variant (object):
    - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
    - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
      - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
      - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
    - `interruption` (object, optional)
      - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
      - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
      - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
    - `turnDetection` (boolean | string, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection; `"stt"` commits on final transcripts without waiting for acoustic end-of-speech (experimental).
    - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
    - `dtmfToolDescription` (string, optional): Replaces the built-in description the model sees on the `send_dtmf` keypad tool — for steering when and what the agent presses on a specific menu. Only meaningful with the `ivr` profile, which is what creates the tool.
    - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
    - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
    - `onMachine` (string, optional): What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
    - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.

Example:

```json
{
  "id": "agent_01HW...",
  "organizationId": "string",
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 0,
    "model": "string"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  }
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No agent with this id exists in the authenticated organization.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/agents/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# List agents (/api-reference/agents-list)

Returns every agent belonging to the authenticated organization. Agents are scoped per-org — IDs from another org will never appear here.



## GET /v1/agents

List agents

Returns every agent belonging to the authenticated organization. Agents are scoped per-org — IDs from another org will never appear here.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: Agents owned by the authenticated organization.

Content type: `application/json`

- Items (object):
  - `id` (string, required): Agent id, prefixed `agent_`.
  - `organizationId` (string, required): Owning organization. Always equal to the authenticated org — agents are never visible across orgs.
  - `name` (string, required): Human-readable name. Unique within an organization.
  - `systemPrompt` (string, required): Initial agent instructions. Hydrated as the session's `systemPrompt` default when no per-call value is supplied.
  - `voice` (string | null, required): Default TTS voice id. `null` when unset — the router picks a sane default per provider.
  - `intent` (object, required): Routing defaults stored on an agent row. Hydrated into a session's `RoutingIntent` when the session is created with `agentId` and no inline `intent`. Note: agents accept a smaller `optimizeFor` enum than the per-session `RoutingIntent`.
    - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`.
    - `optimizeFor` (string, optional): One of: `"latency"`, `"quality"`, `"cost"`.
  - `llmOptions` (object | null, required): Optional LLM tuning defaults. `null` when unset.
    - Variant (object):
      - `temperature` (number, optional): Min: 0. Max: 2.
      - `maxTokens` (integer, optional): Min: 1.
      - `model` (string, optional): Pin a specific LLM model id. When omitted, the router picks per intent.
  - `createdAt` (string (date-time), required)
  - `updatedAt` (string (date-time), required)
  - `stackPreferences` (object | null, required): Per-agent stack preferences. `null` when the agent has no preferences set.
    - Variant (object):
      - `allowedProviders` (object, optional): Per-pipeline-layer provider allowlists (e.g. STT must be Deepgram or AssemblyAI). Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
        - `stt` (array of string, optional): Allowed STT provider entries. Empty / absent = no constraint.
          - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
        - `llm` (array of string, optional): Allowed LLM provider entries. Empty / absent = no constraint.
          - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
        - `tts` (array of string, optional): Allowed TTS provider entries. Empty / absent = no constraint.
          - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
        - `s2s` (array of string, optional): Allowed S2S provider entries. Empty / absent = no constraint.
          - Allowed provider-direct S2S entry. Use a provider id or an exact provider:model pair.
  - `turnHandling` (object | null, required): Per-agent turn-taking posture. `null` when the agent runs the platform defaults.
    - Variant (object):
      - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
      - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
        - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
        - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
      - `interruption` (object, optional)
        - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
        - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
        - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
      - `turnDetection` (boolean | string, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection; `"stt"` commits on final transcripts without waiting for acoustic end-of-speech (experimental).
      - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
      - `dtmfToolDescription` (string, optional): Replaces the built-in description the model sees on the `send_dtmf` keypad tool — for steering when and what the agent presses on a specific menu. Only meaningful with the `ivr` profile, which is what creates the tool.
      - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
      - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
      - `onMachine` (string, optional): What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
      - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.

Example:

```json
[
  {
    "id": "agent_01HW...",
    "organizationId": "string",
    "name": "string",
    "systemPrompt": "string",
    "voice": "string",
    "intent": {
      "language": "en-US",
      "optimizeFor": "latency"
    },
    "llmOptions": {
      "temperature": 0,
      "maxTokens": 0,
      "model": "string"
    },
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z",
    "stackPreferences": {
      "allowedProviders": {
        "stt": [
          null
        ],
        "llm": [
          null
        ],
        "tts": [
          null
        ],
        "s2s": [
          null
        ]
      }
    },
    "turnHandling": {
      "profile": "conversational",
      "endpointing": {
        "minDelay": 0,
        "maxDelay": 0
      },
      "interruption": {
        "mode": "adaptive",
        "minDuration": 0,
        "minWords": 0
      },
      "turnDetection": true,
      "contextThreshold": true,
      "dtmfToolDescription": "string",
      "amdPrompt": "string",
      "waitForCallee": true,
      "onMachine": "agent_decides",
      "voicemailMessage": "string"
    }
  }
]
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/agents' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Update agent (/api-reference/agents-update)

Partial update — every field on the body is optional and only supplied keys are written.



## PATCH /v1/agents/{id}

Update an agent

Partial update — every field on the body is optional and only supplied keys are written.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Agent id, prefixed `agent_`.

### Request body

Required.

Content types: `application/json`

- `name` (string, optional): Human-readable display name. Does not need to be unique — agents are identified by `id`.
- `systemPrompt` (string, optional)
- `voice` (string, optional)
- `intent` (object, optional): Routing defaults stored on an agent row. Hydrated into a session's `RoutingIntent` when the session is created with `agentId` and no inline `intent`. Note: agents accept a smaller `optimizeFor` enum than the per-session `RoutingIntent`.
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`.
  - `optimizeFor` (string, optional): One of: `"latency"`, `"quality"`, `"cost"`.
- `llmOptions` (object, optional): Optional LLM tuning defaults stored on an agent. Strict object — only these three keys are accepted.
  - `temperature` (number, optional): Min: 0. Max: 2.
  - `maxTokens` (integer, optional): Min: 1.
  - `model` (string, optional): Pin a specific LLM model id. When omitted, the router picks per intent.
- `stackPreferences` (object, optional): Per-agent stack preferences. Empty / missing layers leave the router unconstrained for that layer; failover stays active within the allowed set.
  - `allowedProviders` (object, optional): Per-pipeline-layer provider allowlists (e.g. STT must be Deepgram or AssemblyAI). Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
    - `stt` (array of string, optional): Allowed STT provider entries. Empty / absent = no constraint.
      - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
    - `llm` (array of string, optional): Allowed LLM provider entries. Empty / absent = no constraint.
      - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
    - `tts` (array of string, optional): Allowed TTS provider entries. Empty / absent = no constraint.
      - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
    - `s2s` (array of string, optional): Allowed S2S provider entries. Empty / absent = no constraint.
      - Allowed provider-direct S2S entry. Use a provider id or an exact provider:model pair.
- `turnHandling` (object | null, optional): Replaces the stored posture wholesale — supplied keys are not merged into the existing object. `null` clears it back to the platform defaults.
  - Variant (object):
    - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
    - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
      - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
      - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
    - `interruption` (object, optional)
      - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
      - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
      - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
    - `turnDetection` (boolean | string, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection; `"stt"` commits on final transcripts without waiting for acoustic end-of-speech (experimental).
    - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
    - `dtmfToolDescription` (string, optional): Replaces the built-in description the model sees on the `send_dtmf` keypad tool — for steering when and what the agent presses on a specific menu. Only meaningful with the `ivr` profile, which is what creates the tool.
    - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
    - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
    - `onMachine` (string, optional): What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
    - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.
- `backgroundAudio` (object, optional)
  - `ambient` (object, optional)
    - `clip` (string, required): One of: `"office-ambience"`, `"city-ambience"`, `"forest-ambience"`, `"crowded-room"`, `"keyboard-typing"`, `"keyboard-typing2"`.
    - `volume` (number, optional): Min: 0. Max: 16.
- `endCall` (object, optional)
  - `enabled` (boolean, required)
- `firstMessage` (string, optional)
- `idleRePrompts` (object, optional)
  - `enabled` (boolean, required)
  - `delayMs` (integer, optional): Min: 1000. Max: 600000.
  - `maxPrompts` (integer, optional): Min: 1. Max: 10.
  - `messages` (array of string, optional)
- `inboundFirstMessage` (string, optional)
- `languageRouting` (object, optional)
  - `enabled` (boolean, required)
  - `maxDetectionTurns` (integer, optional): Min: 1. Max: 6.
  - `languages` (array of object, required)
    - `language` (string, required)
    - `allowedProviders` (object, optional)
      - `stt` (array of string, optional)
      - `llm` (array of string, optional)
      - `tts` (array of string, optional)
    - `voice` (string, optional)
    - `systemPrompt` (string, optional)
- `outboundFirstMessage` (string, optional)
- `promptVariables` (array of object, optional)
  - `name` (string, required): Pattern: `^[\w-]+(\.[\w-]+)*$`.
  - `defaultValue` (string, optional)
  - `description` (string, optional)
- `runMode` (string, optional): One of: `"cascade"`, `"s2s"`.
- `speechNormalization` (object, optional)
  - `pronunciationDictionary` (object, optional)
  - `textReplacements` (object, optional)
- `sttMissRecovery` (object, optional)
  - `message` (string, optional)
- `sttOptions` (object, optional)
  - `keywords` (array of string, optional)
  - `prompt` (string, optional)
  - `language` (string, optional): Pattern: `^[a-zA-Z][a-zA-Z0-9-]{1,15}$`.
  - `workload` (string, optional): One of: `"conversation"`, `"transcription"`, `"narration"`.
  - `diarization` (boolean, optional)
  - `speakersExpected` (integer, optional): Min: 1. Max: 10.
  - `smartFormat` (boolean, optional)
  - `fillerWords` (boolean, optional)
  - `profanityFilter` (boolean, optional)
  - `providerOptions` (object, optional)
- `timezone` (string, optional)
- `ttsOptions` (object, optional)
  - `speed` (number, optional): Min: 0.5. Max: 2.
  - `model` (string, optional)
  - `workload` (string, optional): One of: `"conversation"`, `"transcription"`, `"narration"`.
  - `providerOptions` (object, optional)
- `voiceInstructions` (string, optional)
- `webhooks` (object, optional)
  - `preCall` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
  - `postCall` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
    - `extractionFields` (array of object, optional)
      - `name` (string, required): Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`.
      - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
      - `description` (string, required)
      - `options` (array of string, optional)
  - `status` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
  - `analysis` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
  - `recording` (object, optional)
    - `url` (string (uri), required)
    - `secret` (string, optional)
    - `headers` (object, optional)
    - `authHeaders` (array of object, optional)
      - `name` (string, required): Pattern: `^[A-Za-z0-9!#$%&'*+.^_`|~-]+$`.
      - `value` (string, optional)
    - `timeoutMs` (integer, optional): Min: 100. Max: 8000.
- `extractionFields` (array of object, optional)
  - `name` (string, required): Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)

Example body:

```json
{
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 0,
    "model": "string"
  },
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  },
  "backgroundAudio": {
    "ambient": {
      "clip": "office-ambience",
      "volume": 0
    }
  },
  "endCall": {
    "enabled": true
  },
  "firstMessage": "string",
  "idleRePrompts": {
    "enabled": true,
    "delayMs": 0,
    "maxPrompts": 0,
    "messages": [
      "string"
    ]
  },
  "inboundFirstMessage": "string",
  "languageRouting": {
    "enabled": true,
    "maxDetectionTurns": 0,
    "languages": [
      {
        "language": "string",
        "allowedProviders": {
          "stt": [
            null
          ],
          "llm": [
            null
          ],
          "tts": [
            null
          ]
        },
        "voice": "string",
        "systemPrompt": "string"
      }
    ]
  },
  "outboundFirstMessage": "string",
  "promptVariables": [
    {
      "name": "string",
      "defaultValue": "string",
      "description": "string"
    }
  ],
  "runMode": "cascade",
  "speechNormalization": {
    "pronunciationDictionary": {},
    "textReplacements": {}
  },
  "sttMissRecovery": {
    "message": "string"
  },
  "sttOptions": {
    "keywords": [
      "string"
    ],
    "prompt": "string",
    "language": "string",
    "workload": "conversation",
    "diarization": true,
    "speakersExpected": 0,
    "smartFormat": true,
    "fillerWords": true,
    "profanityFilter": true,
    "providerOptions": {}
  },
  "timezone": "string",
  "ttsOptions": {
    "speed": 0,
    "model": "string",
    "workload": "conversation",
    "providerOptions": {}
  },
  "voiceInstructions": "string",
  "webhooks": {
    "preCall": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    },
    "postCall": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0,
      "extractionFields": [
        {
          "name": "string",
          "type": "string",
          "description": "string",
          "options": [
            null
          ]
        }
      ]
    },
    "status": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    },
    "analysis": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    },
    "recording": {
      "url": "string",
      "secret": "string",
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "timeoutMs": 0
    }
  },
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ]
}
```

### Responses

#### 200: Agent updated

Content type: `application/json`

- `id` (string, required): Agent id, prefixed `agent_`.
- `organizationId` (string, required): Owning organization. Always equal to the authenticated org — agents are never visible across orgs.
- `name` (string, required): Human-readable name. Unique within an organization.
- `systemPrompt` (string, required): Initial agent instructions. Hydrated as the session's `systemPrompt` default when no per-call value is supplied.
- `voice` (string | null, required): Default TTS voice id. `null` when unset — the router picks a sane default per provider.
- `intent` (object, required): Routing defaults stored on an agent row. Hydrated into a session's `RoutingIntent` when the session is created with `agentId` and no inline `intent`. Note: agents accept a smaller `optimizeFor` enum than the per-session `RoutingIntent`.
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`.
  - `optimizeFor` (string, optional): One of: `"latency"`, `"quality"`, `"cost"`.
- `llmOptions` (object | null, required): Optional LLM tuning defaults. `null` when unset.
  - Variant (object):
    - `temperature` (number, optional): Min: 0. Max: 2.
    - `maxTokens` (integer, optional): Min: 1.
    - `model` (string, optional): Pin a specific LLM model id. When omitted, the router picks per intent.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)
- `stackPreferences` (object | null, required): Per-agent stack preferences. `null` when the agent has no preferences set.
  - Variant (object):
    - `allowedProviders` (object, optional): Per-pipeline-layer provider allowlists (e.g. STT must be Deepgram or AssemblyAI). Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
      - `stt` (array of string, optional): Allowed STT provider entries. Empty / absent = no constraint.
        - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
      - `llm` (array of string, optional): Allowed LLM provider entries. Empty / absent = no constraint.
        - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
      - `tts` (array of string, optional): Allowed TTS provider entries. Empty / absent = no constraint.
        - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
      - `s2s` (array of string, optional): Allowed S2S provider entries. Empty / absent = no constraint.
        - Allowed provider-direct S2S entry. Use a provider id or an exact provider:model pair.
- `turnHandling` (object | null, required): Per-agent turn-taking posture. `null` when the agent runs the platform defaults.
  - Variant (object):
    - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
    - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
      - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
      - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
    - `interruption` (object, optional)
      - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
      - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
      - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
    - `turnDetection` (boolean | string, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection; `"stt"` commits on final transcripts without waiting for acoustic end-of-speech (experimental).
    - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
    - `dtmfToolDescription` (string, optional): Replaces the built-in description the model sees on the `send_dtmf` keypad tool — for steering when and what the agent presses on a specific menu. Only meaningful with the `ivr` profile, which is what creates the tool.
    - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
    - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
    - `onMachine` (string, optional): What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
    - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.

Example:

```json
{
  "id": "agent_01HW...",
  "organizationId": "string",
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 0,
    "model": "string"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  }
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No agent with this id exists in the authenticated organization.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

### Example request

```bash
curl -X PATCH 'https://api.speko.dev/v1/agents/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","systemPrompt":"string","voice":"string","intent":{"language":"en-US","optimizeFor":"latency"},"llmOptions":{"temperature":0,"maxTokens":0,"model":"string"},"stackPreferences":{"allowedProviders":{"stt":["deepgram"],"llm":["openai"],"tts":["elevenlabs"],"s2s":["openai:gpt-realtime-2.1"]}},"turnHandling":{"profile":"conversational","endpointing":{"minDelay":0,"maxDelay":0},"interruption":{"mode":"adaptive","minDuration":0,"minWords":0},"turnDetection":true,"contextThreshold":true,"dtmfToolDescription":"string","amdPrompt":"string","waitForCallee":true,"onMachine":"agent_decides","voicemailMessage":"string"},"backgroundAudio":{"ambient":{"clip":"office-ambience","volume":0}},"endCall":{"enabled":true},"firstMessage":"string","idleRePrompts":{"enabled":true,"delayMs":0,"maxPrompts":0,"messages":["string"]},"inboundFirstMessage":"string","languageRouting":{"enabled":true,"maxDetectionTurns":0,"languages":[{"language":"string","allowedProviders":{"stt":[null],"llm":[null],"tts":[null]},"voice":"string","systemPrompt":"string"}]},"outboundFirstMessage":"string","promptVariables":[{"name":"string","defaultValue":"string","description":"string"}],"runMode":"cascade","speechNormalization":{"pronunciationDictionary":{},"textReplacements":{}},"sttMissRecovery":{"message":"string"},"sttOptions":{"keywords":["string"],"prompt":"string","language":"string","workload":"conversation","diarization":true,"speakersExpected":0,"smartFormat":true,"fillerWords":true,"profanityFilter":true,"providerOptions":{}},"timezone":"string","ttsOptions":{"speed":0,"model":"string","workload":"conversation","providerOptions":{}},"voiceInstructions":"string","webhooks":{"preCall":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0},"postCall":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0,"extractionFields":[{"name":"string","type":"string","description":"string","options":[null]}]},"status":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0},"analysis":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0},"recording":{"url":"string","secret":"string","headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":0}},"extractionFields":[{"name":"string","type":"string","description":"string","options":["string"]}]}'
```


# Broker presence (/api-reference/broker-presence)

Register, heartbeat, and read who can take a human call right now.



## POST /v1/voice/presence/token

Register and mint presence credentials

Marks the supplied broker `available` AND mints credentials for their presence room in one round trip. Connect with `livekit-client` and listen for JSON data messages on topic `speko.human_call` — ring offers and live call events arrive there. A broker with no open presence connection cannot be rung, whatever their status.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `brokerId` (string, required): Pattern: `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`.

Example body:

```json
{
  "brokerId": "string"
}
```

### Responses

#### 200: Presence-room credentials.

Content type: `application/json`

- `token` (string, optional)
- `url` (string, optional): Media transport URL to connect `livekit-client` to.
- `identity` (string, optional)
- `roomName` (string, optional)
- `expiresAt` (string (date-time), optional)

Example:

```json
{
  "token": "string",
  "url": "string",
  "identity": "string",
  "roomName": "string",
  "expiresAt": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/voice/presence/token' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"brokerId":"string"}'
```

## POST /v1/voice/presence/heartbeat

Heartbeat

Keeps the supplied broker reachable. Presence goes stale 90 seconds after the last heartbeat and a stale broker is skipped by inbound routing regardless of stored status — call this on a timer, every 30 seconds is a good default.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `brokerId` (string, required): Pattern: `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`.

Example body:

```json
{
  "brokerId": "string"
}
```

### Responses

#### 200: The broker's presence after the heartbeat.

Content type: `application/json`

- `brokerId` (string, optional)
- `status` (string, optional): One of: `"available"`, `"busy"`, `"away"`, `"offline"`.
- `lastSeenAt` (string (date-time), optional)
- `reachable` (boolean, optional): False once the heartbeat is stale (90 s), regardless of `status`. Routing only rings reachable brokers.

Example:

```json
{
  "brokerId": "string",
  "status": "available",
  "lastSeenAt": "2026-01-01T00:00:00Z",
  "reachable": true
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/voice/presence/heartbeat' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"brokerId":"string"}'
```

## PUT /v1/voice/presence

Set availability

Sets the supplied broker's status. `busy` and `away` keep the heartbeat alive while diverting inbound; `offline` leaves routing entirely.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `brokerId` (string, required): Pattern: `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`.
- `status` (string, required): One of: `"available"`, `"busy"`, `"away"`, `"offline"`.

Example body:

```json
{
  "brokerId": "string",
  "status": "available"
}
```

### Responses

#### 200: The updated presence.

Content type: `application/json`

- `brokerId` (string, optional)
- `status` (string, optional): One of: `"available"`, `"busy"`, `"away"`, `"offline"`.
- `lastSeenAt` (string (date-time), optional)
- `reachable` (boolean, optional): False once the heartbeat is stale (90 s), regardless of `status`. Routing only rings reachable brokers.

Example:

```json
{
  "brokerId": "string",
  "status": "available",
  "lastSeenAt": "2026-01-01T00:00:00Z",
  "reachable": true
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X PUT 'https://api.speko.dev/v1/voice/presence' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"brokerId":"string","status":"available"}'
```

## GET /v1/voice/presence

List the availability roster

Every registered broker in the organization with their status and a computed `reachable`. Build your team's availability board from it.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: The org roster.

Content type: `application/json`

- `brokers` (array of object, optional)
  - `brokerId` (string, optional)
  - `status` (string, optional): One of: `"available"`, `"busy"`, `"away"`, `"offline"`.
  - `lastSeenAt` (string (date-time), optional)
  - `reachable` (boolean, optional): False once the heartbeat is stale (90 s), regardless of `status`. Routing only rings reachable brokers.

Example:

```json
{
  "brokers": [
    {
      "brokerId": "string",
      "status": "available",
      "lastSeenAt": "2026-01-01T00:00:00Z",
      "reachable": true
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/voice/presence' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Call control (/api-reference/call-control)

Programmable human calling: dial, read, and command browser + PSTN call legs by controlId.



## POST /v1/voice/calls

Dial an outbound human call

Places a PSTN call with the supplied org-defined broker's softphone as the other leg. Resolves as soon as the call exists — the PSTN leg is still `initiating`/`ringing`; watch the event stream for `call.answered`. The response carries join credentials for that browser leg: connect immediately, or the first moments after the far end answers are silence.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `brokerId` (string, required): Pattern: `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`.
- `to` (string, required): Destination, E.164. Pattern: `^\+[1-9]\d{1,14}$`.
- `from` (string, optional): Caller ID. Must be a number this organization owns; defaults to the org's first outbound-capable number. Pattern: `^\+[1-9]\d{1,14}$`.
- `metadata` (object, optional)

Example body:

```json
{
  "brokerId": "string",
  "to": "string",
  "from": "string",
  "metadata": {}
}
```

### Responses

#### 201: Call created. `call` carries both legs (the `browser` leg is the caller's softphone, the `pstn` leg the far end); `join` is the caller's own room credentials.

Content type: `application/json`

- `call` (object, required): A call between people. Distinct from an AI voice session — see `/v1/calls` for those.
  - `id` (string, optional)
  - `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
  - `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"ended"`, `"declined"`, `"missed"`, `"cancelled"`, `"failed"`.
  - `answeredAt` (string (date-time) | null, optional)
  - `endedAt` (string (date-time) | null, optional)
  - `endReason` (string | null, optional)
  - `legs` (array of object, optional)
    - `id` (string, optional)
    - `controlId` (string, optional): The command handle. Address every leg action to this.
    - `callId` (string, optional)
    - `kind` (string, optional): `browser` is a person on a softphone, `pstn` a phone number, `agent` an AI session bridged in. One of: `"browser"`, `"pstn"`, `"agent"`.
    - `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
    - `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"held"`, `"ended"`, `"failed"`.
    - `brokerId` (string | null, optional): Owning org-defined broker, when `kind` is `browser`.
    - `phoneNumber` (string | null, optional): E.164 of the far end, when `kind` is `pstn`.
    - `muted` (boolean, optional)
    - `onHold` (boolean, optional)
    - `answeredAt` (string (date-time) | null, optional)
    - `endedAt` (string (date-time) | null, optional)
    - `endReason` (string | null, optional)
    - `createdAt` (string (date-time), optional)
  - `createdAt` (string (date-time), optional)
- `join` (object, required): What a browser needs to join a room. Short-lived; minted per join, never cached.
  - `token` (string, optional)
  - `url` (string, optional): Media transport URL to connect `livekit-client` to.
  - `identity` (string, optional)
  - `roomName` (string, optional)
  - `expiresAt` (string (date-time), optional)

Example:

```json
{
  "call": {
    "id": "string",
    "direction": "inbound",
    "status": "initiating",
    "answeredAt": "2026-01-01T00:00:00Z",
    "endedAt": "2026-01-01T00:00:00Z",
    "endReason": "string",
    "legs": [
      {
        "id": "string",
        "controlId": "string",
        "callId": "string",
        "kind": "browser",
        "direction": "inbound",
        "status": "initiating",
        "brokerId": "string",
        "phoneNumber": "string",
        "muted": true,
        "onHold": true,
        "answeredAt": "2026-01-01T00:00:00Z",
        "endedAt": "2026-01-01T00:00:00Z",
        "endReason": "string",
        "createdAt": "2026-01-01T00:00:00Z"
      }
    ],
    "createdAt": "2026-01-01T00:00:00Z"
  },
  "join": {
    "token": "string",
    "url": "string",
    "identity": "string",
    "roomName": "string",
    "expiresAt": "2026-01-01T00:00:00Z"
  }
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/voice/calls' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"brokerId":"string","to":"string","from":"string","metadata":{}}'
```

## GET /v1/voice/calls

List human calls

The organization's calls, newest first. Filters combine via AND and are validated — an unknown `status` is a 400, not an ignored filter.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `status` (string, in query, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"ended"`, `"declined"`, `"missed"`, `"cancelled"`, `"failed"`.
- `direction` (string, in query, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
- `brokerId` (string, in query, optional): Calls with a `browser` leg owned by this broker.
- `limit` (integer, in query, optional): Min: 1. Max: 200.

### Responses

#### 200: Calls, newest first.

Content type: `application/json`

- `calls` (array of object, optional)
  - `id` (string, optional)
  - `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
  - `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"ended"`, `"declined"`, `"missed"`, `"cancelled"`, `"failed"`.
  - `answeredAt` (string (date-time) | null, optional)
  - `endedAt` (string (date-time) | null, optional)
  - `endReason` (string | null, optional)
  - `legs` (array of object, optional)
    - `id` (string, optional)
    - `controlId` (string, optional): The command handle. Address every leg action to this.
    - `callId` (string, optional)
    - `kind` (string, optional): `browser` is a person on a softphone, `pstn` a phone number, `agent` an AI session bridged in. One of: `"browser"`, `"pstn"`, `"agent"`.
    - `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
    - `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"held"`, `"ended"`, `"failed"`.
    - `brokerId` (string | null, optional): Owning org-defined broker, when `kind` is `browser`.
    - `phoneNumber` (string | null, optional): E.164 of the far end, when `kind` is `pstn`.
    - `muted` (boolean, optional)
    - `onHold` (boolean, optional)
    - `answeredAt` (string (date-time) | null, optional)
    - `endedAt` (string (date-time) | null, optional)
    - `endReason` (string | null, optional)
    - `createdAt` (string (date-time), optional)
  - `createdAt` (string (date-time), optional)

Example:

```json
{
  "calls": [
    {
      "id": "string",
      "direction": "inbound",
      "status": "initiating",
      "answeredAt": "2026-01-01T00:00:00Z",
      "endedAt": "2026-01-01T00:00:00Z",
      "endReason": "string",
      "legs": [
        {
          "id": "string",
          "controlId": "string",
          "callId": "string",
          "kind": "browser",
          "direction": "inbound",
          "status": "initiating",
          "brokerId": "string",
          "phoneNumber": "string",
          "muted": true,
          "onHold": true,
          "answeredAt": "2026-01-01T00:00:00Z",
          "endedAt": "2026-01-01T00:00:00Z",
          "endReason": "string",
          "createdAt": "2026-01-01T00:00:00Z"
        }
      ],
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/voice/calls' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## GET /v1/voice/calls/{callId}

Get a human call

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `callId` (string, in path, required): Call id.

### Responses

#### 200: The call and every leg on it.

Content type: `application/json`

- `id` (string, optional)
- `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
- `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"ended"`, `"declined"`, `"missed"`, `"cancelled"`, `"failed"`.
- `answeredAt` (string (date-time) | null, optional)
- `endedAt` (string (date-time) | null, optional)
- `endReason` (string | null, optional)
- `legs` (array of object, optional)
  - `id` (string, optional)
  - `controlId` (string, optional): The command handle. Address every leg action to this.
  - `callId` (string, optional)
  - `kind` (string, optional): `browser` is a person on a softphone, `pstn` a phone number, `agent` an AI session bridged in. One of: `"browser"`, `"pstn"`, `"agent"`.
  - `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
  - `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"held"`, `"ended"`, `"failed"`.
  - `brokerId` (string | null, optional): Owning org-defined broker, when `kind` is `browser`.
  - `phoneNumber` (string | null, optional): E.164 of the far end, when `kind` is `pstn`.
  - `muted` (boolean, optional)
  - `onHold` (boolean, optional)
  - `answeredAt` (string (date-time) | null, optional)
  - `endedAt` (string (date-time) | null, optional)
  - `endReason` (string | null, optional)
  - `createdAt` (string (date-time), optional)
- `createdAt` (string (date-time), optional)

Example:

```json
{
  "id": "string",
  "direction": "inbound",
  "status": "initiating",
  "answeredAt": "2026-01-01T00:00:00Z",
  "endedAt": "2026-01-01T00:00:00Z",
  "endReason": "string",
  "legs": [
    {
      "id": "string",
      "controlId": "string",
      "callId": "string",
      "kind": "browser",
      "direction": "inbound",
      "status": "initiating",
      "brokerId": "string",
      "phoneNumber": "string",
      "muted": true,
      "onHold": true,
      "answeredAt": "2026-01-01T00:00:00Z",
      "endedAt": "2026-01-01T00:00:00Z",
      "endReason": "string",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Call or leg not found — including a leg that exists but belongs to another organization or broker.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/voice/calls/{callId}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## GET /v1/voice/calls/{callId}/events

List a call's events

The call's ordered history, oldest first — the durable record behind the one-shot webhook stream. Reconcile from here.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `callId` (string, in path, required): Call id.

### Responses

#### 200: Events, oldest first.

Content type: `application/json`

- `events` (array of object, optional)
  - `id` (string, optional)
  - `type` (string, optional): One of: `"call.initiated"`, `"call.ringing"`, `"call.answered"`, `"call.bridged"`, `"call.hold"`, `"call.unhold"`, `"call.mute"`, `"call.unmute"`, `"call.dtmf.received"`, `"call.dtmf.sent"`, `"call.transfer.initiated"`, `"call.transfer.completed"`, `"call.transfer.failed"`, `"call.leg.hangup"`, `"call.hangup"`.
  - `callId` (string, optional)
  - `controlId` (string | null, optional): Null for call-scoped events (`call.initiated`, `call.hangup`).
  - `payload` (object, optional)
  - `occurredAt` (string (date-time), optional)

Example:

```json
{
  "events": [
    {
      "id": "string",
      "type": "call.initiated",
      "callId": "string",
      "controlId": "string",
      "payload": {},
      "occurredAt": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Call or leg not found — including a leg that exists but belongs to another organization or broker.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/voice/calls/{callId}/events' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/voice/legs/{controlId}/join

Mint join credentials for your leg

Room credentials for one of the supplied broker's own `browser` legs. Join first, then `answer`. Tokens are short-lived and minted per join; re-join on reconnect rather than caching one. A leg owned by another broker returns 404, deliberately indistinguishable from a leg that does not exist.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `controlId` (string, in path, required): Leg control id — the opaque command handle returned on every leg (the Telnyx `call_control_id` equivalent).

### Request body

Required.

Content types: `application/json`

- `brokerId` (string, required): Pattern: `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`.

Example body:

```json
{
  "brokerId": "string"
}
```

### Responses

#### 200: Join credentials for the leg's room.

Content type: `application/json`

- `token` (string, optional)
- `url` (string, optional): Media transport URL to connect `livekit-client` to.
- `identity` (string, optional)
- `roomName` (string, optional)
- `expiresAt` (string (date-time), optional)

Example:

```json
{
  "token": "string",
  "url": "string",
  "identity": "string",
  "roomName": "string",
  "expiresAt": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Call or leg not found — including a leg that exists but belongs to another organization or broker.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/voice/legs/{controlId}/join' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"brokerId":"string"}'
```

## POST /v1/voice/legs/{controlId}/actions/{command}

Command a live leg

The command surface: `answer`, `hangup`, `bridge`, `hold`, `unhold`, `mute`, `unmute`, `dtmf`, `transfer`, each addressed to the leg it acts on. Commands are idempotent by intent — repeating one is a no-op that still returns the leg. Accepts an API key: server-side automation on live calls is the point of a programmable-voice API. Notable semantics: `hold` is silent (no hold-music source yet); `dtmf` must be addressed to a `pstn` leg and requires a connected browser leg on the call to relay the tones; a warm `transfer` is completed by a later `bridge`.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `controlId` (string, in path, required): Leg control id — the opaque command handle returned on every leg (the Telnyx `call_control_id` equivalent).
- `command` (string, in path, required): One of: `"answer"`, `"hangup"`, `"bridge"`, `"hold"`, `"unhold"`, `"mute"`, `"unmute"`, `"dtmf"`, `"transfer"`.

### Request body

Optional.

Content types: `application/json`

- `reason` (string, optional): `hangup` only. Recorded as the leg's `endReason`.
- `digits` (string, optional): `dtmf` only. `0-9`, `*`, `#`, `,`, and `w` for a pause; max 64. Pattern: `^[0-9*#w,]{1,64}$`.
- `bridgeTo` (string, optional): `bridge` only. `controlId` of the leg to bridge this one to.
- `to` (string, optional): `transfer` only. An E.164 number, or the `controlId` of another broker's leg.
- `mode` (string, optional): `transfer` only. `blind` hands off and drops the leg; `warm` opens a consultation room you complete with `bridge`. One of: `"blind"`, `"warm"`.

Example body:

```json
{
  "reason": "string",
  "digits": "string",
  "bridgeTo": "string",
  "to": "string",
  "mode": "blind"
}
```

### Responses

#### 200: The leg after the command.

Content type: `application/json`

- `leg` (object, optional): One participant's connection to a human call.
  - `id` (string, optional)
  - `controlId` (string, optional): The command handle. Address every leg action to this.
  - `callId` (string, optional)
  - `kind` (string, optional): `browser` is a person on a softphone, `pstn` a phone number, `agent` an AI session bridged in. One of: `"browser"`, `"pstn"`, `"agent"`.
  - `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"internal"`.
  - `status` (string, optional): One of: `"initiating"`, `"ringing"`, `"active"`, `"held"`, `"ended"`, `"failed"`.
  - `brokerId` (string | null, optional): Owning org-defined broker, when `kind` is `browser`.
  - `phoneNumber` (string | null, optional): E.164 of the far end, when `kind` is `pstn`.
  - `muted` (boolean, optional)
  - `onHold` (boolean, optional)
  - `answeredAt` (string (date-time) | null, optional)
  - `endedAt` (string (date-time) | null, optional)
  - `endReason` (string | null, optional)
  - `createdAt` (string (date-time), optional)
- `noop` (boolean, optional): Present when the command changed nothing, e.g. muting a muted leg.

Example:

```json
{
  "leg": {
    "id": "string",
    "controlId": "string",
    "callId": "string",
    "kind": "browser",
    "direction": "inbound",
    "status": "initiating",
    "brokerId": "string",
    "phoneNumber": "string",
    "muted": true,
    "onHold": true,
    "answeredAt": "2026-01-01T00:00:00Z",
    "endedAt": "2026-01-01T00:00:00Z",
    "endReason": "string",
    "createdAt": "2026-01-01T00:00:00Z"
  },
  "noop": true
}
```

#### 400: Invalid payload (`VALIDATION_ERROR`), a command the leg kind cannot take (`UNSUPPORTED_COMMAND`), or a bridge to a leg that is not live or not yours (`BRIDGE_TARGET_INVALID`).

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "DTMF is only meaningful towards a PSTN leg",
  "code": "UNSUPPORTED_COMMAND"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Call or leg not found — including a leg that exists but belongs to another organization or broker.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

#### 409: The leg (`LEG_NOT_LIVE`) or call (`CALL_NOT_LIVE`) has already ended.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "leg is not live",
  "code": "LEG_NOT_LIVE"
}
```

#### 503: Human calling is not enabled for this organization (it is in early access — ask us to enable it), or is not configured on this deployment.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/voice/legs/{controlId}/actions/{command}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"string","digits":"string","bridgeTo":"string","to":"string","mode":"blind"}'
```


# Callbacks (/api-reference/callbacks)

List, inspect, cancel, and dispatch scheduled callbacks created from call analysis.



## GET /v1/callbacks

List scheduled callbacks

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `status` (string, in query, optional): One of: `"scheduled"`, `"dispatching"`, `"dispatched"`, `"cancelled"`, `"failed"`.
- `source_session_id` (string, in query, optional)
- `limit` (integer, in query, optional): Default: `25`. Min: 1. Max: 100.

### Responses

#### 200: Scheduled callbacks

Content type: `application/json`

- `callbacks` (array of object, required)
  - `id` (string, required)
  - `organization_id` (string, required)
  - `source_session_id` (string | null, optional)
  - `created_session_id` (string | null, optional)
  - `agent_id` (string | null, optional)
  - `phone_number_id` (string | null, optional)
  - `to_number` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
  - `from_number` (string | null, optional)
  - `scheduled_at` (string (date-time), required)
  - `status` (string, required): One of: `"scheduled"`, `"dispatching"`, `"dispatched"`, `"cancelled"`, `"failed"`.
  - `reason` (string | null, optional)
  - `instructions` (string | null, optional)
  - `summary` (string | null, optional)
  - `pipeline_config` (object, required)
  - `metadata` (object, required)
  - `failure_cause` (string | null, optional)
  - `attempted_at` (string (date-time) | null, optional)
  - `dispatched_at` (string (date-time) | null, optional)
  - `cancelled_at` (string (date-time) | null, optional)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)

Example:

```json
{
  "callbacks": [
    {
      "id": "string",
      "organization_id": "string",
      "source_session_id": "string",
      "created_session_id": "string",
      "agent_id": "string",
      "phone_number_id": "string",
      "to_number": "+12015551234",
      "from_number": "string",
      "scheduled_at": "2026-01-01T00:00:00Z",
      "status": "scheduled",
      "reason": "string",
      "instructions": "string",
      "summary": "string",
      "pipeline_config": {},
      "metadata": {},
      "failure_cause": "string",
      "attempted_at": "2026-01-01T00:00:00Z",
      "dispatched_at": "2026-01-01T00:00:00Z",
      "cancelled_at": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/callbacks' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## GET /v1/callbacks/{id}

Get scheduled callback

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Scheduled callback

Content type: `application/json`

- `id` (string, required)
- `organization_id` (string, required)
- `source_session_id` (string | null, optional)
- `created_session_id` (string | null, optional)
- `agent_id` (string | null, optional)
- `phone_number_id` (string | null, optional)
- `to_number` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `from_number` (string | null, optional)
- `scheduled_at` (string (date-time), required)
- `status` (string, required): One of: `"scheduled"`, `"dispatching"`, `"dispatched"`, `"cancelled"`, `"failed"`.
- `reason` (string | null, optional)
- `instructions` (string | null, optional)
- `summary` (string | null, optional)
- `pipeline_config` (object, required)
- `metadata` (object, required)
- `failure_cause` (string | null, optional)
- `attempted_at` (string (date-time) | null, optional)
- `dispatched_at` (string (date-time) | null, optional)
- `cancelled_at` (string (date-time) | null, optional)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organization_id": "string",
  "source_session_id": "string",
  "created_session_id": "string",
  "agent_id": "string",
  "phone_number_id": "string",
  "to_number": "+12015551234",
  "from_number": "string",
  "scheduled_at": "2026-01-01T00:00:00Z",
  "status": "scheduled",
  "reason": "string",
  "instructions": "string",
  "summary": "string",
  "pipeline_config": {},
  "metadata": {},
  "failure_cause": "string",
  "attempted_at": "2026-01-01T00:00:00Z",
  "dispatched_at": "2026-01-01T00:00:00Z",
  "cancelled_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/callbacks/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/callbacks/{id}/cancel

Cancel scheduled callback

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Request body

Optional.

Content types: `application/json`

- `reason` (string, optional)

Example body:

```json
{
  "reason": "string"
}
```

### Responses

#### 200: Scheduled callback

Content type: `application/json`

- `id` (string, required)
- `organization_id` (string, required)
- `source_session_id` (string | null, optional)
- `created_session_id` (string | null, optional)
- `agent_id` (string | null, optional)
- `phone_number_id` (string | null, optional)
- `to_number` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `from_number` (string | null, optional)
- `scheduled_at` (string (date-time), required)
- `status` (string, required): One of: `"scheduled"`, `"dispatching"`, `"dispatched"`, `"cancelled"`, `"failed"`.
- `reason` (string | null, optional)
- `instructions` (string | null, optional)
- `summary` (string | null, optional)
- `pipeline_config` (object, required)
- `metadata` (object, required)
- `failure_cause` (string | null, optional)
- `attempted_at` (string (date-time) | null, optional)
- `dispatched_at` (string (date-time) | null, optional)
- `cancelled_at` (string (date-time) | null, optional)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organization_id": "string",
  "source_session_id": "string",
  "created_session_id": "string",
  "agent_id": "string",
  "phone_number_id": "string",
  "to_number": "+12015551234",
  "from_number": "string",
  "scheduled_at": "2026-01-01T00:00:00Z",
  "status": "scheduled",
  "reason": "string",
  "instructions": "string",
  "summary": "string",
  "pipeline_config": {},
  "metadata": {},
  "failure_cause": "string",
  "attempted_at": "2026-01-01T00:00:00Z",
  "dispatched_at": "2026-01-01T00:00:00Z",
  "cancelled_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/callbacks/{id}/cancel' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"string"}'
```

## POST /v1/callbacks/{id}/dispatch

Dispatch scheduled callback now

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Scheduled callback

Content type: `application/json`

- `id` (string, required)
- `organization_id` (string, required)
- `source_session_id` (string | null, optional)
- `created_session_id` (string | null, optional)
- `agent_id` (string | null, optional)
- `phone_number_id` (string | null, optional)
- `to_number` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `from_number` (string | null, optional)
- `scheduled_at` (string (date-time), required)
- `status` (string, required): One of: `"scheduled"`, `"dispatching"`, `"dispatched"`, `"cancelled"`, `"failed"`.
- `reason` (string | null, optional)
- `instructions` (string | null, optional)
- `summary` (string | null, optional)
- `pipeline_config` (object, required)
- `metadata` (object, required)
- `failure_cause` (string | null, optional)
- `attempted_at` (string (date-time) | null, optional)
- `dispatched_at` (string (date-time) | null, optional)
- `cancelled_at` (string (date-time) | null, optional)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organization_id": "string",
  "source_session_id": "string",
  "created_session_id": "string",
  "agent_id": "string",
  "phone_number_id": "string",
  "to_number": "+12015551234",
  "from_number": "string",
  "scheduled_at": "2026-01-01T00:00:00Z",
  "status": "scheduled",
  "reason": "string",
  "instructions": "string",
  "summary": "string",
  "pipeline_config": {},
  "metadata": {},
  "failure_cause": "string",
  "attempted_at": "2026-01-01T00:00:00Z",
  "dispatched_at": "2026-01-01T00:00:00Z",
  "cancelled_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/callbacks/{id}/dispatch' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Calls (/api-reference/calls)

Inspect call detail, events, reports, recordings, and live call transfers.



## GET /v1/calls/{id}

Get call detail

Returns the call session, transcript, report if available, transfer attempts, and recording metadata.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Call detail

Content type: `application/json`

- `id` (string, required)
- `call_id` (string, required)
- `resource_uri` (string, required)
- `agent_id` (string | null, optional)
- `status` (string, required)
- `kind` (string, required)
- `room_name` (string | null, optional)
- `language` (string, optional)
- `pipeline_config` (object, optional)
- `metadata` (object, optional)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), optional)
- `ended_at` (string (date-time) | null, optional)
- `duration_seconds` (integer | null, optional)
- `recording_status` (string | null, optional)
- `recording_duration_ms` (integer | null, optional)
- `recording_resource_uri` (string, optional)
- `report` (object, optional)
  - `session_id` (string, required)
  - `organization_id` (string, optional)
  - `summary` (string, required)
  - `outcome` (string, required)
  - `structured_data` (object, optional)
  - `custom_data` (object, optional): Caller-defined extraction values keyed by field name, matching the `call.report` webhook. `{}` when the agent declares no extraction fields.
  - `transcript` (object, required)
    - `entries` (array of object, optional)
      - `id` (string, required)
      - `index` (integer, required)
      - `source` (string, required): One of: `"user"`, `"agent"`, `"system"`.
      - `text` (string, required)
      - `started_at` (string (date-time), required)
      - `ended_at` (string (date-time) | null, optional)
      - `provider` (string | null, optional)
      - `model` (string | null, optional)
      - `metadata` (object, required)
  - `cost_micro_usd` (string, required)
  - `cost_breakdown` (array of object, optional)
  - `metadata` (object, optional)
  - `scheduled_callback` (object, optional)
  - `analysis_status` (string, optional): One of: `"heuristic"`, `"completed"`, `"failed"`.
  - `post_call_webhook_status` (string, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
  - `post_call_webhook_attempts` (integer, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
  - `post_call_webhook_next_retry_at` (string (date-time) | null, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
  - `post_call_webhook_delivered_at` (string (date-time) | null, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
  - `post_call_webhook_error` (string | null, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
  - `webhook_deliveries` (array of object, required)
    - `endpointId` (string (uuid), required)
    - `deliveryId` (string (uuid), required)
    - `eventId` (string (uuid), required)
    - `delivered` (boolean, required)
    - `status` (integer | null, required)
    - `error` (string | null, required)
    - `createdAt` (string (date-time), required)
  - `created_at` (string (date-time), optional)
  - `updated_at` (string (date-time), optional)
- `transfers` (array of object, optional)
  - `id` (string, required)
  - `session_id` (string, required)
  - `organization_id` (string, required)
  - `kind` (string, required): One of: `"blind"`, `"warm"`.
  - `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
  - `transfer_to` (string, required)
  - `from_room_name` (string | null, optional)
  - `consultation_room_name` (string | null, optional)
  - `caller_participant_identity` (string | null, optional)
  - `recipient_participant_identity` (string | null, optional)
  - `outbound_trunk_id` (string | null, optional)
  - `screening_prompt` (string | null, optional)
  - `summary` (string | null, optional)
  - `failure_cause` (string | null, optional)
  - `metadata` (object, required)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
  - `completed_at` (string (date-time) | null, optional)
- `transcript` (object, required)
  - `entries` (array of object, optional)
    - `id` (string, required)
    - `index` (integer, required)
    - `source` (string, required): One of: `"user"`, `"agent"`, `"system"`.
    - `text` (string, required)
    - `started_at` (string (date-time), required)
    - `ended_at` (string (date-time) | null, optional)
    - `provider` (string | null, optional)
    - `model` (string | null, optional)
    - `metadata` (object, required)
- `span_tree` (object, optional)

Example:

```json
{
  "id": "string",
  "call_id": "string",
  "resource_uri": "string",
  "agent_id": "string",
  "status": "string",
  "kind": "string",
  "room_name": "string",
  "language": "string",
  "pipeline_config": {},
  "metadata": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "ended_at": "2026-01-01T00:00:00Z",
  "duration_seconds": 0,
  "recording_status": "string",
  "recording_duration_ms": 0,
  "recording_resource_uri": "string",
  "report": {
    "session_id": "string",
    "organization_id": "string",
    "summary": "string",
    "outcome": "string",
    "structured_data": {},
    "custom_data": {},
    "transcript": {
      "entries": [
        {
          "id": "string",
          "index": 0,
          "source": "user",
          "text": "string",
          "started_at": "2026-01-01T00:00:00Z",
          "ended_at": "2026-01-01T00:00:00Z",
          "provider": "string",
          "model": "string",
          "metadata": {}
        }
      ]
    },
    "cost_micro_usd": "string",
    "cost_breakdown": [
      {}
    ],
    "metadata": {},
    "scheduled_callback": {},
    "analysis_status": "heuristic",
    "post_call_webhook_status": "string",
    "post_call_webhook_attempts": 0,
    "post_call_webhook_next_retry_at": "2026-01-01T00:00:00Z",
    "post_call_webhook_delivered_at": "2026-01-01T00:00:00Z",
    "post_call_webhook_error": "string",
    "webhook_deliveries": [
      {
        "endpointId": "string",
        "deliveryId": "string",
        "eventId": "string",
        "delivered": true,
        "status": 0,
        "error": "string",
        "createdAt": "2026-01-01T00:00:00Z"
      }
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "transfers": [
    {
      "id": "string",
      "session_id": "string",
      "organization_id": "string",
      "kind": "blind",
      "status": "requested",
      "transfer_to": "string",
      "from_room_name": "string",
      "consultation_room_name": "string",
      "caller_participant_identity": "string",
      "recipient_participant_identity": "string",
      "outbound_trunk_id": "string",
      "screening_prompt": "string",
      "summary": "string",
      "failure_cause": "string",
      "metadata": {},
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "completed_at": "2026-01-01T00:00:00Z"
    }
  ],
  "transcript": {
    "entries": [
      {
        "id": "string",
        "index": 0,
        "source": "user",
        "text": "string",
        "started_at": "2026-01-01T00:00:00Z",
        "ended_at": "2026-01-01T00:00:00Z",
        "provider": "string",
        "model": "string",
        "metadata": {}
      }
    ]
  },
  "span_tree": {}
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/calls/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## GET /v1/calls/{id}/events

List call events

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Call events

Content type: `application/json`

- `events` (array of object, required)
  - `id` (string, required)
  - `session_id` (string | null, optional)
  - `organization_id` (string, required)
  - `provider` (string, required)
  - `event_type` (string, required)
  - `status` (string | null, optional)
  - `failure_cause` (string | null, optional)
  - `sip_status_code` (integer | null, optional)
  - `sip_status` (string | null, optional)
  - `occurred_at` (string (date-time), required)
  - `payload` (object, required)
  - `created_at` (string (date-time), required)

Example:

```json
{
  "events": [
    {
      "id": "string",
      "session_id": "string",
      "organization_id": "string",
      "provider": "string",
      "event_type": "string",
      "status": "string",
      "failure_cause": "string",
      "sip_status_code": 0,
      "sip_status": "string",
      "occurred_at": "2026-01-01T00:00:00Z",
      "payload": {},
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/calls/{id}/events' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## GET /v1/calls/{id}/report

Get call report

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Call report

Content type: `application/json`

- `session_id` (string, required)
- `organization_id` (string, optional)
- `summary` (string, required)
- `outcome` (string, required)
- `structured_data` (object, optional)
- `custom_data` (object, optional): Caller-defined extraction values keyed by field name, matching the `call.report` webhook. `{}` when the agent declares no extraction fields.
- `transcript` (object, required)
  - `entries` (array of object, optional)
    - `id` (string, required)
    - `index` (integer, required)
    - `source` (string, required): One of: `"user"`, `"agent"`, `"system"`.
    - `text` (string, required)
    - `started_at` (string (date-time), required)
    - `ended_at` (string (date-time) | null, optional)
    - `provider` (string | null, optional)
    - `model` (string | null, optional)
    - `metadata` (object, required)
- `cost_micro_usd` (string, required)
- `cost_breakdown` (array of object, optional)
- `metadata` (object, optional)
- `scheduled_callback` (object, optional)
- `analysis_status` (string, optional): One of: `"heuristic"`, `"completed"`, `"failed"`.
- `post_call_webhook_status` (string, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
- `post_call_webhook_attempts` (integer, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
- `post_call_webhook_next_retry_at` (string (date-time) | null, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
- `post_call_webhook_delivered_at` (string (date-time) | null, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
- `post_call_webhook_error` (string | null, optional): Deprecated aggregate. Use webhook_deliveries. Deprecated.
- `webhook_deliveries` (array of object, required)
  - `endpointId` (string (uuid), required)
  - `deliveryId` (string (uuid), required)
  - `eventId` (string (uuid), required)
  - `delivered` (boolean, required)
  - `status` (integer | null, required)
  - `error` (string | null, required)
  - `createdAt` (string (date-time), required)
- `created_at` (string (date-time), optional)
- `updated_at` (string (date-time), optional)

Example:

```json
{
  "session_id": "string",
  "organization_id": "string",
  "summary": "string",
  "outcome": "string",
  "structured_data": {},
  "custom_data": {},
  "transcript": {
    "entries": [
      {
        "id": "string",
        "index": 0,
        "source": "user",
        "text": "string",
        "started_at": "2026-01-01T00:00:00Z",
        "ended_at": "2026-01-01T00:00:00Z",
        "provider": "string",
        "model": "string",
        "metadata": {}
      }
    ]
  },
  "cost_micro_usd": "string",
  "cost_breakdown": [
    {}
  ],
  "metadata": {},
  "scheduled_callback": {},
  "analysis_status": "heuristic",
  "post_call_webhook_status": "string",
  "post_call_webhook_attempts": 0,
  "post_call_webhook_next_retry_at": "2026-01-01T00:00:00Z",
  "post_call_webhook_delivered_at": "2026-01-01T00:00:00Z",
  "post_call_webhook_error": "string",
  "webhook_deliveries": [
    {
      "endpointId": "string",
      "deliveryId": "string",
      "eventId": "string",
      "delivered": true,
      "status": 0,
      "error": "string",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/calls/{id}/report' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/calls/{id}/report/finalize

Finalize call report

Runs or re-runs analysis for a call and optionally retries post-call webhook delivery.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Request body

Optional.

Content types: `application/json`

- `forceAnalysis` (boolean, optional)
- `retryWebhook` (boolean, optional)

Example body:

```json
{
  "forceAnalysis": true,
  "retryWebhook": true
}
```

### Responses

#### 200: Finalization result

Content type: `application/json`

- `session_id` (string, required)
- `summary` (string, required)
- `outcome` (string, required)
- `cost_micro_usd` (string, required)
- `webhook` (object, required): Deprecated aggregate. Use webhook_deliveries. Deprecated.
- `webhook_deliveries` (array of object, required): Canonical per-endpoint delivery results. The singular webhook field is a deprecated aggregate.
  - `endpointId` (string (uuid), required)
  - `deliveryId` (string (uuid), required)
  - `eventId` (string (uuid), required)
  - `delivered` (boolean, required)
  - `status` (integer | null, required)
  - `error` (string | null, required)
  - `createdAt` (string (date-time), required)

Example:

```json
{
  "session_id": "string",
  "summary": "string",
  "outcome": "string",
  "cost_micro_usd": "string",
  "webhook": {},
  "webhook_deliveries": [
    {
      "endpointId": "string",
      "deliveryId": "string",
      "eventId": "string",
      "delivered": true,
      "status": 0,
      "error": "string",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/calls/{id}/report/finalize' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"forceAnalysis":true,"retryWebhook":true}'
```

## GET /v1/calls/{id}/recording

Get call recording URL

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Signed recording URL

Content type: `application/json`

- `url` (string (uri), required)

Example:

```json
{
  "url": "string"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/calls/{id}/recording' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/calls/{id}/end

End a live session now

Kill switch for any live session — browser/WebRTC sessions included (`calls` routes accept any session id). Deletes the room, which drops every participant; the normal close and metering flow runs via the room webhooks. Idempotent: ending an already-ended session returns `status: "already_ended"`. Use this from your backend to stop billing for a session your client can no longer reach.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Session already ended

Content type: `application/json`

- `ok` (boolean, required)
- `status` (string, required): One of: `"already_ended"`.
- `ended_at` (string (date-time) | null, optional)

Example:

```json
{
  "ok": true,
  "status": "already_ended",
  "ended_at": "2026-01-01T00:00:00Z"
}
```

#### 202: Teardown requested

Content type: `application/json`

- `ok` (boolean, required)
- `status` (string, required): One of: `"ending"`.

Example:

```json
{
  "ok": true,
  "status": "ending"
}
```

#### 400: Session has no room to tear down

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No session with this id in your organization

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/calls/{id}/end' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/calls/{id}/transfers/blind

Start blind transfer

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Request body

Required.

Content types: `application/json`

- `to` (string, required)
- `participantIdentity` (string, optional)
- `playDialtone` (boolean, optional)
- `ringingTimeout` (integer, optional): Min: 1. Max: 120.
- `headers` (object, optional)

Example body:

```json
{
  "to": "string",
  "participantIdentity": "string",
  "playDialtone": true,
  "ringingTimeout": 0,
  "headers": {}
}
```

### Responses

#### 201: Transfer

Content type: `application/json`

- `id` (string, required)
- `session_id` (string, required)
- `organization_id` (string, required)
- `kind` (string, required): One of: `"blind"`, `"warm"`.
- `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
- `transfer_to` (string, required)
- `from_room_name` (string | null, optional)
- `consultation_room_name` (string | null, optional)
- `caller_participant_identity` (string | null, optional)
- `recipient_participant_identity` (string | null, optional)
- `outbound_trunk_id` (string | null, optional)
- `screening_prompt` (string | null, optional)
- `summary` (string | null, optional)
- `failure_cause` (string | null, optional)
- `metadata` (object, required)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)
- `completed_at` (string (date-time) | null, optional)

Example:

```json
{
  "id": "string",
  "session_id": "string",
  "organization_id": "string",
  "kind": "blind",
  "status": "requested",
  "transfer_to": "string",
  "from_room_name": "string",
  "consultation_room_name": "string",
  "caller_participant_identity": "string",
  "recipient_participant_identity": "string",
  "outbound_trunk_id": "string",
  "screening_prompt": "string",
  "summary": "string",
  "failure_cause": "string",
  "metadata": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/calls/{id}/transfers/blind' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"to":"string","participantIdentity":"string","playDialtone":true,"ringingTimeout":0,"headers":{}}'
```

## POST /v1/calls/{id}/transfers/warm

Start warm transfer

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Request body

Required.

Content types: `application/json`

- `to` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
- `destinations` (array of object, optional)
- `from` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
- `participantIdentity` (string, optional)
- `outboundTrunkId` (string, optional)
- `screeningPrompt` (string, optional)
- `summary` (string, optional)
- `ringingTimeout` (integer, optional): Min: 1. Max: 120.
- `waitUntilAnswered` (boolean, optional)
- `fallback` (object, optional)
- `voicemailDetection` (object, optional)
- `metadata` (object, optional)

Example body:

```json
{
  "to": "+12015551234",
  "destinations": [
    {}
  ],
  "from": "+12015551234",
  "participantIdentity": "string",
  "outboundTrunkId": "string",
  "screeningPrompt": "string",
  "summary": "string",
  "ringingTimeout": 0,
  "waitUntilAnswered": true,
  "fallback": {},
  "voicemailDetection": {},
  "metadata": {}
}
```

### Responses

#### 201: Transfer

Content type: `application/json`

- `routing_attempts` (array of object, optional)
  - `id` (string, required)
  - `session_id` (string, required)
  - `organization_id` (string, required)
  - `kind` (string, required): One of: `"blind"`, `"warm"`.
  - `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
  - `transfer_to` (string, required)
  - `from_room_name` (string | null, optional)
  - `consultation_room_name` (string | null, optional)
  - `caller_participant_identity` (string | null, optional)
  - `recipient_participant_identity` (string | null, optional)
  - `outbound_trunk_id` (string | null, optional)
  - `screening_prompt` (string | null, optional)
  - `summary` (string | null, optional)
  - `failure_cause` (string | null, optional)
  - `metadata` (object, required)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
  - `completed_at` (string (date-time) | null, optional)
- `next_transfer` (object, optional)
  - `id` (string, required)
  - `session_id` (string, required)
  - `organization_id` (string, required)
  - `kind` (string, required): One of: `"blind"`, `"warm"`.
  - `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
  - `transfer_to` (string, required)
  - `from_room_name` (string | null, optional)
  - `consultation_room_name` (string | null, optional)
  - `caller_participant_identity` (string | null, optional)
  - `recipient_participant_identity` (string | null, optional)
  - `outbound_trunk_id` (string | null, optional)
  - `screening_prompt` (string | null, optional)
  - `summary` (string | null, optional)
  - `failure_cause` (string | null, optional)
  - `metadata` (object, required)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
  - `completed_at` (string (date-time) | null, optional)
- `fallback` (object, optional)
- `id` (string, required)
- `session_id` (string, required)
- `organization_id` (string, required)
- `kind` (string, required): One of: `"blind"`, `"warm"`.
- `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
- `transfer_to` (string, required)
- `from_room_name` (string | null, optional)
- `consultation_room_name` (string | null, optional)
- `caller_participant_identity` (string | null, optional)
- `recipient_participant_identity` (string | null, optional)
- `outbound_trunk_id` (string | null, optional)
- `screening_prompt` (string | null, optional)
- `summary` (string | null, optional)
- `failure_cause` (string | null, optional)
- `metadata` (object, required)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)
- `completed_at` (string (date-time) | null, optional)

Example:

```json
{
  "routing_attempts": [
    {
      "id": "string",
      "session_id": "string",
      "organization_id": "string",
      "kind": "blind",
      "status": "requested",
      "transfer_to": "string",
      "from_room_name": "string",
      "consultation_room_name": "string",
      "caller_participant_identity": "string",
      "recipient_participant_identity": "string",
      "outbound_trunk_id": "string",
      "screening_prompt": "string",
      "summary": "string",
      "failure_cause": "string",
      "metadata": {},
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "completed_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_transfer": {
    "id": "string",
    "session_id": "string",
    "organization_id": "string",
    "kind": "blind",
    "status": "requested",
    "transfer_to": "string",
    "from_room_name": "string",
    "consultation_room_name": "string",
    "caller_participant_identity": "string",
    "recipient_participant_identity": "string",
    "outbound_trunk_id": "string",
    "screening_prompt": "string",
    "summary": "string",
    "failure_cause": "string",
    "metadata": {},
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "completed_at": "2026-01-01T00:00:00Z"
  },
  "fallback": {},
  "id": "string",
  "session_id": "string",
  "organization_id": "string",
  "kind": "blind",
  "status": "requested",
  "transfer_to": "string",
  "from_room_name": "string",
  "consultation_room_name": "string",
  "caller_participant_identity": "string",
  "recipient_participant_identity": "string",
  "outbound_trunk_id": "string",
  "screening_prompt": "string",
  "summary": "string",
  "failure_cause": "string",
  "metadata": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/calls/{id}/transfers/warm' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"to":"+12015551234","destinations":[{}],"from":"+12015551234","participantIdentity":"string","outboundTrunkId":"string","screeningPrompt":"string","summary":"string","ringingTimeout":0,"waitUntilAnswered":true,"fallback":{},"voicemailDetection":{},"metadata":{}}'
```

## POST /v1/calls/{id}/transfers/{transferId}/complete

Complete warm transfer

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.
- `transferId` (string, in path, required)

### Request body

Optional.

Content types: `application/json`

- `recipientParticipantIdentity` (string, optional)
- `summary` (string, optional)

Example body:

```json
{
  "recipientParticipantIdentity": "string",
  "summary": "string"
}
```

### Responses

#### 200: Transfer

Content type: `application/json`

- `id` (string, required)
- `session_id` (string, required)
- `organization_id` (string, required)
- `kind` (string, required): One of: `"blind"`, `"warm"`.
- `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
- `transfer_to` (string, required)
- `from_room_name` (string | null, optional)
- `consultation_room_name` (string | null, optional)
- `caller_participant_identity` (string | null, optional)
- `recipient_participant_identity` (string | null, optional)
- `outbound_trunk_id` (string | null, optional)
- `screening_prompt` (string | null, optional)
- `summary` (string | null, optional)
- `failure_cause` (string | null, optional)
- `metadata` (object, required)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)
- `completed_at` (string (date-time) | null, optional)

Example:

```json
{
  "id": "string",
  "session_id": "string",
  "organization_id": "string",
  "kind": "blind",
  "status": "requested",
  "transfer_to": "string",
  "from_room_name": "string",
  "consultation_room_name": "string",
  "caller_participant_identity": "string",
  "recipient_participant_identity": "string",
  "outbound_trunk_id": "string",
  "screening_prompt": "string",
  "summary": "string",
  "failure_cause": "string",
  "metadata": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/calls/{id}/transfers/{transferId}/complete' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"recipientParticipantIdentity":"string","summary":"string"}'
```

## POST /v1/calls/{id}/transfers/{transferId}/cancel

Cancel warm transfer

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.
- `transferId` (string, in path, required)

### Request body

Optional.

Content types: `application/json`

- `reason` (string, optional)
- `summary` (string, optional)
- `tryNext` (boolean, optional)
- `voicemailDetected` (boolean, optional)

Example body:

```json
{
  "reason": "string",
  "summary": "string",
  "tryNext": true,
  "voicemailDetected": true
}
```

### Responses

#### 200: Transfer response

Content type: `application/json`

- `routing_attempts` (array of object, optional)
  - `id` (string, required)
  - `session_id` (string, required)
  - `organization_id` (string, required)
  - `kind` (string, required): One of: `"blind"`, `"warm"`.
  - `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
  - `transfer_to` (string, required)
  - `from_room_name` (string | null, optional)
  - `consultation_room_name` (string | null, optional)
  - `caller_participant_identity` (string | null, optional)
  - `recipient_participant_identity` (string | null, optional)
  - `outbound_trunk_id` (string | null, optional)
  - `screening_prompt` (string | null, optional)
  - `summary` (string | null, optional)
  - `failure_cause` (string | null, optional)
  - `metadata` (object, required)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
  - `completed_at` (string (date-time) | null, optional)
- `next_transfer` (object, optional)
  - `id` (string, required)
  - `session_id` (string, required)
  - `organization_id` (string, required)
  - `kind` (string, required): One of: `"blind"`, `"warm"`.
  - `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
  - `transfer_to` (string, required)
  - `from_room_name` (string | null, optional)
  - `consultation_room_name` (string | null, optional)
  - `caller_participant_identity` (string | null, optional)
  - `recipient_participant_identity` (string | null, optional)
  - `outbound_trunk_id` (string | null, optional)
  - `screening_prompt` (string | null, optional)
  - `summary` (string | null, optional)
  - `failure_cause` (string | null, optional)
  - `metadata` (object, required)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
  - `completed_at` (string (date-time) | null, optional)
- `fallback` (object, optional)
- `id` (string, required)
- `session_id` (string, required)
- `organization_id` (string, required)
- `kind` (string, required): One of: `"blind"`, `"warm"`.
- `status` (string, required): One of: `"requested"`, `"screening"`, `"bridging"`, `"completed"`, `"failed"`, `"cancelled"`.
- `transfer_to` (string, required)
- `from_room_name` (string | null, optional)
- `consultation_room_name` (string | null, optional)
- `caller_participant_identity` (string | null, optional)
- `recipient_participant_identity` (string | null, optional)
- `outbound_trunk_id` (string | null, optional)
- `screening_prompt` (string | null, optional)
- `summary` (string | null, optional)
- `failure_cause` (string | null, optional)
- `metadata` (object, required)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)
- `completed_at` (string (date-time) | null, optional)

Example:

```json
{
  "routing_attempts": [
    {
      "id": "string",
      "session_id": "string",
      "organization_id": "string",
      "kind": "blind",
      "status": "requested",
      "transfer_to": "string",
      "from_room_name": "string",
      "consultation_room_name": "string",
      "caller_participant_identity": "string",
      "recipient_participant_identity": "string",
      "outbound_trunk_id": "string",
      "screening_prompt": "string",
      "summary": "string",
      "failure_cause": "string",
      "metadata": {},
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "completed_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_transfer": {
    "id": "string",
    "session_id": "string",
    "organization_id": "string",
    "kind": "blind",
    "status": "requested",
    "transfer_to": "string",
    "from_room_name": "string",
    "consultation_room_name": "string",
    "caller_participant_identity": "string",
    "recipient_participant_identity": "string",
    "outbound_trunk_id": "string",
    "screening_prompt": "string",
    "summary": "string",
    "failure_cause": "string",
    "metadata": {},
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "completed_at": "2026-01-01T00:00:00Z"
  },
  "fallback": {},
  "id": "string",
  "session_id": "string",
  "organization_id": "string",
  "kind": "blind",
  "status": "requested",
  "transfer_to": "string",
  "from_room_name": "string",
  "consultation_room_name": "string",
  "caller_participant_identity": "string",
  "recipient_participant_identity": "string",
  "outbound_trunk_id": "string",
  "screening_prompt": "string",
  "summary": "string",
  "failure_cause": "string",
  "metadata": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/calls/{id}/transfers/{transferId}/cancel' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"string","summary":"string","tryNext":true,"voicemailDetected":true}'
```


# Complete (/api-reference/complete)

Single-turn LLM call routed to the best provider for your intent, with automatic failover. Returns assistant text + token usage.



## POST /v1/complete

Generate an LLM completion

Single-turn LLM call routed to the best provider for your intent, with automatic failover before the first event is emitted. The response is a Server-Sent Events stream: `meta`, `delta`, `tool_call`, `server_tool_call`, `done`, and `error`.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `messages` (array of object, required)
  - `role` (string, required): One of: `"system"`, `"user"`, `"assistant"`, `"tool"`.
  - `content` (string, required)
  - `toolCalls` (array of object, optional)
    - `id` (string, required)
    - `name` (string, required)
    - `args` (string, required): JSON-encoded tool arguments.
  - `toolCallId` (string, optional): Required on `role: tool`; pairs with a prior assistant tool call id.
  - `isError` (boolean, optional): Marks a tool message as an error result.
- `intent` (object, required)
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`. Pattern: `^[a-z]{2}(-[A-Z]{2})?$`.
  - `region` (string, optional): Region whose streaming-latency measurements should be used. `global` falls through to batch-mode rows when no per-region data matches. One of: `"global"`, `"us-east4"`, `"europe-west3"`, `"asia-southeast1"`. Default: `"global"`.
  - `optimizeFor` (string, optional): One of: `"balanced"`, `"accuracy"`, `"latency"`, `"cost"`. Default: `"balanced"`.
- `temperature` (number, optional): Min: 0. Max: 2.
- `maxTokens` (integer, optional): Min: 1.
- `systemPrompt` (string, optional): Forwarded via the canonical system-prompt slot. Don't *also* prepend the same content as a `system` message.
- `constraints` (object, optional)
  - `allowedProviders` (object, optional): Restrict candidate pool per modality. Router still ranks by score. Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
    - `stt` (array of string, optional)
      - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
    - `llm` (array of string, optional)
      - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
    - `tts` (array of string, optional)
      - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
    - `s2s` (array of string, optional)
      - Allowed S2S provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI realtime model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-realtime-2.1"` — only that model). Both forms can be mixed in the same array.
- `reasoningEffort` (string, optional): One of: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`.
- `tools` (array of object, optional)
  - `name` (string, required)
  - `description` (string, required)
  - `parameters` (object, required): JSON Schema parameters object.
  - `executionMode` (string, optional): Where the tool runs. Omit for inline execution. One of: `"inline"`, `"webhook"`, `"builtin"`.
  - `source` (object, optional): Webhook, builtin, or inline execution source config.
- `toolChoice` (string | object, optional)
- `parallelToolCalls` (boolean, optional)
- `maxToolHops` (integer, optional): Min: 1. Max: 16.

Example body:

```json
{
  "messages": [
    {
      "role": "system",
      "content": "string",
      "toolCalls": [
        {
          "id": "string",
          "name": "string",
          "args": "string"
        }
      ],
      "toolCallId": "string",
      "isError": true
    }
  ],
  "intent": {
    "language": "en-US",
    "region": "global",
    "optimizeFor": "balanced"
  },
  "temperature": 0,
  "maxTokens": 0,
  "systemPrompt": "string",
  "constraints": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai"
      ]
    }
  },
  "reasoningEffort": "none",
  "tools": [
    {
      "name": "string",
      "description": "string",
      "parameters": {},
      "executionMode": "inline",
      "source": {}
    }
  ],
  "toolChoice": "auto",
  "parallelToolCalls": true,
  "maxToolHops": 0
}
```

### Responses

#### 200: Completion event stream

Content type: `text/event-stream`

SSE events: `meta`, zero or more `delta` and tool events, final `done` containing a `CompleteResponse`, or `error` after streaming has started.

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 500: No LLM provider available for the intent, or every candidate failed.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "All providers failed",
  "code": "COMPLETE_FAILED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/complete' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"system","content":"string","toolCalls":[{"id":"string","name":"string","args":"string"}],"toolCallId":"string","isError":true}],"intent":{"language":"en-US","region":"global","optimizeFor":"balanced"},"temperature":0,"maxTokens":0,"systemPrompt":"string","constraints":{"allowedProviders":{"stt":["deepgram"],"llm":["openai"],"tts":["elevenlabs"],"s2s":["openai"]}},"reasoningEffort":"none","tools":[{"name":"string","description":"string","parameters":{},"executionMode":"inline","source":{}}],"toolChoice":"auto","parallelToolCalls":true,"maxToolHops":0}'
```


# iMessage phone numbers (/api-reference/imessage-phone-numbers)

Private API for listing dedicated iMessage numbers, placing calls, sending iMessage-first messages, and receiving events.



The iMessage phone-number API is a private, API-only surface enabled for organizations that have dedicated iMessage numbers assigned to them by Speko, plus the internal Speko admin organization. It is separate from the standard `/v1/phone-numbers` inventory.

Use a Speko bearer API key on every request:

```http
Authorization: Bearer sk_live_...
Content-Type: application/json
```

Placing a call and sending a message require a bearer API key; a dashboard session cookie is rejected with `403 API_KEY_REQUIRED`. The read and configuration routes — listing numbers, number tags, and webhook subscriptions — also answer a dashboard session, because **Settings → iMessage** drives them. Speko returns `403 NOT_ENABLED_FOR_ORGANIZATION` when the API has not been enabled for the caller's organization.

## List numbers [#list-numbers]

```http
GET /v1/imessage-phone-numbers
```

The response contains your organization's pool: the dedicated iMessage numbers Speko has assigned to it. Use `id`, not the raw phone number, in call and message requests.

```json
[
  {
    "id": "2b3fb8b3-17ef-4e78-b742-69a4ef55c223",
    "phoneNumber": "+19295550101",
    "status": "active",
    "smsStatus": "ready",
    "smsReadyAt": null,
    "capabilities": {
      "calls": true,
      "messages": true,
      "imessageFirst": true,
      "smsFallback": true
    },
    "tags": {
      "environment": "production"
    },
    "agentId": null
  }
]
```

`tags` are the number's routing tags — see [Tag a number](#tag-a-number). `agentId` names the Speko agent currently answering on the number when a workspace member has selected it on that agent's iMessage page; `null` means the number is available in the pool (turning an agent's iMessage off releases its number back to the pool). Numbers outside your pool are invisible and return `404 PHONE_NUMBER_NOT_FOUND` from the call and message endpoints.

**Transitional behavior:** an organization that was granted API access before pools existed and has no pooled numbers yet sees the historical whole-inventory response (without `agentId`) and may use any unpooled number. Both end the moment its first number is assigned to a pool.

Speko prepares active dedicated numbers for API use behind the scenes, including creating and attaching the provider identity required for sending. Provider identity details are intentionally not exposed. Paused or otherwise unavailable numbers remain visible, but their capability flags are `false` and they cannot be used by the call or message endpoints.

## Tag a number [#tag-a-number]

```http
PUT /v1/imessage-phone-numbers/{phoneNumberId}/tags
```

```json
{
  "tags": {
    "environment": "production",
    "team": "dispatch"
  }
}
```

Number tags use the same key/value shape and limits as webhook subscription tags: at most 20 pairs, keys at most 64 characters, values at most 256. The request replaces the number's tags wholesale — send `{"tags": {}}` to clear them.

Unlike the per-send `tags` field, which describes one outbound message, these apply to **every** event on the line. That makes them the only way to route inbound traffic: an inbound message did not come from a Speko send request, so there is nothing else to match a subscription against. A subscription tagged the same as a number therefore receives that number's inbound *and* outbound events.

```json
{
  "phoneNumberId": "2b3fb8b3-17ef-4e78-b742-69a4ef55c223",
  "phoneNumber": "+19295550101",
  "tags": {
    "environment": "production",
    "team": "dispatch"
  },
  "updatedAt": "2026-07-28T12:00:00.000Z"
}
```

Number tags are part of the shared webhook fan-out, so they are managed by the same organization that manages the subscriptions: other organizations receive `403 NOT_ENABLED_FOR_ORGANIZATION`. A number outside the caller's reach returns `404 PHONE_NUMBER_NOT_FOUND`.

## Place a call [#place-a-call]

```http
POST /v1/imessage-phone-numbers/{phoneNumberId}/calls
```

```json
{
  "to": "+12015551234",
  "agentId": "agent_dispatch",
  "variables": {
    "load_id": "42"
  },
  "metadata": {
    "externalJobId": "job_123"
  },
  "maxDurationSeconds": 900
}
```

`to` must be E.164. `agentId` selects the Speko voice agent that runs the call. `variables`, `metadata`, and `maxDurationSeconds` are optional; the duration must be between 30 and 14,400 seconds.

Speko originates the PSTN leg through Telnyx Call Control and supplies the selected iMessage number as caller ID. After the recipient answers, Telnyx transfers the live call to the Speko agent over the configured SIP bridge. The customer never submits a raw `from` value.

```json
{
  "callId": "0ab83b2f-047e-4b43-a350-8ab948eb84d8",
  "callControlId": "v3:abc123...",
  "status": "dialing",
  "to": "+12015551234",
  "from": "+19295550101",
  "phoneNumberId": "2b3fb8b3-17ef-4e78-b742-69a4ef55c223"
}
```

`callId` is the normal Speko call/session ID. Use it with `/v1/calls/{callId}` and the standard call report, event, recording, and transfer APIs.

## Receive a call [#receive-a-call]

Inbound calls to a dedicated iMessage number are answered by the Speko agent that currently holds the number (the agent selected under **Agents → iMessage → Dedicated number**). No extra configuration is needed on your side: when an agent claims a number, Speko configures the carrier to forward that number's inbound calls to Speko, and releasing the number stops the forwarding. Inbound calls appear as normal Speko calls — `direction: "inbound"`, with the iMessage number as `to` — and support the standard call report, event, recording, and transfer APIs. A pooled number no agent has claimed does not answer.

## Send a message [#send-a-message]

`DEPRECATED` This endpoint is deprecated in favor of the agent-scoped [`POST /v1/imessage/{agentId}/messages`](/api-reference/agent-imessage) and will be removed on **August 14, 2026**.

```http
POST /v1/imessage-phone-numbers/{phoneNumberId}/messages
```

```json
{
  "to": "+12015551234",
  "text": "Load 42 is ready for pickup.",
  "tags": {
    "environment": "production",
    "customer": "acme"
  }
}
```

`tags` is an optional string-to-string object used to route the message's lifecycle webhooks. A request can include at most 20 tags; keys are at most 64 characters and values are at most 256 characters. Matching is case-sensitive.

Speko asks Inkbox to deliver from the selected dedicated identity. Inkbox attempts iMessage first. When the destination is not associated with an Apple ID, the dedicated-line delivery policy may downgrade the message to SMS asynchronously. When Inkbox resolves that downgrade immediately, the response looks like this:

```json
{
  "messageId": "76528fd0-9aeb-43d0-a851-b813fdfaeae0",
  "conversationId": "37f30c7f-565b-45fa-b04c-df29b5af2068",
  "phoneNumberId": "2b3fb8b3-17ef-4e78-b742-69a4ef55c223",
  "to": "+12015551234",
  "attemptedChannel": "imessage",
  "channel": "sms",
  "fallbackApplied": true,
  "deliveryFinal": false,
  "status": "queued",
  "tags": {
    "environment": "production",
    "customer": "acme"
  }
}
```

Inkbox accepts delivery asynchronously. The immediate response is a queued snapshot, not a delivery receipt. While an iMessage attempt is still `registered`, `pending`, `queued`, or `accepted`, `channel` and `fallbackApplied` are `null` because fallback has not been resolved yet:

```json
{
  "messageId": "a6190882-9342-42b6-bf26-85bb6a4f6539",
  "conversationId": "b1166c65-7b35-4d5b-b954-684d754fec8f",
  "phoneNumberId": "d70ffac3-3ebd-4c04-94e0-72fc4a090643",
  "to": "+998905748252",
  "attemptedChannel": "imessage",
  "channel": null,
  "fallbackApplied": null,
  "deliveryFinal": false,
  "status": "pending",
  "tags": {}
}
```

`channel` becomes `imessage`, `sms`, or `rcs` once Inkbox confirms the transport or reports a downgrade. `deliveryFinal` becomes `true` on `delivered`, `declined`, or `error`. Track the authoritative result through the registered `imessage.sent`, `imessage.delivered`, and `imessage.delivery_failed` webhooks.

Do not send a second SMS when the request succeeds: retrying a pending asynchronous delivery through another endpoint can create a duplicate. Retry only failed HTTP requests according to their status and your own idempotency policy.

## Receive webhook events [#receive-webhook-events]

Register each subscriber's HTTPS endpoint at runtime using the same Speko bearer API key as the other phone-number endpoints. This production subscription receives events only for sends tagged with `environment=production`:

```http
PUT /v1/imessage-phone-numbers/webhook
Content-Type: application/json

{
  "url": "https://prod.example.com/webhooks/speko-imessage",
  "tags": {
    "environment": "production"
  }
}
```

By default, the subscription uses the registering organization's global **Webhook signing secret** from the dashboard's **API Keys** page:

```json
{
  "configured": true,
  "id": "3a8f1976-4c76-44c6-97d5-303f8ed0ce81",
  "url": "https://prod.example.com/webhooks/speko-imessage",
  "tags": {
    "environment": "production"
  },
  "signingSecretSource": "organization",
  "eventTypes": [
    "imessage.received",
    "imessage.reaction_received",
    "imessage.sent",
    "imessage.delivered",
    "imessage.delivery_failed"
  ],
  "updatedAt": "2026-07-16T12:00:00.000Z"
}
```

Speko does not mint or return a new secret for each subscription. The organization secret is resolved when each webhook is delivered, so rotating it from the dashboard updates every subscription whose `signingSecretSource` is `organization`.

To use a different secret for one endpoint, provide an explicit `signingSecret` when registering it:

```json
{
  "url": "https://partner.example.com/webhooks/speko-imessage",
  "tags": { "partner": "carrier-a" },
  "signingSecret": "customer-selected-secret"
}
```

The override is encrypted at rest, is never returned by the API, and is reported as `"signingSecretSource": "custom"`. A different URL creates another subscription without affecting existing ones. Calling `PUT` again with the same URL updates that subscription; omitting `signingSecret` switches it back to the organization secret.

Register a catch-all endpoint by omitting `tags` or passing `{}`. It receives every event, including inbound messages and events for sends that did not include tags:

```json
{
  "url": "https://audit.example.com/webhooks/speko-imessage"
}
```

A tagged subscription matches when every key/value pair configured on the subscription is present on the event. Extra event tags do not prevent a match. For example, the production subscription above matches `{ "environment": "production", "customer": "acme" }`, but not `{ "environment": "staging" }` or an untagged event.

An event's tags come from two places, merged per event:

1. The **number's** tags (see [Tag a number](#tag-a-number)), which apply to every event on that line, in both directions.
2. The **send request's** `tags`, which apply to that message's lifecycle events only. On a shared key the send's value wins, being the more specific statement.

So an inbound message carries exactly its receiving number's tags — that is what lets a tagged subscription receive inbound traffic at all. An untagged number still reaches only catch-all subscriptions. Reactions to an outbound message use the tags from the original send, merged over the number's.

List subscriptions without exposing their secrets:

```http
GET /v1/imessage-phone-numbers/webhook
```

```json
{
  "configured": true,
  "subscriptions": [
    {
      "id": "3a8f1976-4c76-44c6-97d5-303f8ed0ce81",
      "url": "https://prod.example.com/webhooks/speko-imessage",
      "tags": { "environment": "production" },
      "signingSecretSource": "organization",
      "eventTypes": [
        "imessage.received",
        "imessage.reaction_received",
        "imessage.sent",
        "imessage.delivered",
        "imessage.delivery_failed"
      ],
      "updatedAt": "2026-07-16T12:00:00.000Z"
    }
  ]
}
```

Remove one subscription by ID:

```http
DELETE /v1/imessage-phone-numbers/webhook/3a8f1976-4c76-44c6-97d5-303f8ed0ce81
```

Remove all subscriptions and stop forwarding events:

```http
DELETE /v1/imessage-phone-numbers/webhook
```

Subscriptions are shared by the customer and Speko admin organizations because they manage the same private phone-number integration. Dashboard sessions cannot manage them; API-key authentication is required.

Every subscriber delivery is visible in **Settings → iMessage → Webhooks**, where each subscription has its own log, and in **Settings → Webhooks → Logs** alongside workspace endpoints, for the organization that registered that endpoint. Logs include the stable Inkbox event ID, routing tags, sanitized request headers and body, bounded response body, HTTP result, duration, and every provider-triggered attempt. They are retained for 30 days even if the API subscription is later deleted. Inkbox controls retries for these events, so manual redelivery is not available from the dashboard or delivery API.

Speko registers a separate Inkbox ingress subscription for every active number returned by the list endpoint, receives all iMessage event types, and then applies the subscriber tag predicates described above:

| Event                        | Meaning                                                      |
| ---------------------------- | ------------------------------------------------------------ |
| `imessage.received`          | A message arrived from the remote number.                    |
| `imessage.reaction_received` | A reaction or tapback arrived.                               |
| `imessage.sent`              | Inkbox accepted an outbound message.                         |
| `imessage.delivered`         | The carrier or iMessage service reported delivery.           |
| `imessage.delivery_failed`   | Delivery failed; the message contains provider error fields. |

The POST body is the original Inkbox JSON event, unchanged. Routing tags are used by Speko to choose endpoints; they are not injected into the provider event body. For example:

```json
{
  "id": "evt_01JZ...",
  "event_type": "imessage.delivered",
  "timestamp": "2026-07-16T09:30:00.000Z",
  "data": {
    "message": {
      "id": "76528fd0-9aeb-43d0-a851-b813fdfaeae0",
      "conversation_id": "37f30c7f-565b-45fa-b04c-df29b5af2068",
      "remote_number": "+12015551234",
      "service": "imessage",
      "status": "delivered"
    },
    "reaction": null,
    "contacts": [],
    "agent_identities": []
  }
}
```

Speko adds these headers:

| Header                       | Value                                                                   |
| ---------------------------- | ----------------------------------------------------------------------- |
| `webhook-id`                 | The stable Inkbox event ID. Deduplicate deliveries on this value.       |
| `webhook-timestamp`          | Unix timestamp used by the signature.                                   |
| `webhook-signature`          | Standard Webhooks HMAC-SHA256 signature (`v1,...`).                     |
| `x-speko-phone-number-id`    | The same stable number ID returned by `GET /v1/imessage-phone-numbers`. |
| `x-speko-phone-number`       | The managed E.164 number.                                               |
| `x-speko-inkbox-identity-id` | The internal Inkbox identity ID backing the managed number.             |
| `x-speko-event-type`         | The event type from the body.                                           |

Verify `webhook-signature` against the **raw request body** using the organization's dashboard webhook secret, or the custom secret supplied for that subscription. Do not parse and re-serialize JSON before verification. Also reject stale `webhook-timestamp` values; a five-minute tolerance is recommended.

Each request carries more than one `v1,` token. Speko signs under two key derivations — the secret's raw bytes, and the Standard Webhooks derivation of stripping `whsec_` and base64-decoding the remainder — so either style of verifier matches. Accept the request if **any** token matches, as the spec requires; never assume there is exactly one.

<Warning>
  If your signing secret contains `-` or `_`, it predates 2026-07-28 and was minted
  with the base64url alphabet. Strict base64 decoders reject it outright — the
  `standardwebhooks` package throws `Base64Coder: incorrect characters for decoding`
  in its constructor. Either rotate the secret to get a current-format one, or build
  the verifier with `new Webhook(secret, { format: 'raw' })`. The same applies to a
  custom `signingSecret` that is not `whsec_` + standard base64.
</Warning>

Return any `2xx` response after durably accepting an event. A timeout or non-`2xx` response makes the pass-through delivery fail, and Inkbox may retry the same event. Retries retain the same `webhook-id`, so handlers must be idempotent.

## Errors [#errors]

| Status    | Code                             | Meaning                                                                                  |
| --------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
| `400`     | validation error                 | The ID, E.164 number, body, or duration is invalid.                                      |
| `402`     | `INSUFFICIENT_CREDITS`           | The organization has no positive Speko credit balance for a call.                        |
| `403`     | `API_KEY_REQUIRED`               | Authentication was not a Speko bearer API key.                                           |
| `403`     | `NOT_ENABLED_FOR_ORGANIZATION`   | The private API is not enabled for this organization.                                    |
| `404`     | `PHONE_NUMBER_NOT_FOUND`         | The number ID is unknown, inactive, released, or no longer iMessage-enabled.             |
| `409`     | `CALLER_ID_VERIFICATION_PENDING` | The number is not yet enabled as an outbound caller ID. Retry after `retryAfterSeconds`. |
| `4xx/502` | `MESSAGE_SEND_FAILED`            | Inkbox rejected the message or its service was unavailable.                              |
| `502`     | `TELNYX_DIAL_FAILED`             | Telnyx rejected the outbound call or could not originate it.                             |


# Introduction (/api-reference/introduction)

Public REST API for the Speko voice gateway.



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

<Card title="OpenAPI specification" icon="file-code" href="https://github.com/SpekoAI/docs/blob/main/api-reference/openapi.json">
  View the OpenAPI 3.1 spec file
</Card>

## Servers [#servers]

| Environment | Base URL                |
| ----------- | ----------------------- |
| Production  | `https://api.speko.dev` |

## Authentication [#authentication]

All endpoints are authenticated with a bearer API key. Mint one at [API keys](https://platform.speko.ai/agents/keys).

```http
Authorization: Bearer sk_live_...
```

The OpenAPI spec declares this scheme as `bearerAuth`:

```json
"security": [
  {
    "bearerAuth": []
  }
]
```


# Phone numbers (/api-reference/phone-numbers)

Provision managed numbers, import SIP-trunk numbers, update routing, and manage phone-number business verification.



## GET /v1/phone-numbers

List phone numbers

Returns managed and customer SIP-trunk phone numbers registered to the authenticated organization.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: Organization phone numbers

Content type: `application/json`

- Items (object):
  - `id` (string, required)
  - `organizationId` (string, required)
  - `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
  - `source` (string, required): One of: `"managed"`, `"sip_trunk"`.
  - `providerResourceId` (string | null, optional)
  - `telnyxPhoneNumberId` (string | null, optional): Deprecated.
  - `sipTrunkId` (string | null, optional): Deprecated.
  - `sipConnectionInstallationId` (string | null, optional)
  - `sipProviderName` (string | null, optional)
  - `direction` (string, required): One of: `"inbound"`, `"outbound"`, `"both"`.
  - `dispatchMetadataTemplate` (object | null, optional)
  - `agentId` (string | null, optional)
  - `routeToBrokerId` (string | null, optional): Org-defined broker id whose softphone this number rings instead of an agent. Mutually exclusive with `agentId` — setting one clears the other. Requires human calling to be enabled for the workspace.
  - `label` (string | null, optional)
  - `sms10dlcProfileId` (string | null, optional)
  - `smsCampaignId` (string | null, optional)
  - `smsAssignmentStatus` (string | null, optional)
  - `smsAssignmentUpdatedAt` (string (date-time) | null, optional)
  - `telnyxMessagingProfileId` (string | null, optional)
  - `smsMessagingProfileStatus` (string, optional): One of: `"pending"`, `"ready"`, `"failed"`.
  - `smsMessagingProfileUpdatedAt` (string (date-time) | null, optional)
  - `smsMessagingProfileError` (string | null, optional)
  - `smsAutomationEnabled` (boolean, optional)
  - `setupStatus` (object, required)
    - `status` (string, required): One of: `"ready"`, `"action_required"`, `"suspended"`.
    - `inboundReady` (boolean, required)
    - `outboundReady` (boolean, required)
    - `agentReady` (boolean, required)
    - `forwardingRequired` (boolean, required)
    - `sipConnectionReady` (boolean, required)
    - `issues` (array of string, required)
  - `nextChargeAt` (string (date-time), optional)
  - `lastChargedAt` (string (date-time) | null, optional)
  - `suspendedAt` (string (date-time) | null, optional): Effective suspension timestamp retained for older clients. Compliance takes precedence when both compliance and billing holds are active.
  - `billingSuspendedAt` (string (date-time) | null, optional)
  - `complianceSuspendedAt` (string (date-time) | null, optional)
  - `suspensionReason` (string | null, optional): One of: `"billing"`, `"compliance"`.
  - `createdAt` (string (date-time), required)
  - `updatedAt` (string (date-time), required)

Example:

```json
[
  {
    "id": "string",
    "organizationId": "string",
    "e164": "+12015551234",
    "source": "managed",
    "providerResourceId": "string",
    "telnyxPhoneNumberId": "string",
    "sipTrunkId": "string",
    "sipConnectionInstallationId": "string",
    "sipProviderName": "string",
    "direction": "inbound",
    "dispatchMetadataTemplate": {},
    "agentId": "string",
    "routeToBrokerId": "string",
    "label": "string",
    "sms10dlcProfileId": "string",
    "smsCampaignId": "string",
    "smsAssignmentStatus": "string",
    "smsAssignmentUpdatedAt": "2026-01-01T00:00:00Z",
    "telnyxMessagingProfileId": "string",
    "smsMessagingProfileStatus": "pending",
    "smsMessagingProfileUpdatedAt": "2026-01-01T00:00:00Z",
    "smsMessagingProfileError": "string",
    "smsAutomationEnabled": true,
    "setupStatus": {
      "status": "ready",
      "inboundReady": true,
      "outboundReady": true,
      "agentReady": true,
      "forwardingRequired": true,
      "sipConnectionReady": true,
      "issues": [
        "string"
      ]
    },
    "nextChargeAt": "2026-01-01T00:00:00Z",
    "lastChargedAt": "2026-01-01T00:00:00Z",
    "suspendedAt": "2026-01-01T00:00:00Z",
    "billingSuspendedAt": "2026-01-01T00:00:00Z",
    "complianceSuspendedAt": "2026-01-01T00:00:00Z",
    "suspensionReason": "billing",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z"
  }
]
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/phone-numbers' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/phone-numbers

Buy a managed phone number

Orders a platform-managed phone number and registers it for inbound and/or outbound calling. A current business declaration, no compliance hold, the global purchase switch, and sufficient credits are required.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object, optional)
- `label` (string, optional)
- `agentId` (string, optional)

Example body:

```json
{
  "e164": "+12015551234",
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "label": "string",
  "agentId": "string"
}
```

### Responses

#### 200: Phone number

Content type: `application/json`

- `id` (string, required)
- `organizationId` (string, required)
- `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `source` (string, required): One of: `"managed"`, `"sip_trunk"`.
- `providerResourceId` (string | null, optional)
- `telnyxPhoneNumberId` (string | null, optional): Deprecated.
- `sipTrunkId` (string | null, optional): Deprecated.
- `sipConnectionInstallationId` (string | null, optional)
- `sipProviderName` (string | null, optional)
- `direction` (string, required): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object | null, optional)
- `agentId` (string | null, optional)
- `routeToBrokerId` (string | null, optional): Org-defined broker id whose softphone this number rings instead of an agent. Mutually exclusive with `agentId` — setting one clears the other. Requires human calling to be enabled for the workspace.
- `label` (string | null, optional)
- `sms10dlcProfileId` (string | null, optional)
- `smsCampaignId` (string | null, optional)
- `smsAssignmentStatus` (string | null, optional)
- `smsAssignmentUpdatedAt` (string (date-time) | null, optional)
- `telnyxMessagingProfileId` (string | null, optional)
- `smsMessagingProfileStatus` (string, optional): One of: `"pending"`, `"ready"`, `"failed"`.
- `smsMessagingProfileUpdatedAt` (string (date-time) | null, optional)
- `smsMessagingProfileError` (string | null, optional)
- `smsAutomationEnabled` (boolean, optional)
- `setupStatus` (object, required)
  - `status` (string, required): One of: `"ready"`, `"action_required"`, `"suspended"`.
  - `inboundReady` (boolean, required)
  - `outboundReady` (boolean, required)
  - `agentReady` (boolean, required)
  - `forwardingRequired` (boolean, required)
  - `sipConnectionReady` (boolean, required)
  - `issues` (array of string, required)
- `nextChargeAt` (string (date-time), optional)
- `lastChargedAt` (string (date-time) | null, optional)
- `suspendedAt` (string (date-time) | null, optional): Effective suspension timestamp retained for older clients. Compliance takes precedence when both compliance and billing holds are active.
- `billingSuspendedAt` (string (date-time) | null, optional)
- `complianceSuspendedAt` (string (date-time) | null, optional)
- `suspensionReason` (string | null, optional): One of: `"billing"`, `"compliance"`.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organizationId": "string",
  "e164": "+12015551234",
  "source": "managed",
  "providerResourceId": "string",
  "telnyxPhoneNumberId": "string",
  "sipTrunkId": "string",
  "sipConnectionInstallationId": "string",
  "sipProviderName": "string",
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "agentId": "string",
  "routeToBrokerId": "string",
  "label": "string",
  "sms10dlcProfileId": "string",
  "smsCampaignId": "string",
  "smsAssignmentStatus": "string",
  "smsAssignmentUpdatedAt": "2026-01-01T00:00:00Z",
  "telnyxMessagingProfileId": "string",
  "smsMessagingProfileStatus": "pending",
  "smsMessagingProfileUpdatedAt": "2026-01-01T00:00:00Z",
  "smsMessagingProfileError": "string",
  "smsAutomationEnabled": true,
  "setupStatus": {
    "status": "ready",
    "inboundReady": true,
    "outboundReady": true,
    "agentReady": true,
    "forwardingRequired": true,
    "sipConnectionReady": true,
    "issues": [
      "string"
    ]
  },
  "nextChargeAt": "2026-01-01T00:00:00Z",
  "lastChargedAt": "2026-01-01T00:00:00Z",
  "suspendedAt": "2026-01-01T00:00:00Z",
  "billingSuspendedAt": "2026-01-01T00:00:00Z",
  "complianceSuspendedAt": "2026-01-01T00:00:00Z",
  "suspensionReason": "billing",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/phone-numbers' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"e164":"+12015551234","direction":"inbound","dispatchMetadataTemplate":{},"label":"string","agentId":"string"}'
```

## GET /v1/phone-numbers/available

Search available managed numbers

Searches the platform-managed phone-number pool. A current phone-number business declaration, no compliance hold, and the buy-phone-numbers feature flag are required.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `areaCode` (string, in query, optional): Pattern: `^\d{3}$`.
- `locality` (string, in query, optional)
- `limit` (integer, in query, optional): Default: `10`. Min: 1. Max: 50.

### Responses

#### 200: Available numbers

Content type: `application/json`

- Items (object):
  - `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
  - `friendlyName` (string, required)
  - `monthlyCostUsd` (number, required)
  - `upfrontCostUsd` (number, required)
  - `features` (array of string, required)
  - `region` (object, required)

Example:

```json
[
  {
    "e164": "+12015551234",
    "friendlyName": "string",
    "monthlyCostUsd": 0,
    "upfrontCostUsd": 0,
    "features": [
      "string"
    ],
    "region": {}
  }
]
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/phone-numbers/available' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/phone-numbers/import

Import a SIP trunk phone number

Registers a customer-owned phone number from an installed SIP connection or a legacy outbound trunk id.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `sipConnectionInstallationId` (string, optional): Installed SIP connection integration id. Preferred for new imports.
- `sipTrunkId` (string, optional): Legacy outbound trunk id. Required when `sipConnectionInstallationId` is omitted.
- `sipProviderName` (string, optional)
- `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object, optional)
- `label` (string, optional)
- `agentId` (string, optional)

Example body:

```json
{
  "e164": "+12015551234",
  "sipConnectionInstallationId": "string",
  "sipTrunkId": "string",
  "sipProviderName": "string",
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "label": "string",
  "agentId": "string"
}
```

### Responses

#### 200: Phone number

Content type: `application/json`

- `id` (string, required)
- `organizationId` (string, required)
- `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `source` (string, required): One of: `"managed"`, `"sip_trunk"`.
- `providerResourceId` (string | null, optional)
- `telnyxPhoneNumberId` (string | null, optional): Deprecated.
- `sipTrunkId` (string | null, optional): Deprecated.
- `sipConnectionInstallationId` (string | null, optional)
- `sipProviderName` (string | null, optional)
- `direction` (string, required): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object | null, optional)
- `agentId` (string | null, optional)
- `routeToBrokerId` (string | null, optional): Org-defined broker id whose softphone this number rings instead of an agent. Mutually exclusive with `agentId` — setting one clears the other. Requires human calling to be enabled for the workspace.
- `label` (string | null, optional)
- `sms10dlcProfileId` (string | null, optional)
- `smsCampaignId` (string | null, optional)
- `smsAssignmentStatus` (string | null, optional)
- `smsAssignmentUpdatedAt` (string (date-time) | null, optional)
- `telnyxMessagingProfileId` (string | null, optional)
- `smsMessagingProfileStatus` (string, optional): One of: `"pending"`, `"ready"`, `"failed"`.
- `smsMessagingProfileUpdatedAt` (string (date-time) | null, optional)
- `smsMessagingProfileError` (string | null, optional)
- `smsAutomationEnabled` (boolean, optional)
- `setupStatus` (object, required)
  - `status` (string, required): One of: `"ready"`, `"action_required"`, `"suspended"`.
  - `inboundReady` (boolean, required)
  - `outboundReady` (boolean, required)
  - `agentReady` (boolean, required)
  - `forwardingRequired` (boolean, required)
  - `sipConnectionReady` (boolean, required)
  - `issues` (array of string, required)
- `nextChargeAt` (string (date-time), optional)
- `lastChargedAt` (string (date-time) | null, optional)
- `suspendedAt` (string (date-time) | null, optional): Effective suspension timestamp retained for older clients. Compliance takes precedence when both compliance and billing holds are active.
- `billingSuspendedAt` (string (date-time) | null, optional)
- `complianceSuspendedAt` (string (date-time) | null, optional)
- `suspensionReason` (string | null, optional): One of: `"billing"`, `"compliance"`.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organizationId": "string",
  "e164": "+12015551234",
  "source": "managed",
  "providerResourceId": "string",
  "telnyxPhoneNumberId": "string",
  "sipTrunkId": "string",
  "sipConnectionInstallationId": "string",
  "sipProviderName": "string",
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "agentId": "string",
  "routeToBrokerId": "string",
  "label": "string",
  "sms10dlcProfileId": "string",
  "smsCampaignId": "string",
  "smsAssignmentStatus": "string",
  "smsAssignmentUpdatedAt": "2026-01-01T00:00:00Z",
  "telnyxMessagingProfileId": "string",
  "smsMessagingProfileStatus": "pending",
  "smsMessagingProfileUpdatedAt": "2026-01-01T00:00:00Z",
  "smsMessagingProfileError": "string",
  "smsAutomationEnabled": true,
  "setupStatus": {
    "status": "ready",
    "inboundReady": true,
    "outboundReady": true,
    "agentReady": true,
    "forwardingRequired": true,
    "sipConnectionReady": true,
    "issues": [
      "string"
    ]
  },
  "nextChargeAt": "2026-01-01T00:00:00Z",
  "lastChargedAt": "2026-01-01T00:00:00Z",
  "suspendedAt": "2026-01-01T00:00:00Z",
  "billingSuspendedAt": "2026-01-01T00:00:00Z",
  "complianceSuspendedAt": "2026-01-01T00:00:00Z",
  "suspensionReason": "billing",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/phone-numbers/import' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"e164":"+12015551234","sipConnectionInstallationId":"string","sipTrunkId":"string","sipProviderName":"string","direction":"inbound","dispatchMetadataTemplate":{},"label":"string","agentId":"string"}'
```

## GET /v1/phone-numbers/kyb

Get phone-number business verification

Returns the latest business declaration, immutable attestor snapshot, current attestation contract, compliance access state, and optional legacy 10DLC-derived prefill.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: Business verification state

Content type: `application/json`

- `status` (string, required): One of: `"missing"`, `"draft"`, `"submitted"`, `"approved"`, `"rejected"`, `"revoked"`.
- `submission` (object | null, required)
  - `id` (string, required)
  - `organizationId` (string, required)
  - `status` (string, required): One of: `"draft"`, `"submitted"`, `"approved"`, `"rejected"`, `"revoked"`.
  - `businessProfile` (object, optional)
    - `legalName` (string, required)
    - `displayName` (string, required)
    - `entityType` (string, required)
    - `country` (string, required)
    - `registrationId` (string, optional)
    - `website` (string (uri), required)
    - `address` (object, required)
    - `useCase` (string, required)
    - `expectedUsage` (string, required)
  - `authorizedRepresentative` (object, optional)
    - `name` (string, required)
    - `title` (string, required)
    - `email` (string (email), required)
    - `phone` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
  - `declaration` (object | null, optional)
    - `businessName` (string, required)
    - `useCase` (string, required)
  - `attestor` (object, optional)
    - Variant (object):
      - `kind` (string, required): One of: `"user"`.
      - `userId` (string, required)
      - `name` (string, required)
      - `email` (string (email), required)
      - `organizationRole` (string | null, optional)
    - Variant (object):
      - `kind` (string, required): One of: `"api_key"`.
      - `apiKeyId` (string, required)
  - `attestationAccepted` (boolean, required)
  - `attestationVersion` (string | null, optional)
  - `attestationText` (string | null, optional)
  - `termsVersion` (string | null, optional)
  - `attestedAt` (string (date-time) | null, optional)
  - `accessHoldAt` (string (date-time) | null, optional)
  - `accessHoldReason` (string | null, optional): One of: `"rejected"`, `"revoked"`.
  - `submittedByUserId` (string | null, optional)
  - `submittedByEmail` (string (email) | null, optional)
  - `submittedByApiKeyId` (string | null, optional)
  - `submittedAt` (string (date-time) | null, optional)
  - `reviewerUserId` (string | null, optional)
  - `reviewerEmail` (string (email) | null, optional)
  - `reviewedAt` (string (date-time) | null, optional)
  - `rejectionReason` (string | null, optional)
  - `slackNotificationStatus` (string, optional): One of: `"not_queued"`, `"queued"`, `"enqueue_failed"`.
  - `slackNotificationJobId` (string | null, optional)
  - `slackNotificationError` (string | null, optional)
  - `createdAt` (string (date-time), required)
  - `updatedAt` (string (date-time), required)
- `declarationPrefill` (object, required)
  - `businessName` (string, required)
  - `useCase` (string, required)
- `requiredAttestation` (object, required)
  - `version` (string, required)
  - `text` (string, required)
  - `termsVersion` (string, required)
  - `termsUrl` (string (uri), required)
- `attestationRequired` (boolean, required)
- `complianceAccess` (string, required): One of: `"enabled"`, `"awaiting_attestation"`, `"suspended"`.
- `prefill` (object | null, required)
  - `businessProfile` (object, optional)
    - `legalName` (string, required)
    - `displayName` (string, required)
    - `entityType` (string, required)
    - `country` (string, required)
    - `registrationId` (string, optional)
    - `website` (string (uri), required)
    - `address` (object, required)
    - `useCase` (string, required)
    - `expectedUsage` (string, required)
  - `authorizedRepresentative` (object, optional)
    - `name` (string, required)
    - `title` (string, required)
    - `email` (string (email), required)
    - `phone` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.

Example:

```json
{
  "status": "missing",
  "submission": {
    "id": "string",
    "organizationId": "string",
    "status": "draft",
    "businessProfile": {
      "legalName": "string",
      "displayName": "string",
      "entityType": "string",
      "country": "string",
      "registrationId": "string",
      "website": "string",
      "address": {},
      "useCase": "string",
      "expectedUsage": "string"
    },
    "authorizedRepresentative": {
      "name": "string",
      "title": "string",
      "email": "string",
      "phone": "+12015551234"
    },
    "declaration": {
      "businessName": "string",
      "useCase": "string"
    },
    "attestor": {
      "kind": "user",
      "userId": "string",
      "name": "string",
      "email": "string",
      "organizationRole": "string"
    },
    "attestationAccepted": true,
    "attestationVersion": "string",
    "attestationText": "string",
    "termsVersion": "string",
    "attestedAt": "2026-01-01T00:00:00Z",
    "accessHoldAt": "2026-01-01T00:00:00Z",
    "accessHoldReason": "rejected",
    "submittedByUserId": "string",
    "submittedByEmail": "string",
    "submittedByApiKeyId": "string",
    "submittedAt": "2026-01-01T00:00:00Z",
    "reviewerUserId": "string",
    "reviewerEmail": "string",
    "reviewedAt": "2026-01-01T00:00:00Z",
    "rejectionReason": "string",
    "slackNotificationStatus": "not_queued",
    "slackNotificationJobId": "string",
    "slackNotificationError": "string",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z"
  },
  "declarationPrefill": {
    "businessName": "string",
    "useCase": "string"
  },
  "requiredAttestation": {
    "version": "string",
    "text": "string",
    "termsVersion": "string",
    "termsUrl": "string"
  },
  "attestationRequired": true,
  "complianceAccess": "enabled",
  "prefill": {
    "businessProfile": {
      "legalName": "string",
      "displayName": "string",
      "entityType": "string",
      "country": "string",
      "registrationId": "string",
      "website": "string",
      "address": {},
      "useCase": "string",
      "expectedUsage": "string"
    },
    "authorizedRepresentative": {
      "name": "string",
      "title": "string",
      "email": "string",
      "phone": "+12015551234"
    }
  }
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/phone-numbers/kyb' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## PUT /v1/phone-numbers/kyb/draft

Save phone-number business verification draft

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `businessProfile` (object, required)
  - `legalName` (string, required)
  - `displayName` (string, required)
  - `entityType` (string, required)
  - `country` (string, required)
  - `registrationId` (string, optional)
  - `website` (string (uri), required)
  - `address` (object, required)
  - `useCase` (string, required)
  - `expectedUsage` (string, required)
- `authorizedRepresentative` (object, required)
  - `name` (string, required)
  - `title` (string, required)
  - `email` (string (email), required)
  - `phone` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
- `attestationAccepted` (boolean, optional): Default: `false`.

Example body:

```json
{
  "businessProfile": {
    "legalName": "string",
    "displayName": "string",
    "entityType": "string",
    "country": "string",
    "registrationId": "string",
    "website": "string",
    "address": {},
    "useCase": "string",
    "expectedUsage": "string"
  },
  "authorizedRepresentative": {
    "name": "string",
    "title": "string",
    "email": "string",
    "phone": "+12015551234"
  },
  "attestationAccepted": false
}
```

### Responses

#### 200: Saved draft

Content type: `application/json`

- `id` (string, required)
- `organizationId` (string, required)
- `status` (string, required): One of: `"draft"`, `"submitted"`, `"approved"`, `"rejected"`, `"revoked"`.
- `businessProfile` (object, optional)
  - `legalName` (string, required)
  - `displayName` (string, required)
  - `entityType` (string, required)
  - `country` (string, required)
  - `registrationId` (string, optional)
  - `website` (string (uri), required)
  - `address` (object, required)
  - `useCase` (string, required)
  - `expectedUsage` (string, required)
- `authorizedRepresentative` (object, optional)
  - `name` (string, required)
  - `title` (string, required)
  - `email` (string (email), required)
  - `phone` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
- `declaration` (object | null, optional)
  - `businessName` (string, required)
  - `useCase` (string, required)
- `attestor` (object, optional)
  - Variant (object):
    - `kind` (string, required): One of: `"user"`.
    - `userId` (string, required)
    - `name` (string, required)
    - `email` (string (email), required)
    - `organizationRole` (string | null, optional)
  - Variant (object):
    - `kind` (string, required): One of: `"api_key"`.
    - `apiKeyId` (string, required)
- `attestationAccepted` (boolean, required)
- `attestationVersion` (string | null, optional)
- `attestationText` (string | null, optional)
- `termsVersion` (string | null, optional)
- `attestedAt` (string (date-time) | null, optional)
- `accessHoldAt` (string (date-time) | null, optional)
- `accessHoldReason` (string | null, optional): One of: `"rejected"`, `"revoked"`.
- `submittedByUserId` (string | null, optional)
- `submittedByEmail` (string (email) | null, optional)
- `submittedByApiKeyId` (string | null, optional)
- `submittedAt` (string (date-time) | null, optional)
- `reviewerUserId` (string | null, optional)
- `reviewerEmail` (string (email) | null, optional)
- `reviewedAt` (string (date-time) | null, optional)
- `rejectionReason` (string | null, optional)
- `slackNotificationStatus` (string, optional): One of: `"not_queued"`, `"queued"`, `"enqueue_failed"`.
- `slackNotificationJobId` (string | null, optional)
- `slackNotificationError` (string | null, optional)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organizationId": "string",
  "status": "draft",
  "businessProfile": {
    "legalName": "string",
    "displayName": "string",
    "entityType": "string",
    "country": "string",
    "registrationId": "string",
    "website": "string",
    "address": {},
    "useCase": "string",
    "expectedUsage": "string"
  },
  "authorizedRepresentative": {
    "name": "string",
    "title": "string",
    "email": "string",
    "phone": "+12015551234"
  },
  "declaration": {
    "businessName": "string",
    "useCase": "string"
  },
  "attestor": {
    "kind": "user",
    "userId": "string",
    "name": "string",
    "email": "string",
    "organizationRole": "string"
  },
  "attestationAccepted": true,
  "attestationVersion": "string",
  "attestationText": "string",
  "termsVersion": "string",
  "attestedAt": "2026-01-01T00:00:00Z",
  "accessHoldAt": "2026-01-01T00:00:00Z",
  "accessHoldReason": "rejected",
  "submittedByUserId": "string",
  "submittedByEmail": "string",
  "submittedByApiKeyId": "string",
  "submittedAt": "2026-01-01T00:00:00Z",
  "reviewerUserId": "string",
  "reviewerEmail": "string",
  "reviewedAt": "2026-01-01T00:00:00Z",
  "rejectionReason": "string",
  "slackNotificationStatus": "not_queued",
  "slackNotificationJobId": "string",
  "slackNotificationError": "string",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X PUT 'https://api.speko.dev/v1/phone-numbers/kyb/draft' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"businessProfile":{"legalName":"string","displayName":"string","entityType":"string","country":"string","registrationId":"string","website":"string","address":{},"useCase":"string","expectedUsage":"string"},"authorizedRepresentative":{"name":"string","title":"string","email":"string","phone":"+12015551234"},"attestationAccepted":false}'
```

## POST /v1/phone-numbers/kyb/submit

Submit phone-number business verification

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

Example body:

```json
{
  "declaration": {
    "businessName": "string",
    "useCase": "string"
  },
  "attestationAccepted": true,
  "attestationVersion": "string"
}
```

### Responses

#### 200: Submitted verification

Content type: `application/json`

- `id` (string, required)
- `organizationId` (string, required)
- `status` (string, required): One of: `"draft"`, `"submitted"`, `"approved"`, `"rejected"`, `"revoked"`.
- `businessProfile` (object, optional)
  - `legalName` (string, required)
  - `displayName` (string, required)
  - `entityType` (string, required)
  - `country` (string, required)
  - `registrationId` (string, optional)
  - `website` (string (uri), required)
  - `address` (object, required)
  - `useCase` (string, required)
  - `expectedUsage` (string, required)
- `authorizedRepresentative` (object, optional)
  - `name` (string, required)
  - `title` (string, required)
  - `email` (string (email), required)
  - `phone` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
- `declaration` (object | null, optional)
  - `businessName` (string, required)
  - `useCase` (string, required)
- `attestor` (object, optional)
  - Variant (object):
    - `kind` (string, required): One of: `"user"`.
    - `userId` (string, required)
    - `name` (string, required)
    - `email` (string (email), required)
    - `organizationRole` (string | null, optional)
  - Variant (object):
    - `kind` (string, required): One of: `"api_key"`.
    - `apiKeyId` (string, required)
- `attestationAccepted` (boolean, required)
- `attestationVersion` (string | null, optional)
- `attestationText` (string | null, optional)
- `termsVersion` (string | null, optional)
- `attestedAt` (string (date-time) | null, optional)
- `accessHoldAt` (string (date-time) | null, optional)
- `accessHoldReason` (string | null, optional): One of: `"rejected"`, `"revoked"`.
- `submittedByUserId` (string | null, optional)
- `submittedByEmail` (string (email) | null, optional)
- `submittedByApiKeyId` (string | null, optional)
- `submittedAt` (string (date-time) | null, optional)
- `reviewerUserId` (string | null, optional)
- `reviewerEmail` (string (email) | null, optional)
- `reviewedAt` (string (date-time) | null, optional)
- `rejectionReason` (string | null, optional)
- `slackNotificationStatus` (string, optional): One of: `"not_queued"`, `"queued"`, `"enqueue_failed"`.
- `slackNotificationJobId` (string | null, optional)
- `slackNotificationError` (string | null, optional)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organizationId": "string",
  "status": "draft",
  "businessProfile": {
    "legalName": "string",
    "displayName": "string",
    "entityType": "string",
    "country": "string",
    "registrationId": "string",
    "website": "string",
    "address": {},
    "useCase": "string",
    "expectedUsage": "string"
  },
  "authorizedRepresentative": {
    "name": "string",
    "title": "string",
    "email": "string",
    "phone": "+12015551234"
  },
  "declaration": {
    "businessName": "string",
    "useCase": "string"
  },
  "attestor": {
    "kind": "user",
    "userId": "string",
    "name": "string",
    "email": "string",
    "organizationRole": "string"
  },
  "attestationAccepted": true,
  "attestationVersion": "string",
  "attestationText": "string",
  "termsVersion": "string",
  "attestedAt": "2026-01-01T00:00:00Z",
  "accessHoldAt": "2026-01-01T00:00:00Z",
  "accessHoldReason": "rejected",
  "submittedByUserId": "string",
  "submittedByEmail": "string",
  "submittedByApiKeyId": "string",
  "submittedAt": "2026-01-01T00:00:00Z",
  "reviewerUserId": "string",
  "reviewerEmail": "string",
  "reviewedAt": "2026-01-01T00:00:00Z",
  "rejectionReason": "string",
  "slackNotificationStatus": "not_queued",
  "slackNotificationJobId": "string",
  "slackNotificationError": "string",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 409: The displayed attestation version is stale, or the declaration is already approved.

Content type: `application/json`

- `error` (string, optional)
- `code` (string, optional)
- `requiredAttestation` (object, optional)
  - `version` (string, required)
  - `text` (string, required)
  - `termsVersion` (string, required)
  - `termsUrl` (string (uri), required)

Example:

```json
{
  "error": "string",
  "code": "string",
  "requiredAttestation": {
    "version": "string",
    "text": "string",
    "termsVersion": "string",
    "termsUrl": "string"
  }
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/phone-numbers/kyb/submit' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"declaration":{"businessName":"string","useCase":"string"},"attestationAccepted":true,"attestationVersion":"string"}'
```

## GET /v1/phone-numbers/{id}

Get a phone number

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Phone number

Content type: `application/json`

- `id` (string, required)
- `organizationId` (string, required)
- `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `source` (string, required): One of: `"managed"`, `"sip_trunk"`.
- `providerResourceId` (string | null, optional)
- `telnyxPhoneNumberId` (string | null, optional): Deprecated.
- `sipTrunkId` (string | null, optional): Deprecated.
- `sipConnectionInstallationId` (string | null, optional)
- `sipProviderName` (string | null, optional)
- `direction` (string, required): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object | null, optional)
- `agentId` (string | null, optional)
- `routeToBrokerId` (string | null, optional): Org-defined broker id whose softphone this number rings instead of an agent. Mutually exclusive with `agentId` — setting one clears the other. Requires human calling to be enabled for the workspace.
- `label` (string | null, optional)
- `sms10dlcProfileId` (string | null, optional)
- `smsCampaignId` (string | null, optional)
- `smsAssignmentStatus` (string | null, optional)
- `smsAssignmentUpdatedAt` (string (date-time) | null, optional)
- `telnyxMessagingProfileId` (string | null, optional)
- `smsMessagingProfileStatus` (string, optional): One of: `"pending"`, `"ready"`, `"failed"`.
- `smsMessagingProfileUpdatedAt` (string (date-time) | null, optional)
- `smsMessagingProfileError` (string | null, optional)
- `smsAutomationEnabled` (boolean, optional)
- `setupStatus` (object, required)
  - `status` (string, required): One of: `"ready"`, `"action_required"`, `"suspended"`.
  - `inboundReady` (boolean, required)
  - `outboundReady` (boolean, required)
  - `agentReady` (boolean, required)
  - `forwardingRequired` (boolean, required)
  - `sipConnectionReady` (boolean, required)
  - `issues` (array of string, required)
- `nextChargeAt` (string (date-time), optional)
- `lastChargedAt` (string (date-time) | null, optional)
- `suspendedAt` (string (date-time) | null, optional): Effective suspension timestamp retained for older clients. Compliance takes precedence when both compliance and billing holds are active.
- `billingSuspendedAt` (string (date-time) | null, optional)
- `complianceSuspendedAt` (string (date-time) | null, optional)
- `suspensionReason` (string | null, optional): One of: `"billing"`, `"compliance"`.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organizationId": "string",
  "e164": "+12015551234",
  "source": "managed",
  "providerResourceId": "string",
  "telnyxPhoneNumberId": "string",
  "sipTrunkId": "string",
  "sipConnectionInstallationId": "string",
  "sipProviderName": "string",
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "agentId": "string",
  "routeToBrokerId": "string",
  "label": "string",
  "sms10dlcProfileId": "string",
  "smsCampaignId": "string",
  "smsAssignmentStatus": "string",
  "smsAssignmentUpdatedAt": "2026-01-01T00:00:00Z",
  "telnyxMessagingProfileId": "string",
  "smsMessagingProfileStatus": "pending",
  "smsMessagingProfileUpdatedAt": "2026-01-01T00:00:00Z",
  "smsMessagingProfileError": "string",
  "smsAutomationEnabled": true,
  "setupStatus": {
    "status": "ready",
    "inboundReady": true,
    "outboundReady": true,
    "agentReady": true,
    "forwardingRequired": true,
    "sipConnectionReady": true,
    "issues": [
      "string"
    ]
  },
  "nextChargeAt": "2026-01-01T00:00:00Z",
  "lastChargedAt": "2026-01-01T00:00:00Z",
  "suspendedAt": "2026-01-01T00:00:00Z",
  "billingSuspendedAt": "2026-01-01T00:00:00Z",
  "complianceSuspendedAt": "2026-01-01T00:00:00Z",
  "suspensionReason": "billing",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/phone-numbers/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## PATCH /v1/phone-numbers/{id}

Update a phone number

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Request body

Required.

Content types: `application/json`

- `direction` (string, optional): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object | null, optional)
- `label` (string | null, optional)
- `agentId` (string | null, optional)
- `routeToBrokerId` (string | null, optional): Org-defined broker id whose softphone this number rings instead of an agent. Mutually exclusive with `agentId` — setting one clears the other. Requires human calling to be enabled for the workspace.
- `smsAutomationEnabled` (boolean, optional): Owner/admin-only opt-in for inbound SMS agent replies on this number.

Example body:

```json
{
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "label": "string",
  "agentId": "string",
  "routeToBrokerId": "string",
  "smsAutomationEnabled": true
}
```

### Responses

#### 200: Phone number

Content type: `application/json`

- `id` (string, required)
- `organizationId` (string, required)
- `e164` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `source` (string, required): One of: `"managed"`, `"sip_trunk"`.
- `providerResourceId` (string | null, optional)
- `telnyxPhoneNumberId` (string | null, optional): Deprecated.
- `sipTrunkId` (string | null, optional): Deprecated.
- `sipConnectionInstallationId` (string | null, optional)
- `sipProviderName` (string | null, optional)
- `direction` (string, required): One of: `"inbound"`, `"outbound"`, `"both"`.
- `dispatchMetadataTemplate` (object | null, optional)
- `agentId` (string | null, optional)
- `routeToBrokerId` (string | null, optional): Org-defined broker id whose softphone this number rings instead of an agent. Mutually exclusive with `agentId` — setting one clears the other. Requires human calling to be enabled for the workspace.
- `label` (string | null, optional)
- `sms10dlcProfileId` (string | null, optional)
- `smsCampaignId` (string | null, optional)
- `smsAssignmentStatus` (string | null, optional)
- `smsAssignmentUpdatedAt` (string (date-time) | null, optional)
- `telnyxMessagingProfileId` (string | null, optional)
- `smsMessagingProfileStatus` (string, optional): One of: `"pending"`, `"ready"`, `"failed"`.
- `smsMessagingProfileUpdatedAt` (string (date-time) | null, optional)
- `smsMessagingProfileError` (string | null, optional)
- `smsAutomationEnabled` (boolean, optional)
- `setupStatus` (object, required)
  - `status` (string, required): One of: `"ready"`, `"action_required"`, `"suspended"`.
  - `inboundReady` (boolean, required)
  - `outboundReady` (boolean, required)
  - `agentReady` (boolean, required)
  - `forwardingRequired` (boolean, required)
  - `sipConnectionReady` (boolean, required)
  - `issues` (array of string, required)
- `nextChargeAt` (string (date-time), optional)
- `lastChargedAt` (string (date-time) | null, optional)
- `suspendedAt` (string (date-time) | null, optional): Effective suspension timestamp retained for older clients. Compliance takes precedence when both compliance and billing holds are active.
- `billingSuspendedAt` (string (date-time) | null, optional)
- `complianceSuspendedAt` (string (date-time) | null, optional)
- `suspensionReason` (string | null, optional): One of: `"billing"`, `"compliance"`.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "organizationId": "string",
  "e164": "+12015551234",
  "source": "managed",
  "providerResourceId": "string",
  "telnyxPhoneNumberId": "string",
  "sipTrunkId": "string",
  "sipConnectionInstallationId": "string",
  "sipProviderName": "string",
  "direction": "inbound",
  "dispatchMetadataTemplate": {},
  "agentId": "string",
  "routeToBrokerId": "string",
  "label": "string",
  "sms10dlcProfileId": "string",
  "smsCampaignId": "string",
  "smsAssignmentStatus": "string",
  "smsAssignmentUpdatedAt": "2026-01-01T00:00:00Z",
  "telnyxMessagingProfileId": "string",
  "smsMessagingProfileStatus": "pending",
  "smsMessagingProfileUpdatedAt": "2026-01-01T00:00:00Z",
  "smsMessagingProfileError": "string",
  "smsAutomationEnabled": true,
  "setupStatus": {
    "status": "ready",
    "inboundReady": true,
    "outboundReady": true,
    "agentReady": true,
    "forwardingRequired": true,
    "sipConnectionReady": true,
    "issues": [
      "string"
    ]
  },
  "nextChargeAt": "2026-01-01T00:00:00Z",
  "lastChargedAt": "2026-01-01T00:00:00Z",
  "suspendedAt": "2026-01-01T00:00:00Z",
  "billingSuspendedAt": "2026-01-01T00:00:00Z",
  "complianceSuspendedAt": "2026-01-01T00:00:00Z",
  "suspensionReason": "billing",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X PATCH 'https://api.speko.dev/v1/phone-numbers/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"direction":"inbound","dispatchMetadataTemplate":{},"label":"string","agentId":"string","routeToBrokerId":"string","smsAutomationEnabled":true}'
```

## DELETE /v1/phone-numbers/{id}

Release a phone number

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string, in path, required): Resource id.

### Responses

#### 200: Release result

Content type: `application/json`

- `released` (boolean, required)

Example:

```json
{
  "released": true
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X DELETE 'https://api.speko.dev/v1/phone-numbers/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Create phone session (/api-reference/sessions-phone)

POST /v1/sessions/phone — place an outbound PSTN call backed by a Speko voice session.



## POST /v1/sessions/phone

Place an outbound phone call

Creates a voice session, dispatches the configured agent worker, and dials the destination over LiveKit SIP. Supply either `agentId` or `intent`.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `to` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `from` (string, optional): Pattern: `^\+[1-9]\d{6,14}$`.
- `agentId` (string, optional): Persisted agent to run. Required unless `intent` is supplied.
- `intent` (object, optional)
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`. Pattern: `^[a-z]{2}(-[A-Z]{2})?$`.
  - `region` (string, optional): Region whose streaming-latency measurements should be used. `global` falls through to batch-mode rows when no per-region data matches. One of: `"global"`, `"us-east4"`, `"europe-west3"`, `"asia-southeast1"`. Default: `"global"`.
  - `optimizeFor` (string, optional): One of: `"balanced"`, `"accuracy"`, `"latency"`, `"cost"`. Default: `"balanced"`.
- `constraints` (object, optional)
  - `allowedProviders` (object, optional): Restrict candidate pool per modality. Router still ranks by score. Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
    - `stt` (array of string, optional)
      - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
    - `llm` (array of string, optional)
      - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
    - `tts` (array of string, optional)
      - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
    - `s2s` (array of string, optional)
      - Allowed S2S provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI realtime model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-realtime-2.1"` — only that model). Both forms can be mixed in the same array.
- `voice` (string, optional)
- `systemPrompt` (string, optional)
- `firstMessage` (string, optional)
- `llm` (object, optional)
- `ttsOptions` (object, optional)
- `sttOptions` (object, optional)
- `telephony` (object, optional)
  - `region` (string, optional): Optional SIP routing region hint forwarded as `X-Speko-Region`.
  - `amd` (object, optional)
    - `mode` (string, optional): One of: `"agent"`, `"carrier"`, `"disabled"`. Default: `"agent"`.
    - `timeoutSeconds` (integer, optional): Min: 1. Max: 60.
- `turnHandling` (object, optional): Per-call turn-taking posture for an outbound phone call — e.g. dialling a number known to answer with a menu. Replaces the agent's stored `turnHandling` wholesale for this call.
  - `profile` (string, optional): Turn-taking posture preset. `ivr` is for calls INTO phone menus: it unlocks the `send_dtmf` keypad tool plus the menu-loop and dead-air watch — armed by the answering-machine verdict on outbound calls, and from call start elsewhere. Turn-taking itself stays conversational under both presets. The legacy value `ivr_patient` is still accepted and normalized to `ivr`. One of: `"conversational"`, `"ivr"`. Default: `"conversational"`.
  - `endpointing` (object, optional): How long a caller has to stay silent before their turn is committed.
    - `minDelay` (integer, optional): Milliseconds. Min: 0. Max: 5000.
    - `maxDelay` (integer, optional): Milliseconds. Min: 0. Max: 10000.
  - `interruption` (object, optional)
    - `mode` (string, optional): `vad` barges in on any overlapping speech, honoring `minDuration`/`minWords`. `adaptive` classifies a real interruption from a backchannel ("mhm", "right") first and ignores both thresholds. Unset uses the platform default. One of: `"adaptive"`, `"vad"`.
    - `minDuration` (integer, optional): Milliseconds of caller speech required to interrupt. `vad` mode only. Min: 0. Max: 5000.
    - `minWords` (integer, optional): Words required to interrupt. `vad` mode only. Min: 0. Max: 10.
  - `turnDetection` (boolean, optional): End-of-turn detection. Unset uses the semantic turn model; `false` falls back to plain voice-activity detection.
  - `contextThreshold` (boolean, optional): Context-conditioned turn-taking: the commit threshold adapts to the shape of what the agent just asked. Unset uses the platform default.
  - `amdPrompt` (string, optional): Replaces the built-in prompt the answering-machine classifier sees when deciding whether a person, a phone menu, or voicemail answered. Write it as classification instructions with examples; the callee's greeting transcript is appended as the input. The category vocabulary is always supplied for you, so a prompt that never names the categories still works. Outbound calls only — inbound never runs the detector, and this is accepted and inert there. It steers only the judgement on what was said: a pickup with no speech at all is decided on timing before the prompt is read.
  - `greetFirst` (boolean, optional): Play the opening line immediately on answer while answering-machine detection classifies in the background. `false` holds the OPENING LINE ONLY — never later replies — until the verdict lands, bounded at roughly 8 seconds, so the agent never greets a machine. Default: `true`.
  - `waitForCallee` (boolean, optional): Outbound opening etiquette: after pickup, hold the opening line briefly so the callee's own hello ("Good morning, Riverside Dental…") finishes first. `false` greets the instant they answer. Default: `true`.
  - `onMachine` (string, optional): Per-call override of the agent's `onMachine`. What happens when answering-machine detection says a VOICEMAIL (or an "unavailable" recording) answered an outbound call. `hangup` ends the call the moment the verdict lands. `leave_message` waits for the greeting to finish, speaks `voicemailMessage` once in the agent's voice, then hangs up. `agent_decides` (default) hands the verdict to the model as a system note and lets the prompt's own voicemail rules act. Never applies to phone menus or call-screening services, which lead to a person. Calls ended this way close with `endReason: voicemail_reached` and report outcome `voicemail`. One of: `"hangup"`, `"leave_message"`, `"agent_decides"`. Default: `"agent_decides"`.
  - `voicemailMessage` (string, optional): Spoken once into the mailbox under `onMachine: leave_message`, after the greeting ends. Plain text, rendered by the agent's TTS voice.
- `webhookTags` (object, optional): Case-sensitive routing tags for workspace webhook endpoints. Requires agentId.
- `metadata` (object, optional)

Example body:

```json
{
  "to": "+12015551234",
  "from": "+12015551234",
  "agentId": "string",
  "intent": {
    "language": "en-US",
    "region": "global",
    "optimizeFor": "balanced"
  },
  "constraints": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai"
      ]
    }
  },
  "voice": "string",
  "systemPrompt": "string",
  "firstMessage": "string",
  "llm": {},
  "ttsOptions": {},
  "sttOptions": {},
  "telephony": {
    "region": "string",
    "amd": {
      "mode": "agent",
      "timeoutSeconds": 0
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "amdPrompt": "string",
    "greetFirst": true,
    "waitForCallee": true,
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  },
  "webhookTags": {},
  "metadata": {}
}
```

### Responses

#### 200: Call dialing

Content type: `application/json`

- `sessionId` (string, required)
- `callControlId` (string, required): LiveKit SIP participant identity for the outbound leg.
- `roomName` (string, required)
- `status` (string, required): One of: `"dialing"`, `"dialing-stub"`.
- `to` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.
- `from` (string, required): Pattern: `^\+[1-9]\d{6,14}$`.

Example:

```json
{
  "sessionId": "string",
  "callControlId": "string",
  "roomName": "string",
  "status": "dialing",
  "to": "+12015551234",
  "from": "+12015551234"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No agent with this id exists in the authenticated organization.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "not found",
  "code": "NOT_FOUND"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/sessions/phone' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"to":"+12015551234","from":"+12015551234","agentId":"string","intent":{"language":"en-US","region":"global","optimizeFor":"balanced"},"constraints":{"allowedProviders":{"stt":["deepgram"],"llm":["openai"],"tts":["elevenlabs"],"s2s":["openai"]}},"voice":"string","systemPrompt":"string","firstMessage":"string","llm":{},"ttsOptions":{},"sttOptions":{},"telephony":{"region":"string","amd":{"mode":"agent","timeoutSeconds":0}},"turnHandling":{"profile":"conversational","endpointing":{"minDelay":0,"maxDelay":0},"interruption":{"mode":"adaptive","minDuration":0,"minWords":0},"turnDetection":true,"contextThreshold":true,"amdPrompt":"string","greetFirst":true,"waitForCallee":true,"onMachine":"agent_decides","voicemailMessage":"string"},"webhookTags":{},"metadata":{}}'
```


# Sessions (/api-reference/sessions)

Creates either a provider-direct S2S session with a scoped OpenAI, Gemini Live, or xAI credential, or a cascade session with browser-safe LiveKit transport credentials.



## POST /v1/sessions

Create a real-time voice session

Creates either a provider-direct S2S session or a LiveKit-backed cascade session. S2S returns a scoped, short-lived provider credential so the client connects directly to OpenAI Realtime, Gemini Live, or xAI Grok Voice; Speko remains in the control and billing path but never proxies media. Cascade returns browser-safe LiveKit credentials and dispatches an STT → LLM → TTS worker.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `Idempotency-Key` (string, in header, optional): Required when the session resolves to `s2s`. Reuse the same value after an ambiguous timeout to recover the same reservation.

### Request body

Required.

Content types: `application/json`

- Set `mode` explicitly when possible. If omitted, the server uses the persisted agent's S2S run mode when applicable and otherwise defaults to cascade.

Example body:

```json
{
  "mode": "cascade",
  "agentId": "string",
  "intent": {
    "language": "en-US",
    "region": "global",
    "optimizeFor": "balanced"
  },
  "constraints": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai"
      ]
    }
  },
  "voice": "string",
  "systemPrompt": "string",
  "llm": {
    "temperature": 0,
    "maxTokens": 0
  },
  "ttsOptions": {
    "sampleRate": 0,
    "speed": 0
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "onMachine": "agent_decides",
    "voicemailMessage": "string"
  },
  "webhookTags": {},
  "metadata": {},
  "ttlSeconds": 900,
  "maxDurationSeconds": 3600,
  "identity": "string"
}
```

### Responses

#### 201: Session created

Content type: `application/json`

Example:

```json
{
  "mode": "cascade",
  "sessionId": "string",
  "transportToken": "string",
  "transportUrl": "string",
  "conversationToken": "string",
  "livekitUrl": "string",
  "roomName": "speko_...",
  "identity": "string",
  "expiresAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 402: Insufficient credit balance for the requested S2S entitlement.

#### 403: Provider-direct S2S is not enabled for the organization.

#### 409: The idempotency key is already in use by a different S2S bootstrap.

#### 422: The requested S2S provider, model, voice, sample rate, or route is unavailable.

#### 429: Realtime session capacity is currently exhausted.

#### 500: Token mint failed, agent dispatch failed, or DB insert failed.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Failed to dispatch voice agent",
  "code": "SESSION_CREATE_FAILED"
}
```

#### 502: The provider-direct control plane returned an invalid session plan.

#### 503: Provider-direct S2S bootstrap is temporarily unavailable.

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/sessions' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"cascade","agentId":"string","intent":{"language":"en-US","region":"global","optimizeFor":"balanced"},"constraints":{"allowedProviders":{"stt":["deepgram"],"llm":["openai"],"tts":["elevenlabs"],"s2s":["openai"]}},"voice":"string","systemPrompt":"string","llm":{"temperature":0,"maxTokens":0},"ttsOptions":{"sampleRate":0,"speed":0},"turnHandling":{"profile":"conversational","endpointing":{"minDelay":0,"maxDelay":0},"interruption":{"mode":"adaptive","minDuration":0,"minWords":0},"turnDetection":true,"contextThreshold":true,"dtmfToolDescription":"string","amdPrompt":"string","onMachine":"agent_decides","voicemailMessage":"string"},"webhookTags":{},"metadata":{},"ttlSeconds":900,"maxDurationSeconds":3600,"identity":"string"}'
```


# Synthesize (/api-reference/synthesize)

Routes the request to the best TTS provider for your intent, with automatic failover. Returns binary audio. The `Content-Type` header (mirrored in `X-Speko-Audio-Format`) tells you the format.



## POST /v1/synthesize

Synthesize speech (text to speech)

Routes the request to the best TTS provider for your intent, with automatic failover before the first audio chunk. Returns chunked binary audio. The `Content-Type` header (mirrored in `X-Speko-Audio-Format`) tells you the format.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `text` (string, required)
- `intent` (object, required)
  - `language` (string, required): BCP-47 language tag, e.g. `en`, `en-US`, `es-MX`. Pattern: `^[a-z]{2}(-[A-Z]{2})?$`.
  - `region` (string, optional): Region whose streaming-latency measurements should be used. `global` falls through to batch-mode rows when no per-region data matches. One of: `"global"`, `"us-east4"`, `"europe-west3"`, `"asia-southeast1"`. Default: `"global"`.
  - `optimizeFor` (string, optional): One of: `"balanced"`, `"accuracy"`, `"latency"`, `"cost"`. Default: `"balanced"`.
- `voice` (string, optional): Provider-specific voice id. Speko falls back to a sane default per provider when omitted.
- `model` (string, optional): Optional upstream model name (e.g. `eleven_multilingual_v2`, `sonic-2`, `gpt-4o-mini-tts`, `qwen3-tts-flash`). When set, overrides the selector's chosen model on the primary candidate only — failover candidates still use the selector's model so a model intended for provider A is not sent to provider B.
- `speed` (number, optional): Min: 0.5. Max: 2.
- `workload` (string, optional): Applies per-provider defaults from the param registry (e.g. `narration` sets ElevenLabs `voice_settings` and prefers a 24 kHz ladder when `sampleRate` is unset). Explicit fields override defaults. Applied param names are reported in the `X-Speko-Applied-Params` response header. One of: `"conversation"`, `"transcription"`, `"narration"`.
- `providerOptions` (object, optional): Per-provider TTS params keyed by provider id, validated against the registry (e.g. `{"elevenlabs":{"voice_settings":{"stability":0.6}}}`). A provider's options apply only when that provider serves the request and never cross providers on failover. Setting a provider spelling of `speed` alongside the top-level `speed` is rejected as `canonical_collision`.
- `constraints` (object, optional)
  - `allowedProviders` (object, optional): Restrict candidate pool per modality. Router still ranks by score. Each entry is either `"<vendor>"` (vendor wildcard — allow any model from that vendor) or `"<vendor>:<model>"` (allow only that specific model). Failover stays active across all entries in the layer.
    - `stt` (array of string, optional)
      - Allowed STT provider entry. Either a vendor id (e.g. `"deepgram"` — any Deepgram model) or `"<vendor>:<model>"` (e.g. `"deepgram:nova-3"` — only Nova-3, no fallback to other Deepgram models within the vendor). Both forms can be mixed in the same array.
    - `llm` (array of string, optional)
      - Allowed LLM provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-5"` — only that model). Both forms can be mixed in the same array.
    - `tts` (array of string, optional)
      - Allowed TTS provider entry. Either a vendor id (e.g. `"elevenlabs"` — any ElevenLabs model) or `"<vendor>:<model>"` (e.g. `"elevenlabs:eleven_flash_v2_5"` — only that model). Both forms can be mixed in the same array.
    - `s2s` (array of string, optional)
      - Allowed S2S provider entry. Either a vendor id (e.g. `"openai"` — any OpenAI realtime model) or `"<vendor>:<model>"` (e.g. `"openai:gpt-realtime-2.1"` — only that model). Both forms can be mixed in the same array.

Example body:

```json
{
  "text": "string",
  "intent": {
    "language": "en-US",
    "region": "global",
    "optimizeFor": "balanced"
  },
  "voice": "string",
  "model": "string",
  "speed": 0,
  "workload": "conversation",
  "providerOptions": {},
  "constraints": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai"
      ]
    }
  }
}
```

### Responses

#### 200: Chunked audio bytes

Content type: `application/octet-stream`

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 500: No TTS provider available for the intent, no default voice for chosen provider, or every candidate failed.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "All providers failed",
  "code": "SYNTHESIZE_FAILED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/synthesize' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text":"string","intent":{"language":"en-US","region":"global","optimizeFor":"balanced"},"voice":"string","model":"string","speed":0,"workload":"conversation","providerOptions":{},"constraints":{"allowedProviders":{"stt":["deepgram"],"llm":["openai"],"tts":["elevenlabs"],"s2s":["openai"]}}}'
```


# Transcribe (/api-reference/transcribe)

Routes the request to the best STT provider for your `(language, region, optimizeFor)` intent, with automatic failover to runner-up providers. Body is binary audio. Routing intent goes in the `x-speko-intent` header (JSON).



## POST /v1/transcribe

Transcribe audio (speech to text)

Routes the request to the best STT provider for your `(language, region, optimizeFor)` intent, with automatic failover to runner-up providers before the first event is emitted. Body is binary audio. Routing intent goes in the `x-speko-intent` header (JSON). The response is a Server-Sent Events stream: `meta`, `transcript`, `done`, and `error`.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `x-speko-intent` (string, in header, required): JSON-encoded `RoutingIntent`. Example: `{"language":"en-US","region":"global"}`.
- `x-speko-constraints` (string, in header, optional): Optional JSON-encoded `PipelineConstraints`. Each `allowedProviders` entry is either `"<vendor>"` (any model from that vendor) or `"<vendor>:<model>"` (a specific model). Example: `{"allowedProviders":{"stt":["deepgram:nova-3"]}}`.
- `x-speko-stt-options` (string, in header, optional): Optional JSON-encoded STT options, max 4 KB. Fields: `keywords` (string[], <=200, vocabulary bias), `language` (BCP-47 or `auto`, provider-level override that does not change routing), `workload` (`conversation` | `transcription` | `narration`, applies registry defaults per provider), `diarization` (batch-only boolean, demote-class: incapable providers are excluded from failover; 422 `no_capable_provider` when none remain), `speakersExpected` (integer hint), `smartFormat` (boolean), `fillerWords` (boolean), `profanityFilter` (boolean), `wordTimestamps` (batch-only boolean, demote-class; the `done` frame carries `words: [{text, start, end}]` in seconds — served by `gemini-3.5-transcribe`, which must be pinned through `X-Speko-Constraints` or the request answers 422 `no_capable_provider`, and which cannot combine it with `keywords`), `providerOptions` (per-provider params validated against the registry, e.g. `{"deepgram":{"dictation":true}}`; apply only when that provider serves the request and never cross providers on failover). Example: `{"workload":"transcription","diarization":true}`.
- `Content-Type` (string, in header, optional): Audio MIME type, e.g. `audio/wav`, `audio/mpeg`, `audio/pcm;rate=16000`.

### Request body

Required. Binary audio. WAV, MP3, or raw PCM accepted.

Content types: `application/octet-stream`, `audio/wav`, `audio/mpeg`

### Responses

#### 200: Transcript event stream

Content type: `text/event-stream`

SSE events: `meta` with provider/model, zero or more `transcript` events, final `done` containing a `TranscribeResponse`, or `error` after streaming has started.

#### 400: Empty body, missing/invalid `x-speko-intent` header, or malformed `x-speko-constraints`.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Audio body is empty.",
  "code": "INVALID_AUDIO"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 500: No STT provider available for the intent, or every candidate failed.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "All providers failed",
  "code": "TRANSCRIBE_FAILED"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/transcribe' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'x-speko-intent: {"language":"en-US","region":"global"}' \
  -H 'Content-Type: audio/wav' \
  --data-binary '@audio.wav'
```


# TTS Quality Vocabulary (/api-reference/tts-meta)

Every value the quality, pace, capacity and use-case filters accept, with what each label asserts.



## GET /v1/tts/meta

The quality vocabulary

What every quality label asserts, plus the pace buckets, capacity rungs and use-case bundles. Every value the filters accept is listed here.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: Vocabulary

Content type: `application/json`

- `quality` (array of object, optional)
  - `value` (string, optional)
  - `label` (string, optional)
  - `means` (string, optional)
- `pace` (array of object, optional)
  - `value` (string, optional)
  - `label` (string, optional)
  - `range_wpm` (array of number, optional)
- `chars_per_call` (array of object, optional)
  - `value` (integer, optional)
  - `label` (string, optional)
- `use_cases` (array of object, optional)
  - `value` (string, optional)
  - `label` (string, optional)
  - `hint` (string, optional)
  - `requires` (array of string, optional)
  - `min_chars_per_call` (integer, optional)
- `notes` (array of string, optional)

Example:

```json
{
  "quality": [
    {
      "value": "string",
      "label": "string",
      "means": "string"
    }
  ],
  "pace": [
    {
      "value": "string",
      "label": "string",
      "range_wpm": [
        0
      ]
    }
  ],
  "chars_per_call": [
    {
      "value": 0,
      "label": "string"
    }
  ],
  "use_cases": [
    {
      "value": "string",
      "label": "string",
      "hint": "string",
      "requires": [
        "string"
      ],
      "min_chars_per_call": 0
    }
  ],
  "notes": [
    "string"
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/tts/meta' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# TTS Models (/api-reference/tts-models)

Compare the TTS models your organization can route on measured naturalness, robustness, cost and first-audio latency, with the regional and per-language readings alongside.



## GET /v1/tts/models

Compare TTS models

Every TTS model this organization can route, with all measured benchmarks for one language. Scoped to what you can call: a vendor with no platform key and no BYOK credential is absent unless you pass `include_unroutable=true`.

There is no composite score. The TTS board publishes no overall rank column, so results come back measured-first and then ordered by the single axis you name. A model with no value on that axis sorts last in either direction, so an unmeasured model cannot win a cheapest-or-fastest sort by having no number.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `language` (string, in query, optional): Which language cell to report. Robustness is measured for English only. Default: `"en"`.
- `use_case` (string, in query, optional): Narrow to models with at least one voice meeting this use case. Rows included only by `include_unroutable=true` are not narrowed, since no voice evidence exists for a model this organization cannot route. One of: `"longform"`, `"phone"`.
- `sort` (string, in query, optional): One of: `"natural"`, `"latency"`, `"cost"`, `"robustness"`. Default: `"natural"`.
- `order` (string, in query, optional): Defaults to ascending for `latency` and `cost`, descending for the other axes. One of: `"asc"`, `"desc"`.
- `include_unroutable` (string, in query, optional): One of: `"true"`, `"false"`, `"1"`, `"0"`. Default: `"false"`.

### Responses

#### 200: Model comparison

Content type: `application/json`

- `object` (string, optional)
- `language` (string, optional)
- `sort` (string, optional)
- `order` (string, optional)
- `data` (array of object, optional)
  - `id` (string, required)
  - `provider` (string, required)
  - `model` (string, required)
  - `routable` (boolean, required)
  - `routable_via` (string | null, optional): One of: `"platform_key"`, `"byok"`, `null`.
  - `benchmark` (object, required)
    - `language` (string, optional)
    - `board` (string, optional)
    - `naturalness` (object, optional): One measured axis, with its unit and direction stated so a caller never has to infer them.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `robustness` (object, optional): One measured axis, with its unit and direction stated so a caller never has to infer them.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `panel_mos` (object, optional): A 0-5 direct-rating scale. `naturalness` uses a different scale.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `panel_named_pct` (object, optional): One measured axis, with its unit and direction stated so a caller never has to infer them.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `latency_ms` (number | null, optional): The ranked reading: first-audio p50. The only latency to sort on. Null where the model has no reading.
    - `latency_evidence` (object, optional): The region and sample size behind `latency_ms`. Present whenever `latency_ms` is non-null.
      - `board` (string, optional)
      - `region` (string, optional)
      - `n` (integer, optional)
      - `p90_ms` (number, optional)
    - `latency` (object, optional): TTS latency detail, published beside `latency_ms` and `latency_evidence` rather than in place of them. The blocks are different quantities, so do not compare them with each other or with `latency_ms`.
      - `vendor_direct` (array of object, optional): The reading in each region it covers. The row whose `location` equals `latency_evidence.region` is the same number as `latency_ms`; the others are the regional siblings the ranked field does not carry.
        - `region` (string, optional)
        - `location` (string, optional)
        - `p50_ms` (number, optional)
        - `p90_ms` (number | null, optional)
      - `per_language` (array of object, optional): Per-language time to first audio, p50 and p90. Measured differently from `latency_ms`, so these rows compare with each other and never against it. `n`, `sweeps` and `wide_tail` describe each row on its own terms.
        - `language` (string, optional)
        - `p50` (number, optional)
        - `p90` (number, optional)
        - `n` (integer, optional)
        - `sweeps` (integer, optional)
        - `wide_tail` (boolean, optional): p90/p50 above 1.7, a tail this row’s sample size cannot resolve. Do not read movement between sweeps as change.
        - `voice` (string, optional)
    - `cost` (object, optional): Always present. On a model with no board row every number is null, which is a different answer from the field being absent.
      - `per_1m_chars_usd` (number | null, optional)
      - `per_min_usd` (number | null, optional): Derived, not measured: `per_1m_chars_usd x 900 / 1e6`.
      - `higher_is_better` (boolean, optional)
  - `languages` (object, optional)
    - `measured` (array of string, optional): Language tags this model is measured on.
    - `vendor_claimed` (array of string, optional): The vendor lists the language but we have not probed it.
    - `count` (integer, optional)
  - `voices` (object, optional): How many voices can be used with this model, how many of those carry a measurement, and how the pairing was established. Pass `?model=` to `/v1/tts/voices` to list them.
    - `total` (integer, optional)
    - `measured` (integer, optional): How many of those voices carry a measurement.
    - `compatibility` (string, optional): One of: `"verified"`, `"vendor_roster"`, `"restricted"`.
- `meta` (object, optional)
  - `benchmark` (object, optional)
    - `schema` (integer, optional)
    - `routing_policy_version` (string, optional)
  - `quality_overlay` (object, optional)
    - `generated_at` (string, optional)
    - `run_id` (string, optional)
  - `org_routable_vendors` (array of string, optional)
  - `coverage` (object, optional)
    - `models_routable` (integer, optional)
    - `models_measured` (integer, optional)
    - `voices_routable` (integer, optional)
    - `voices_measured` (integer, optional)
  - `notes` (array of string, optional): The caveats that stop a number being read as something it is not.

Example:

```json
{
  "object": "string",
  "language": "string",
  "sort": "string",
  "order": "string",
  "data": [
    {
      "id": "cartesia:sonic-3.5",
      "provider": "string",
      "model": "string",
      "routable": true,
      "routable_via": "platform_key",
      "benchmark": {
        "language": "string",
        "board": "string",
        "naturalness": {
          "value": 0,
          "unit": "string",
          "higher_is_better": true,
          "board": "string",
          "ci": [
            null
          ],
          "n": 0,
          "basis": "string",
          "unjudgeable": 0,
          "field_mean": 0,
          "comparable_across_languages": true,
          "estimated": true
        },
        "robustness": {
          "value": 0,
          "unit": "string",
          "higher_is_better": true,
          "board": "string",
          "ci": [
            null
          ],
          "n": 0,
          "basis": "string",
          "unjudgeable": 0,
          "field_mean": 0,
          "comparable_across_languages": true,
          "estimated": true
        },
        "panel_mos": {
          "value": 0,
          "unit": "string",
          "higher_is_better": true,
          "board": "string",
          "ci": [
            null
          ],
          "n": 0,
          "basis": "string",
          "unjudgeable": 0,
          "field_mean": 0,
          "comparable_across_languages": true,
          "estimated": true
        },
        "panel_named_pct": {
          "value": 0,
          "unit": "string",
          "higher_is_better": true,
          "board": "string",
          "ci": [
            null
          ],
          "n": 0,
          "basis": "string",
          "unjudgeable": 0,
          "field_mean": 0,
          "comparable_across_languages": true,
          "estimated": true
        },
        "latency_ms": 0,
        "latency_evidence": {
          "board": "string",
          "region": "string",
          "n": 0,
          "p90_ms": 0
        },
        "latency": {
          "vendor_direct": [
            null
          ],
          "per_language": [
            null
          ]
        },
        "cost": {
          "per_1m_chars_usd": 0,
          "per_min_usd": 0,
          "higher_is_better": true
        }
      },
      "languages": {
        "measured": [
          "string"
        ],
        "vendor_claimed": [
          "string"
        ],
        "count": 0
      },
      "voices": {
        "total": 0,
        "measured": 0,
        "compatibility": "verified"
      }
    }
  ],
  "meta": {
    "benchmark": {
      "schema": 0,
      "routing_policy_version": "string"
    },
    "quality_overlay": {
      "generated_at": "string",
      "run_id": "string"
    },
    "org_routable_vendors": [
      "string"
    ],
    "coverage": {
      "models_routable": 0,
      "models_measured": 0,
      "voices_routable": 0,
      "voices_measured": 0
    },
    "notes": [
      "string"
    ]
  }
}
```

#### 400: Validation error

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/tts/models' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# TTS Voice Detail (/api-reference/tts-voice-detail)

One voice, its measured quality labels, and the benchmarks of the model it runs on.



## GET /v1/tts/voices/{vendor}/{voiceId}

One voice and the model it runs on

Everything the list returns for a single voice, plus the model it would run on and that model’s benchmarks. Quality labels state what was checked, and `quality.verdict` says whether the voice was measured at all.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `vendor` (string, in path, required)
- `voiceId` (string, in path, required): Case-sensitive, exactly as the provider spells it.

### Responses

#### 200: Voice detail

Content type: `application/json`

- `model` (object | null, optional)
  - `id` (string, required)
  - `provider` (string, required)
  - `model` (string, required)
  - `routable` (boolean, required)
  - `routable_via` (string | null, optional): One of: `"platform_key"`, `"byok"`, `null`.
  - `benchmark` (object, required)
    - `language` (string, optional)
    - `board` (string, optional)
    - `naturalness` (object, optional): One measured axis, with its unit and direction stated so a caller never has to infer them.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `robustness` (object, optional): One measured axis, with its unit and direction stated so a caller never has to infer them.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `panel_mos` (object, optional): A 0-5 direct-rating scale. `naturalness` uses a different scale.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `panel_named_pct` (object, optional): One measured axis, with its unit and direction stated so a caller never has to infer them.
      - `value` (number, required)
      - `unit` (string, required): `elo_arena`, `score_0_1`, `mos_0_5`, `percent`.
      - `higher_is_better` (boolean, required)
      - `board` (string, optional)
      - `ci` (array of number, optional)
      - `n` (integer, optional)
      - `basis` (string, optional): Robustness fixture basis. Do not read small gaps across different bases as real.
      - `unjudgeable` (integer, optional)
      - `field_mean` (number, optional): Naturalness only: 1500, the per-language field average.
      - `comparable_across_languages` (boolean, optional): Naturalness only, and always false. Arena Elo is fit per language.
      - `estimated` (boolean, optional): Present and true when the score came from Speko’s own scorer rather than human votes.
    - `latency_ms` (number | null, optional): The ranked reading: first-audio p50. The only latency to sort on. Null where the model has no reading.
    - `latency_evidence` (object, optional): The region and sample size behind `latency_ms`. Present whenever `latency_ms` is non-null.
      - `board` (string, optional)
      - `region` (string, optional)
      - `n` (integer, optional)
      - `p90_ms` (number, optional)
    - `latency` (object, optional): TTS latency detail, published beside `latency_ms` and `latency_evidence` rather than in place of them. The blocks are different quantities, so do not compare them with each other or with `latency_ms`.
      - `vendor_direct` (array of object, optional): The reading in each region it covers. The row whose `location` equals `latency_evidence.region` is the same number as `latency_ms`; the others are the regional siblings the ranked field does not carry.
        - `region` (string, optional)
        - `location` (string, optional)
        - `p50_ms` (number, optional)
        - `p90_ms` (number | null, optional)
      - `per_language` (array of object, optional): Per-language time to first audio, p50 and p90. Measured differently from `latency_ms`, so these rows compare with each other and never against it. `n`, `sweeps` and `wide_tail` describe each row on its own terms.
        - `language` (string, optional)
        - `p50` (number, optional)
        - `p90` (number, optional)
        - `n` (integer, optional)
        - `sweeps` (integer, optional)
        - `wide_tail` (boolean, optional): p90/p50 above 1.7, a tail this row’s sample size cannot resolve. Do not read movement between sweeps as change.
        - `voice` (string, optional)
    - `cost` (object, optional): Always present. On a model with no board row every number is null, which is a different answer from the field being absent.
      - `per_1m_chars_usd` (number | null, optional)
      - `per_min_usd` (number | null, optional): Derived, not measured: `per_1m_chars_usd x 900 / 1e6`.
      - `higher_is_better` (boolean, optional)
  - `languages` (object, optional)
    - `measured` (array of string, optional): Language tags this model is measured on.
    - `vendor_claimed` (array of string, optional): The vendor lists the language but we have not probed it.
    - `count` (integer, optional)
  - `voices` (object, optional): How many voices can be used with this model, how many of those carry a measurement, and how the pairing was established. Pass `?model=` to `/v1/tts/voices` to list them.
    - `total` (integer, optional)
    - `measured` (integer, optional): How many of those voices carry a measurement.
    - `compatibility` (string, optional): One of: `"verified"`, `"vendor_roster"`, `"restricted"`.
- `meta` (object, optional)
  - `benchmark` (object, optional)
    - `schema` (integer, optional)
    - `routing_policy_version` (string, optional)
  - `quality_overlay` (object, optional)
    - `generated_at` (string, optional)
    - `run_id` (string, optional)
  - `org_routable_vendors` (array of string, optional)
  - `coverage` (object, optional)
    - `models_routable` (integer, optional)
    - `models_measured` (integer, optional)
    - `voices_routable` (integer, optional)
    - `voices_measured` (integer, optional)
  - `notes` (array of string, optional): The caveats that stop a number being read as something it is not.
- `id` (string, required)
- `vendor` (string, required)
- `voice_id` (string, required)
- `name` (string, required)
- `gender` (string | null, optional)
- `accent` (string | null, optional)
- `languages` (array of string, optional)
- `styles` (array of string, optional): Descriptive words only. Measured quality is in `quality.labels`.
- `use_with` (object, required): The exact triple to send to `POST /v1/synthesize` or `POST /v1/sessions`. Pass it through unmodified.
  - `provider` (string, required)
  - `model` (string, required)
  - `voice` (string, required)
- `model_id` (string, required)
- `voice_compatibility` (string, optional): `verified` = this voice/model pairing is individually confirmed. `vendor_roster` = same vendor, pairing inferred from vendor-level voice ownership. `restricted` = the model accepts only a documented subset of its vendor’s voices. One of: `"verified"`, `"vendor_roster"`, `"restricted"`.
- `quality` (object, required)
  - `verdict` (string, required): `measured_no_labels` means we measured the voice and it cleared nothing. `unmeasured` means we never measured it. Only positive labels are emitted, so an empty `labels` array is a result in the first case and a gap in the second. One of: `"measured"`, `"measured_no_labels"`, `"unmeasured"`.
  - `basis` (string | null, optional): `longform-render` or `preview-clip`. Several axes are only computable from a long-form render.
  - `labels` (array of string, required): Human display strings, e.g. `["no hiss","steady to the end","10k chars"]`, in canonical chip order. The cumulative capacity rungs collapse to the highest one held.
  - `summary` (array of string, optional)
  - `max_chars_per_call` (integer | null, optional)
  - `words_per_minute` (number | null, optional)
- `why` (object | null, optional): Generated from deterministic templates over the measured numbers. No model writes this copy.
  - `best_for` (array of string, optional)
  - `strengths` (array of string, optional)
  - `weaknesses` (array of string, optional)
  - `tradeoffs` (array of string, optional)

Example:

```json
{
  "model": {
    "id": "cartesia:sonic-3.5",
    "provider": "string",
    "model": "string",
    "routable": true,
    "routable_via": "platform_key",
    "benchmark": {
      "language": "string",
      "board": "string",
      "naturalness": {
        "value": 0,
        "unit": "string",
        "higher_is_better": true,
        "board": "string",
        "ci": [
          0
        ],
        "n": 0,
        "basis": "string",
        "unjudgeable": 0,
        "field_mean": 0,
        "comparable_across_languages": true,
        "estimated": true
      },
      "robustness": {
        "value": 0,
        "unit": "string",
        "higher_is_better": true,
        "board": "string",
        "ci": [
          0
        ],
        "n": 0,
        "basis": "string",
        "unjudgeable": 0,
        "field_mean": 0,
        "comparable_across_languages": true,
        "estimated": true
      },
      "panel_mos": {
        "value": 0,
        "unit": "string",
        "higher_is_better": true,
        "board": "string",
        "ci": [
          0
        ],
        "n": 0,
        "basis": "string",
        "unjudgeable": 0,
        "field_mean": 0,
        "comparable_across_languages": true,
        "estimated": true
      },
      "panel_named_pct": {
        "value": 0,
        "unit": "string",
        "higher_is_better": true,
        "board": "string",
        "ci": [
          0
        ],
        "n": 0,
        "basis": "string",
        "unjudgeable": 0,
        "field_mean": 0,
        "comparable_across_languages": true,
        "estimated": true
      },
      "latency_ms": 0,
      "latency_evidence": {
        "board": "string",
        "region": "string",
        "n": 0,
        "p90_ms": 0
      },
      "latency": {
        "vendor_direct": [
          {
            "region": null,
            "location": null,
            "p50_ms": null,
            "p90_ms": null
          }
        ],
        "per_language": [
          {
            "language": null,
            "p50": null,
            "p90": null,
            "n": null,
            "sweeps": null,
            "wide_tail": null,
            "voice": null
          }
        ]
      },
      "cost": {
        "per_1m_chars_usd": 0,
        "per_min_usd": 0,
        "higher_is_better": true
      }
    },
    "languages": {
      "measured": [
        "string"
      ],
      "vendor_claimed": [
        "string"
      ],
      "count": 0
    },
    "voices": {
      "total": 0,
      "measured": 0,
      "compatibility": "verified"
    }
  },
  "meta": {
    "benchmark": {
      "schema": 0,
      "routing_policy_version": "string"
    },
    "quality_overlay": {
      "generated_at": "string",
      "run_id": "string"
    },
    "org_routable_vendors": [
      "string"
    ],
    "coverage": {
      "models_routable": 0,
      "models_measured": 0,
      "voices_routable": 0,
      "voices_measured": 0
    },
    "notes": [
      "string"
    ]
  },
  "id": "cartesia:f9836c6e-a0bd-460e-9d3c-f7299fa60f94",
  "vendor": "string",
  "voice_id": "string",
  "name": "string",
  "gender": "string",
  "accent": "string",
  "languages": [
    "string"
  ],
  "styles": [
    "string"
  ],
  "use_with": {
    "provider": "string",
    "model": "string",
    "voice": "string"
  },
  "model_id": "string",
  "voice_compatibility": "verified",
  "quality": {
    "verdict": "measured",
    "basis": "string",
    "labels": [
      "string"
    ],
    "summary": [
      "string"
    ],
    "max_chars_per_call": 0,
    "words_per_minute": 0
  },
  "why": {
    "best_for": [
      "string"
    ],
    "strengths": [
      "string"
    ],
    "weaknesses": [
      "string"
    ],
    "tradeoffs": [
      "string"
    ]
  }
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: No such voice, or it is not routable for this organization.

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/tts/voices/{vendor}/{voiceId}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# TTS Voices (/api-reference/tts-voices)

Browse voices by measured quality (no hiss, steady to the end, repeatable, characters per call) and get the provider, model and voice ids to synthesize with.



## GET /v1/tts/voices

Browse TTS voices by measured quality

Paginated voice list with measured quality labels and the benchmarks of the model each voice would run on.

One parameter gets you a long way: `?use_case=longform` or `?use_case=phone`. Longform returns a short list, because it requires the `consistent` label that roughly a fifth of routed voices hold, concentrated in two vendors. When a filter set returns little, `blockers` names the requirements holding the rest back, and each entry says whether relaxing that one alone would admit anything.

Every row carries `use_with`, the provider, model and voice ids to send to `POST /v1/synthesize`.

Always scoped to what this organization can route. Unlike `/v1/tts/models` there is no way to widen it.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `use_case` (string, in query, optional): Expands to a bundle of quality requirements plus a capacity floor. Combine with `quality` to tighten it. One of: `"longform"`, `"phone"`.
- `quality` (array of string, in query, optional): Repeatable, and repeats mean AND. `GET /v1/tts/meta` documents what each value asserts.
- `min_chars_per_call` (integer, in query, optional): A floor. Returns voices that accept at least this much in one call. One of: `5000`, `7500`, `10000`, `20000`.
- `pace` (string, in query, optional): An exact bucket. `normal` excludes `brisk`. One of: `"slow"`, `"normal"`, `"brisk"`, `"fast"`.
- `vendor` (string, in query, optional)
- `gender` (string, in query, optional): One of: `"male"`, `"female"`, `"neutral"`.
- `accent` (string, in query, optional)
- `language` (string, in query, optional): Filter voices by supported language. Exact when a region is named, prefix otherwise.
- `model` (string, in query, optional): Pin to one model id. Compatible voices are re-paired onto it, so `use_with` names the model you asked for rather than the vendor default, and `voice_compatibility` says whether that pairing is individually verified.
- `benchmark_language` (string, in query, optional): Which language the embedded model benchmarks report. Default: `"en"`.
- `sort` (string, in query, optional): Measured voices sort before unmeasured ones on every axis except `name`, which is purely alphabetical. A voice with no value on the chosen axis sorts last in either direction. One of: `"model_naturalness"`, `"latency"`, `"model_cost"`, `"pace"`, `"max_chars"`, `"name"`. Default: `"model_naturalness"`.
- `limit` (integer, in query, optional): Default: `25`. Min: 1. Max: 100.
- `cursor` (string, in query, optional): From a previous `next_cursor`. Tied to the filter and sort it was issued for; changing either returns `INVALID_CURSOR` instead of silently reshuffling the page.
- `include_unmeasured` (string, in query, optional): Set `false` to drop voices that were never measured. Voices that were measured and cleared no label (`verdict: measured_no_labels`) are kept, since that is a result rather than a gap. One of: `"true"`, `"false"`, `"1"`, `"0"`. Default: `"true"`.

### Responses

#### 200: Voice list

Content type: `application/json`

- `object` (string, optional)
- `total` (integer, optional): Total matching the filters, not the page size.
- `next_cursor` (string | null, optional)
- `data` (array of object, optional)
  - `id` (string, required)
  - `vendor` (string, required)
  - `voice_id` (string, required)
  - `name` (string, required)
  - `gender` (string | null, optional)
  - `accent` (string | null, optional)
  - `languages` (array of string, optional)
  - `styles` (array of string, optional): Descriptive words only. Measured quality is in `quality.labels`.
  - `use_with` (object, required): The exact triple to send to `POST /v1/synthesize` or `POST /v1/sessions`. Pass it through unmodified.
    - `provider` (string, required)
    - `model` (string, required)
    - `voice` (string, required)
  - `model_id` (string, required)
  - `voice_compatibility` (string, optional): `verified` = this voice/model pairing is individually confirmed. `vendor_roster` = same vendor, pairing inferred from vendor-level voice ownership. `restricted` = the model accepts only a documented subset of its vendor’s voices. One of: `"verified"`, `"vendor_roster"`, `"restricted"`.
  - `quality` (object, required)
    - `verdict` (string, required): `measured_no_labels` means we measured the voice and it cleared nothing. `unmeasured` means we never measured it. Only positive labels are emitted, so an empty `labels` array is a result in the first case and a gap in the second. One of: `"measured"`, `"measured_no_labels"`, `"unmeasured"`.
    - `basis` (string | null, optional): `longform-render` or `preview-clip`. Several axes are only computable from a long-form render.
    - `labels` (array of string, required): Human display strings, e.g. `["no hiss","steady to the end","10k chars"]`, in canonical chip order. The cumulative capacity rungs collapse to the highest one held.
    - `summary` (array of string, optional)
    - `max_chars_per_call` (integer | null, optional)
    - `words_per_minute` (number | null, optional)
  - `why` (object | null, optional): Generated from deterministic templates over the measured numbers. No model writes this copy.
    - `best_for` (array of string, optional)
    - `strengths` (array of string, optional)
    - `weaknesses` (array of string, optional)
    - `tradeoffs` (array of string, optional)
- `models` (object, optional): The models this page references, keyed by id, included once rather than repeated per voice.
- `facets` (object, optional): Self-excluding counts: each group is computed with its own filter dropped, so `vendor` still lists every vendor when `?vendor=` is set. `quality` is multi-valued, so its whole group is dropped and each axis reports what that axis alone would return with the other slots still applied. The quality counts therefore do not move when the quality selection changes, and a count is not "what relaxing this one requirement would give" once two or more axes are selected. For that, read `blockers`.
  - `vendor` (array of object, optional)
    - `value` (string, optional)
    - `count` (integer, optional)
  - `accent` (array of object, optional)
    - `value` (string, optional)
    - `count` (integer, optional)
  - `quality` (array of object, optional)
    - `value` (string, optional)
    - `label` (string, optional)
    - `count` (integer, optional)
- `blockers` (array of object, optional): Which requirements are holding voices back, so a short result set explains itself. `param` and `value` are what to change or drop to widen the search. `sole_binding` says whether relaxing that one requirement alone would admit anything; when it is false, two or more bind together and `blocks` is that requirement's cost on its own. Counts cover measured voices only, since an unmeasured voice holds no label and so fails every requirement rather than any one of them.
  - `param` (string, optional): The query parameter this requirement came from. One of: `"quality"`, `"pace"`, `"min_chars_per_call"`.
  - `value` (string | integer, optional): The value to drop or relax on that parameter.
  - `label` (string, optional)
  - `blocks` (integer, optional)
  - `hint` (string, optional)
  - `sole_binding` (boolean, optional): True when relaxing this requirement alone would admit more voices. False when no single relaxation helps.
- `meta` (object, optional)
  - `benchmark` (object, optional)
    - `schema` (integer, optional)
    - `routing_policy_version` (string, optional)
  - `quality_overlay` (object, optional)
    - `generated_at` (string, optional)
    - `run_id` (string, optional)
  - `org_routable_vendors` (array of string, optional)
  - `coverage` (object, optional)
    - `models_routable` (integer, optional)
    - `models_measured` (integer, optional)
    - `voices_routable` (integer, optional)
    - `voices_measured` (integer, optional)
  - `notes` (array of string, optional): The caveats that stop a number being read as something it is not.

Example:

```json
{
  "object": "string",
  "total": 0,
  "next_cursor": "string",
  "data": [
    {
      "id": "cartesia:f9836c6e-a0bd-460e-9d3c-f7299fa60f94",
      "vendor": "string",
      "voice_id": "string",
      "name": "string",
      "gender": "string",
      "accent": "string",
      "languages": [
        "string"
      ],
      "styles": [
        "string"
      ],
      "use_with": {
        "provider": "string",
        "model": "string",
        "voice": "string"
      },
      "model_id": "string",
      "voice_compatibility": "verified",
      "quality": {
        "verdict": "measured",
        "basis": "string",
        "labels": [
          "string"
        ],
        "summary": [
          "string"
        ],
        "max_chars_per_call": 0,
        "words_per_minute": 0
      },
      "why": {
        "best_for": [
          "string"
        ],
        "strengths": [
          "string"
        ],
        "weaknesses": [
          "string"
        ],
        "tradeoffs": [
          "string"
        ]
      }
    }
  ],
  "models": {},
  "facets": {
    "vendor": [
      {
        "value": "string",
        "count": 0
      }
    ],
    "accent": [
      {
        "value": "string",
        "count": 0
      }
    ],
    "quality": [
      {
        "value": "string",
        "label": "string",
        "count": 0
      }
    ]
  },
  "blockers": [
    {
      "param": "quality",
      "value": "string",
      "label": "string",
      "blocks": 0,
      "hint": "string",
      "sole_binding": true
    }
  ],
  "meta": {
    "benchmark": {
      "schema": 0,
      "routing_policy_version": "string"
    },
    "quality_overlay": {
      "generated_at": "string",
      "run_id": "string"
    },
    "org_routable_vendors": [
      "string"
    ],
    "coverage": {
      "models_routable": 0,
      "models_measured": 0,
      "voices_routable": 0,
      "voices_measured": 0
    },
    "notes": [
      "string"
    ]
  }
}
```

#### 400: Validation error (`VALIDATION_ERROR`); `INVALID_CURSOR` when a cursor is reused across a different filter or sort; `CURSOR_EXPIRED` when the row a cursor resumes after has left the result set. In both cursor cases, restart the listing without a cursor.

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/tts/voices' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Voices (/api-reference/voices)

Read-only catalog of TTS voices grouped by provider. ElevenLabs voices are account-scoped and fetched live from ElevenLabs rather than returned here.



## GET /v1/voices

List TTS voices

Returns the curated catalog of TTS voices grouped by provider, plus the list of TTS providers Speko routes to. ElevenLabs is included in `providers` with `voicesFetchedLive: true` because its voice library is account-scoped — fetch it directly from `https://api.elevenlabs.io/v1/voices` with the org's key.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `provider` (string, in query, optional): Filter to a single provider's voices. Accepts either the routing key (`cartesia`, `xai`, `alibaba`, `openai`, `inworld`, `elevenlabs`) or the catalog suffix form (`xai-tts`, `alibaba-tts`, `openai-tts`).

### Responses

#### 200: Voice catalog

Content type: `application/json`

- `voices` (array of object, required)
  - `vendor` (string, required): Routing-key vendor (matches `allowedProviders.tts` entries).
  - `id` (string, required): Voice id passed through to the provider's TTS API.
  - `name` (string, required): Human-readable label.
- `providers` (array of object, required)
  - `key` (string, required)
  - `name` (string, required)
  - `models` (array of string, required)
  - `voicesFetchedLive` (boolean, required): `true` when the provider's voice library is account-scoped and must be fetched live from the provider (currently ElevenLabs).

Example:

```json
{
  "voices": [
    {
      "vendor": "string",
      "id": "string",
      "name": "string"
    }
  ],
  "providers": [
    {
      "key": "string",
      "name": "string",
      "models": [
        "string"
      ],
      "voicesFetchedLive": true
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/voices' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Webhook deliveries (/api-reference/webhook-deliveries)

Search delivery logs, inspect attempts, and redeliver an event.





## GET /v1/webhook-deliveries

List webhook deliveries

Returns one row per endpoint delivery, newest first. Bodies and logs expire after 30 days.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `endpointId` (string, in query, optional)
- `event` (string, in query, optional): One of: `"call.pre_call"`, `"call.status"`, `"call.report"`, `"call.analysis"`, `"call.recording"`, `"imessage.received"`, `"imessage.reaction_received"`, `"imessage.sent"`, `"imessage.delivered"`, `"imessage.delivery_failed"`, `"sms.received"`, `"sms.accepted"`, `"sms.sent"`, `"sms.delivered"`, `"sms.delivery_failed"`, `"sms.submission_unknown"`, `"sms.opted_out"`, `"sms.opted_in"`.
- `agentId` (string, in query, optional)
- `status` (string, in query, optional): One of: `"pending"`, `"delivering"`, `"succeeded"`, `"failed"`, `"cancelled"`, `"expired"`.
- `sessionId` (string (uuid), in query, optional)
- `eventId` (string, in query, optional): Speko lifecycle webhook UUID or stable provider event ID.
- `from` (string (date-time), in query, optional)
- `to` (string (date-time), in query, optional)
- `cursor` (string, in query, optional): Opaque cursor from a previous response.
- `limit` (integer, in query, optional): Default: `50`. Min: 1. Max: 100.

### Responses

#### 200: Delivery page.

Content type: `application/json`

- `data` (array of object, required)
  - `id` (string (uuid), required)
  - `eventId` (string, required): Stable Speko or upstream-provider webhook ID.
  - `endpointId` (string, required)
  - `endpointName` (string, required)
  - `endpointKind` (string, required): One of: `"workspace"`, `"imessage"`.
  - `endpointDeleted` (boolean, required)
  - `event` (string, required): One of: `"call.pre_call"`, `"call.status"`, `"call.report"`, `"call.analysis"`, `"call.recording"`, `"imessage.received"`, `"imessage.reaction_received"`, `"imessage.sent"`, `"imessage.delivered"`, `"imessage.delivery_failed"`, `"sms.received"`, `"sms.accepted"`, `"sms.sent"`, `"sms.delivered"`, `"sms.delivery_failed"`, `"sms.submission_unknown"`, `"sms.opted_out"`, `"sms.opted_in"`.
  - `sessionId` (string | null (uuid), required)
  - `agentId` (string | null, required)
  - `webhookTags` (object, required)
  - `status` (string, required): One of: `"pending"`, `"delivering"`, `"succeeded"`, `"failed"`, `"cancelled"`, `"expired"`.
  - `attempts` (integer, required)
  - `httpStatus` (integer | null, required)
  - `error` (string | null, required)
  - `occurredAt` (string (date-time), required)
  - `expiresAt` (string (date-time), required)
  - `deliveredAt` (string | null (date-time), required)
  - `createdAt` (string (date-time), required)
  - `canRedeliver` (boolean, required): Whether manual redelivery is currently available.
- `nextCursor` (string | null, required)
- `endpointOptions` (array of object, required)
  - `id` (string, required)
  - `name` (string, required)
  - `kind` (string, required): One of: `"workspace"`, `"imessage"`.
  - `deleted` (boolean, required)

Example:

```json
{
  "data": [
    {
      "id": "string",
      "eventId": "string",
      "endpointId": "string",
      "endpointName": "string",
      "endpointKind": "workspace",
      "endpointDeleted": true,
      "event": "call.pre_call",
      "sessionId": "string",
      "agentId": "string",
      "webhookTags": {},
      "status": "pending",
      "attempts": 0,
      "httpStatus": 0,
      "error": "string",
      "occurredAt": "2026-01-01T00:00:00Z",
      "expiresAt": "2026-01-01T00:00:00Z",
      "deliveredAt": "2026-01-01T00:00:00Z",
      "createdAt": "2026-01-01T00:00:00Z",
      "canRedeliver": true
    }
  ],
  "nextCursor": "string",
  "endpointOptions": [
    {
      "id": "string",
      "name": "string",
      "kind": "workspace",
      "deleted": true
    }
  ]
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/webhook-deliveries' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## GET /v1/webhook-deliveries/{id}

Get webhook delivery details

Returns the stored endpoint-specific payload and chronological sanitized attempt history.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string (uuid), in path, required)

### Responses

#### 200: Delivery details.

Content type: `application/json`

- `attemptCount` (integer, required)
- `requestPayload` (object, required)
- `attempts` (array of object, required)
  - `id` (string (uuid), required)
  - `attemptNumber` (integer, required)
  - `trigger` (string, required): One of: `"automatic"`, `"manual"`.
  - `requestUrl` (string, required): Sanitized URL with query values redacted.
  - `requestHeaders` (object, required)
  - `requestBody` (object, required)
  - `responseStatus` (integer | null, required)
  - `responseBody` (string | null, required)
  - `responseTruncated` (boolean, required)
  - `durationMs` (integer, required)
  - `error` (string | null, required)
  - `createdAt` (string (date-time), required)

Example:

```json
{
  "attemptCount": 0,
  "requestPayload": {},
  "attempts": [
    {
      "id": "string",
      "attemptNumber": 0,
      "trigger": "automatic",
      "requestUrl": "string",
      "requestHeaders": {},
      "requestBody": {},
      "responseStatus": 0,
      "responseBody": "string",
      "responseTruncated": true,
      "durationMs": 0,
      "error": "string",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Delivery not found.

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/webhook-deliveries/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/webhook-deliveries/{id}/redeliver

Redeliver a webhook

Adds a manual attempt using the original event payload and webhook ID with the endpoint's current URL and credentials. Pre-call, expired, and provider-retried iMessage deliveries cannot be manually redelivered.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Parameters

- `id` (string (uuid), in path, required)

### Responses

#### 200: Manual delivery result.

Content type: `application/json`

- `delivered` (boolean, required)
- `httpStatus` (integer | null, required)
- `error` (string | null, required)

Example:

```json
{
  "delivered": true,
  "httpStatus": 0,
  "error": "string"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Delivery not found.

#### 409: Delivery is expired, pre-call, provider-retried, or belongs to a deleted endpoint.

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/webhook-deliveries/{id}/redeliver' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Webhooks (/api-reference/webhooks)

Create and manage organization lifecycle webhook endpoints.





## GET /v1/webhooks

List webhook endpoints

Lists active organization-level lifecycle webhook endpoints. Secret values are never returned.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: Active webhook endpoints.

Content type: `application/json`

- `data` (array of object, required)
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `url` (string (uri), required)
  - `events` (array of string, required)
  - `allAgents` (boolean, required)
  - `agentIds` (array of string, required)
  - `filterTags` (object, required)
  - `headers` (object, required)
  - `authHeaders` (array of object, required)
    - `name` (string, required)
    - `configured` (true, required)
  - `timeoutMs` (integer, required)
  - `signingSecretSource` (string, required): One of: `"workspace"`, `"custom"`.
  - `hasCustomSigningSecret` (boolean, required)
  - `extractionFields` (array of object, required)
    - `name` (string, required): Pattern: `^[A-Za-z_][A-Za-z0-9_]*$`.
    - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
    - `description` (string, required)
    - `options` (array of string, optional)
  - `contentMode` (string, required): One of: `"full"`, `"metadata_only"`.
  - `legacyManaged` (boolean, required): True when synchronized from deprecated agent.webhooks fields.
  - `createdAt` (string (date-time), required)
  - `updatedAt` (string (date-time), required)

Example:

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "url": "string",
      "events": [
        "call.pre_call"
      ],
      "allAgents": true,
      "agentIds": [
        "string"
      ],
      "filterTags": {},
      "headers": {},
      "authHeaders": [
        {
          "name": "string",
          "configured": true
        }
      ],
      "timeoutMs": 0,
      "signingSecretSource": "workspace",
      "hasCustomSigningSecret": true,
      "extractionFields": [
        {
          "name": "string",
          "type": "string",
          "description": "string",
          "options": [
            null
          ]
        }
      ],
      "contentMode": "full",
      "legacyManaged": true,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## POST /v1/webhooks

Create a webhook endpoint

Creates an organization endpoint with event, agent, and optional tag routing. Plaintext signing and auth-header secrets are write-only.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `name` (string, required)
- `url` (string (uri), required)
- `events` (array of string, required)
- `allAgents` (boolean, optional): Default: `true`.
- `agentIds` (array of string, optional)
- `filterTags` (object, optional): Case-sensitive subset match. Tagged matches override untagged defaults.
- `headers` (object, optional)
- `authHeaders` (array of object, optional)
  - `name` (string, required)
  - `value` (string, optional): Required when creating a new secret header. Omit during update to preserve its encrypted value.
- `timeoutMs` (integer, optional): Default: `4000`. Min: 500. Max: 8000.
- `signingSecretSource` (string, optional): One of: `"workspace"`, `"custom"`. Default: `"workspace"`.
- `signingSecret` (string, optional): Required when signingSecretSource is custom. Never returned.
- `extractionFields` (array of object, optional)
  - `name` (string, required): Pattern: `^[A-Za-z_][A-Za-z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)
- `contentMode` (string, optional): Controls whether SMS webhook payloads include message text. One of: `"full"`, `"metadata_only"`. Default: `"full"`.

Example body:

```json
{
  "name": "string",
  "url": "string",
  "events": [
    "call.pre_call"
  ],
  "allAgents": true,
  "agentIds": [
    "string"
  ],
  "filterTags": {},
  "headers": {},
  "authHeaders": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "timeoutMs": 4000,
  "signingSecretSource": "workspace",
  "signingSecret": "string",
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ],
  "contentMode": "full"
}
```

### Responses

#### 201: Endpoint created.

Content type: `application/json`

- `id` (string (uuid), required)
- `name` (string, required)
- `url` (string (uri), required)
- `events` (array of string, required)
- `allAgents` (boolean, required)
- `agentIds` (array of string, required)
- `filterTags` (object, required)
- `headers` (object, required)
- `authHeaders` (array of object, required)
  - `name` (string, required)
  - `configured` (true, required)
- `timeoutMs` (integer, required)
- `signingSecretSource` (string, required): One of: `"workspace"`, `"custom"`.
- `hasCustomSigningSecret` (boolean, required)
- `extractionFields` (array of object, required)
  - `name` (string, required): Pattern: `^[A-Za-z_][A-Za-z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)
- `contentMode` (string, required): One of: `"full"`, `"metadata_only"`.
- `legacyManaged` (boolean, required): True when synchronized from deprecated agent.webhooks fields.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "name": "string",
  "url": "string",
  "events": [
    "call.pre_call"
  ],
  "allAgents": true,
  "agentIds": [
    "string"
  ],
  "filterTags": {},
  "headers": {},
  "authHeaders": [
    {
      "name": "string",
      "configured": true
    }
  ],
  "timeoutMs": 0,
  "signingSecretSource": "workspace",
  "hasCustomSigningSecret": true,
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ],
  "contentMode": "full",
  "legacyManaged": true,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 409: The endpoint conflicts with an existing extraction definition or pre-call route.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "string",
  "code": "string"
}
```

### Example request

```bash
curl -X POST 'https://api.speko.dev/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","url":"string","events":["call.pre_call"],"allAgents":true,"agentIds":["string"],"filterTags":{},"headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":4000,"signingSecretSource":"workspace","signingSecret":"string","extractionFields":[{"name":"string","type":"string","description":"string","options":["string"]}],"contentMode":"full"}'
```

## GET /v1/webhooks/{id}

Get a webhook endpoint

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 200: Webhook endpoint.

Content type: `application/json`

- `id` (string (uuid), required)
- `name` (string, required)
- `url` (string (uri), required)
- `events` (array of string, required)
- `allAgents` (boolean, required)
- `agentIds` (array of string, required)
- `filterTags` (object, required)
- `headers` (object, required)
- `authHeaders` (array of object, required)
  - `name` (string, required)
  - `configured` (true, required)
- `timeoutMs` (integer, required)
- `signingSecretSource` (string, required): One of: `"workspace"`, `"custom"`.
- `hasCustomSigningSecret` (boolean, required)
- `extractionFields` (array of object, required)
  - `name` (string, required): Pattern: `^[A-Za-z_][A-Za-z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)
- `contentMode` (string, required): One of: `"full"`, `"metadata_only"`.
- `legacyManaged` (boolean, required): True when synchronized from deprecated agent.webhooks fields.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "name": "string",
  "url": "string",
  "events": [
    "call.pre_call"
  ],
  "allAgents": true,
  "agentIds": [
    "string"
  ],
  "filterTags": {},
  "headers": {},
  "authHeaders": [
    {
      "name": "string",
      "configured": true
    }
  ],
  "timeoutMs": 0,
  "signingSecretSource": "workspace",
  "hasCustomSigningSecret": true,
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ],
  "contentMode": "full",
  "legacyManaged": true,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Endpoint not found.

### Example request

```bash
curl -X GET 'https://api.speko.dev/v1/webhooks/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```

## PATCH /v1/webhooks/{id}

Update a webhook endpoint

Updates supplied endpoint fields. Omit an existing secret auth-header value to retain it.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Request body

Required.

Content types: `application/json`

- `name` (string, optional)
- `url` (string (uri), optional)
- `events` (array of string, optional)
- `allAgents` (boolean, optional): Default: `true`.
- `agentIds` (array of string, optional)
- `filterTags` (object, optional): Case-sensitive subset match. Tagged matches override untagged defaults.
- `headers` (object, optional)
- `authHeaders` (array of object, optional)
  - `name` (string, required)
  - `value` (string, optional): Required when creating a new secret header. Omit during update to preserve its encrypted value.
- `timeoutMs` (integer, optional): Default: `4000`. Min: 500. Max: 8000.
- `signingSecretSource` (string, optional): One of: `"workspace"`, `"custom"`. Default: `"workspace"`.
- `signingSecret` (string, optional): Required when signingSecretSource is custom. Never returned.
- `extractionFields` (array of object, optional)
  - `name` (string, required): Pattern: `^[A-Za-z_][A-Za-z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)
- `contentMode` (string, optional): Controls whether SMS webhook payloads include message text. One of: `"full"`, `"metadata_only"`. Default: `"full"`.

Example body:

```json
{
  "name": "string",
  "url": "string",
  "events": [
    "call.pre_call"
  ],
  "allAgents": true,
  "agentIds": [
    "string"
  ],
  "filterTags": {},
  "headers": {},
  "authHeaders": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "timeoutMs": 4000,
  "signingSecretSource": "workspace",
  "signingSecret": "string",
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ],
  "contentMode": "full"
}
```

### Responses

#### 200: Updated endpoint.

Content type: `application/json`

- `id` (string (uuid), required)
- `name` (string, required)
- `url` (string (uri), required)
- `events` (array of string, required)
- `allAgents` (boolean, required)
- `agentIds` (array of string, required)
- `filterTags` (object, required)
- `headers` (object, required)
- `authHeaders` (array of object, required)
  - `name` (string, required)
  - `configured` (true, required)
- `timeoutMs` (integer, required)
- `signingSecretSource` (string, required): One of: `"workspace"`, `"custom"`.
- `hasCustomSigningSecret` (boolean, required)
- `extractionFields` (array of object, required)
  - `name` (string, required): Pattern: `^[A-Za-z_][A-Za-z0-9_]*$`.
  - `type` (string, required): One of: `"string"`, `"number"`, `"boolean"`, `"enum"`.
  - `description` (string, required)
  - `options` (array of string, optional)
- `contentMode` (string, required): One of: `"full"`, `"metadata_only"`.
- `legacyManaged` (boolean, required): True when synchronized from deprecated agent.webhooks fields.
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

Example:

```json
{
  "id": "string",
  "name": "string",
  "url": "string",
  "events": [
    "call.pre_call"
  ],
  "allAgents": true,
  "agentIds": [
    "string"
  ],
  "filterTags": {},
  "headers": {},
  "authHeaders": [
    {
      "name": "string",
      "configured": true
    }
  ],
  "timeoutMs": 0,
  "signingSecretSource": "workspace",
  "hasCustomSigningSecret": true,
  "extractionFields": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "options": [
        "string"
      ]
    }
  ],
  "contentMode": "full",
  "legacyManaged": true,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

#### 400: Request body or query parameters failed validation.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}
```

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Endpoint not found.

#### 409: Routing or extraction conflict.

### Example request

```bash
curl -X PATCH 'https://api.speko.dev/v1/webhooks/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","url":"string","events":["call.pre_call"],"allAgents":true,"agentIds":["string"],"filterTags":{},"headers":{},"authHeaders":[{"name":"string","value":"string"}],"timeoutMs":4000,"signingSecretSource":"workspace","signingSecret":"string","extractionFields":[{"name":"string","type":"string","description":"string","options":["string"]}],"contentMode":"full"}'
```

## DELETE /v1/webhooks/{id}

Delete a webhook endpoint

Soft-deletes the endpoint and cancels pending retries. Existing delivery history remains until its 30-day expiry.

Auth: required. Send `Authorization: Bearer <SPEKO_API_KEY>` (API key (sk_live_...)).

### Responses

#### 204: Endpoint deleted.

#### 401: Missing or invalid bearer token.

Content type: `application/json`

- `error` (string, required): Human-readable message.
- `code` (string, required): Machine-readable code.

Example:

```json
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
```

#### 404: Endpoint not found.

### Example request

```bash
curl -X DELETE 'https://api.speko.dev/v1/webhooks/{id}' \
  -H 'Authorization: Bearer YOUR_SPEKO_API_KEY'
```


# Human calling (/guides/human-calling)

Programmable calls between people: browser softphones for your team, PSTN legs for everyone else, and Telnyx-style call control over both.



Human calling connects **people** — an agent (a broker, a rep, a dispatcher) on a browser softphone and a phone number on the PSTN — as legs of one call, with server-side control over every leg. It is a separate product from Speko's AI voice sessions: there is no STT→LLM→TTS pipeline, no agent worker, and no `voice_session`. Calls get their own resources, their own event stream, and their own webhook events.

The API is modeled on Telnyx Call Control. Every leg of a call has an opaque `controlId` — the equivalent of Telnyx's `call_control_id` — and every command is addressed to that handle. If you are porting an integration off Telnyx, the mapping is meant to be mechanical; see [Porting from Telnyx](#porting-from-telnyx).

<Callout type="info">
  Human calling is in **early access** and is enabled per workspace. If calls fail with HTTP 503 and code `HUMAN_CALLING_DISABLED`, ask us to turn it on for your organization.
</Callout>

## Concepts [#concepts]

| Term            | What it is                                                                                                                                                     |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Call**        | One conversation. Holds legs, a status (`initiating` → `ringing` → `active` → `ended` / `declined` / `missed` / `cancelled` / `failed`), and an event history. |
| **Leg**         | One participant's connection to the call. Kinds: `browser` (a person on a softphone), `pstn` (a phone number), `agent` (an AI session bridged in).             |
| **`controlId`** | The opaque handle every command is addressed to. One per leg. Returned when the leg is created and in every read.                                              |
| **Presence**    | Whether a specific broker can be rung right now. Inbound routing only rings brokers who are `available` with a fresh heartbeat.                                |

## API key and broker identity [#api-key-and-broker-identity]

An API key (`sk_…`) authenticates your organization. A `brokerId` identifies one softphone inside the identity namespace your organization owns. Supply both when you instantiate the SDK; broker-scoped methods automatically include the id in their requests:

```ts
import { Speko } from '@spekoai/sdk';

const speko = new Speko({
  apiKey: process.env.SPEKO_API_KEY!,
  brokerId: 'broker-42', // your stable id for this person/device
});
```

`brokerId` must start with a letter or digit, may contain letters, digits, `.`, `_`, and `-`, and is limited to 128 characters. Direct REST callers send the same `brokerId` in presence, dial, and join request bodies. Commands and org-wide reads need only the API key.

## Come online: presence [#come-online-presence]

A broker who wants to receive calls does two things: **registers** and **holds a presence connection open**.

```ts
import { PRESENCE_STALE_AFTER_MS } from '@spekoai/sdk';

// 1. Register + mint the presence-room credentials in one round trip.
const presence = await speko.callControl.presenceToken();
// → { token, url, identity, roomName, expiresAt }

// 2. Heartbeat on a timer. Presence goes stale after 90 seconds without one,
//    and a stale broker is skipped by routing no matter what their status says.
setInterval(() => speko.callControl.heartbeat(), PRESENCE_STALE_AFTER_MS / 3);
```

Connect to the presence room with [`livekit-client`](https://www.npmjs.com/package/livekit-client) and listen for data messages on the topic `speko.human_call`. Every message is JSON — either a ring offer or a live call event:

```ts
import { Room, RoomEvent } from 'livekit-client';

const presenceRoom = new Room();
await presenceRoom.connect(presence.url, presence.token);

presenceRoom.on(RoomEvent.DataReceived, (payload, _participant, _kind, topic) => {
  if (topic !== 'speko.human_call') return;
  const message = JSON.parse(new TextDecoder().decode(payload));

  if (message.type === 'incoming_call') {
    // A RingOffer: { callId, controlId, roomName, caller: { brokerId, name, phoneNumber } }
    showIncomingCallUI(message);
  } else if (message.type === 'call_event') {
    // A CallEventResource, same shape as GET /v1/voice/calls/{id}/events —
    // the far end hung up, a transfer completed, a supervisor bridged in.
    // This is also how a ring is cancelled: a caller who gives up produces
    // call.leg.hangup / call.hangup here; dismiss the ring UI on those.
    applyCallEvent(message.event);
  }
});
```

Availability is a first-class state — send `busy` or `away` to keep the heartbeat alive while diverting inbound, or `offline` to leave routing entirely:

```ts
await speko.callControl.setStatus('busy');
```

`GET /v1/voice/presence` returns the org roster (`{ brokers: [...] }`, each with `brokerId`, `status`, `lastSeenAt`, and a computed `reachable`) — build your team's availability board from it.

## Dial out [#dial-out]

`POST /v1/voice/calls` places an outbound PSTN call. The browser leg belongs to the SDK instance's configured `brokerId`.

```ts
const { call, join } = await speko.callControl.dial({ to: '+12015551234' });

const mine = call.legs.find((leg) => leg.kind === 'browser')!; // your softphone
const theirs = call.legs.find((leg) => leg.kind === 'pstn')!; // the far end
```

Two things about the response:

* **It resolves when the call exists, not when it is answered.** The PSTN leg comes back `initiating` or `ringing`; watch the event stream (or your own room connection) for `call.answered`.
* **Your join credentials ship with the call.** Connect to `join.url` with `join.token` immediately — your softphone must already be in the room when the far end answers, or the first moments of the conversation are silence. Tokens are short-lived and minted per join; re-join on reconnect rather than caching one.

`from` is optional and must be a number your organization owns; without it, the org's first outbound-capable number is used. With neither, dialing fails with `400 VALIDATION_ERROR`.

```bash
curl -X POST https://api.speko.dev/v1/voice/calls \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "brokerId": "broker-42", "to": "+12015551234", "from": "+12015550199" }'
```

## Receive inbound calls [#receive-inbound-calls]

Point a phone number at a person instead of an AI agent:

```bash
curl -X PATCH https://api.speko.dev/v1/phone-numbers/$NUMBER_ID \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "routeToBrokerId": "broker-42" }'
```

`routeToBrokerId` and `agentId` are mutually exclusive — a number answers to either an agent or a person. Setting one clears the other, so a number can be handed back and forth without a dangling destination.

When that number is called and its broker is reachable, a `RingOffer` arrives on their presence connection. Answering is a three-step sequence, in this order:

```ts
// message is the RingOffer from the presence room
const credentials = await speko.callControl.join(message.controlId); // 1. mint room credentials
await callRoom.connect(credentials.url, credentials.token);          // 2. be in the room
await speko.callControl.answer(message.controlId);                   // 3. connect the audio
```

Join before answering — answering a leg whose participant is not in the room yet gives the caller a silent opening.

<Callout type="warn">
  The PSTN side of an inbound call is answered at the network edge before routing happens, so a caller whose target broker is offline or slow to answer hears **silence**, not ringback. There is no ring-timeout or voicemail fallback yet — drive one from the event stream if you need it, and keep your team's presence heartbeats healthy.
</Callout>

## Control a live call [#control-a-live-call]

Every command is `POST /v1/voice/legs/{controlId}/actions/{command}`, addressed to the leg it acts on. Commands are idempotent by intent — muting a muted leg is a no-op that still returns the leg — and every command returns the leg's post-command state, so you never re-read to learn what you just did.

| Command           | Body                                          | What it does                                                                       |
| ----------------- | --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `answer`          | —                                             | Answer a ringing leg (yours — join the room first).                                |
| `hangup`          | `{ "reason"?: string }`                       | Drop this leg. The call ends when it runs out of live legs.                        |
| `mute` / `unmute` | —                                             | Stop / resume this leg's outgoing audio. A muted leg still hears the call.         |
| `hold` / `unhold` | —                                             | Park / resume a leg. A held leg neither hears nor is heard; status becomes `held`. |
| `dtmf`            | `{ "digits": string }`                        | Send tones toward a PSTN leg. `0-9`, `*`, `#`, `,`, and `w` (pause), max 64.       |
| `bridge`          | `{ "bridgeTo": controlId }`                   | Pull this leg into another leg's conversation.                                     |
| `transfer`        | `{ "to": string, "mode": "blind" \| "warm" }` | Hand the leg to an E.164 number or another broker's leg.                           |

```bash
curl -X POST https://api.speko.dev/v1/voice/legs/$CONTROL_ID/actions/mute \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Errors carry stable codes: `404 NOT_FOUND` (or a leg you cannot see), `409 LEG_NOT_LIVE` / `409 CALL_NOT_LIVE` for a command on a finished leg, `400 UNSUPPORTED_COMMAND` for a command the leg kind cannot take, `400 BRIDGE_TARGET_INVALID` for a bridge to a leg that is not live or not yours.

### Hold is silent [#hold-is-silent]

There is no hold primitive on the underlying transport, so hold is synthesized by isolating subscriptions in both directions. &#x2A;*With no music-on-hold source, the held party hears nothing at all.** Say "on hold" in your UI and consider announcing the hold verbally first — callers read silence as a dropped call.

Hold and mute are different states: a muted rep still hears the customer; a held customer hears nothing.

### DTMF needs a connected softphone [#dtmf-needs-a-connected-softphone]

Address `dtmf&#x60; to the **`pstn` leg** — the leg the tones are *for*. Any other leg kind fails with `UNSUPPORTED_COMMAND`.

Under the hood, only a participant inside the room can emit SIP tones, so the server relays the command through one connected browser leg. Two consequences:

* A call with **no connected browser leg cannot send DTMF** — the command fails rather than silently doing nothing. Keep the softphone connected while driving an IVR.
* The softphone must implement the relay: listen for data messages on the topic `speko.call_control` and press the keys it is asked to.

```ts
callRoom.on(RoomEvent.DataReceived, (payload, _p, _k, topic) => {
  if (topic !== 'speko.call_control') return;
  const message = JSON.parse(new TextDecoder().decode(payload));
  if (message.type === 'dtmf.press') {
    // message: { controlId (the PSTN leg the tones are for), digits }
    pressDigits(callRoom, message.digits); // publish each digit via publishDtmf(); treat 'w' as a ~500 ms pause
  }
});
```

### Transfers [#transfers]

`transfer` moves a leg elsewhere. `to` is an E.164 number, or the `controlId` of another broker's leg for an internal transfer.

* **`blind`** hands the call off and drops your leg immediately. Watch for `call.transfer.completed` (the carrier owns the leg now) or `call.transfer.failed`.
* **`warm`** parks the far end and opens a consultation room: your leg moves there and the destination is dialed into it, so the two of you talk before the customer is handed over. **You** complete a warm transfer — bridge the consultation leg back into the original call (`call.bridged` fires); there is no `call.transfer.completed` for warm transfers.

One caveat worth designing around: during a transfer, the far end is left alone in the original room but is **not** put on hold — their leg stays `active` with `onHold: false`, and they hear silence. If you want your UI (and the caller's experience) to say "on hold", call `hold` on that leg yourself before transferring.

### Escalate an AI call to a human [#escalate-an-ai-call-to-a-human]

An `agent` leg is an AI voice session participating in a human call. Bridging is leg-to-leg, so pulling a person into an AI conversation — or an AI agent into a human one — is an ordinary `bridge`, not a special escalation API.

## Events and webhooks [#events-and-webhooks]

Every call keeps an ordered history: `GET /v1/voice/calls/{callId}/events`, oldest first. This is the durable record — the recorded equivalent of a Telnyx webhook stream — and the thing to reconcile from.

The same events can be delivered to your [workspace webhooks](/docs/guides/webhooks#call-control-events) (`call.initiated`, `call.ringing`, `call.answered`, `call.bridged`, `call.hold`/`call.unhold`, `call.mute`/`call.unmute`, `call.dtmf.sent`, `call.transfer.*`, `call.leg.hangup`, `call.hangup`). Two things to know:

* **Webhook deliveries are one-shot** — no automatic retries. They are a live projection of the event history, which stays readable over the API, so treat webhooks as a trigger and `events` as the truth.
* **Inbound DTMF (`call.dtmf.received`) is not webhook-subscribable.** A key pressed by the far end arrives as an in-room data packet observable by your connected softphone, never by the webhook receiver.

Human calls have no agent, so webhook endpoints scoped to specific `agentIds` never receive call-control events — subscribe with `allAgents`.

## Porting from Telnyx [#porting-from-telnyx]

| Telnyx Call Control        | Speko                                                                       |
| -------------------------- | --------------------------------------------------------------------------- |
| `call_control_id`          | `controlId` (per leg)                                                       |
| `POST /calls` (Dial)       | `POST /v1/voice/calls`                                                      |
| `actions/answer`           | `actions/answer`                                                            |
| `actions/hangup`           | `actions/hangup`                                                            |
| `actions/bridge`           | `actions/bridge`                                                            |
| `actions/hold` / `unhold`  | `actions/hold` / `actions/unhold` — **silent hold**, see above              |
| `actions/send_dtmf`        | `actions/dtmf` — relayed via a connected browser leg                        |
| `actions/transfer`         | `actions/transfer` with `mode: 'blind' \| 'warm'`                           |
| Webhook event stream       | Workspace webhooks (one-shot) + `GET /v1/voice/calls/{id}/events` (durable) |
| SIP credential / registrar | **None** — human legs are browser legs                                      |

Deliberate gaps, so you can plan around them rather than discover them:

* **No SIP registrar.** Desk phones, third-party softphones, and PBXes cannot register and be rung. Anything terminating on a Telnyx SIP connection becomes a PSTN transfer or a browser client.
* **No hold music / playback yet.** `playback_start`-style media into a call has no equivalent; hold is silence.
* **No early media, and busy is not distinguishable** from a generic rejection — the leg fails either way, without a `486`-specific signal.
* **Answering-machine detection, recording, and call queuing** are not part of human calling yet. (AMD and recording exist for AI sessions.)

## Current limitations [#current-limitations]

* **Bring your own softphone UI.** The `@spekoai/client` package does not yet ship a human-calling surface; drive the presence and call rooms with `livekit-client` directly, as shown above. The REST API and the TypeScript SDK (`speko.callControl`) are the stable integration surface.
* The **Python SDK** exposes the webhook event types but no call-control methods yet — use the REST API from Python.
* One number routes to **one broker**; there are no ring groups or round-robin queues yet. Fan out with multiple numbers, or build hunting on top of presence + `transfer`.
* No ring timeout or voicemail fallback on inbound (see the callout above).


# Multilingual agents (/guides/multilingual-agents)

Author a greeting, a mailbox line, and workflow steps in every language one agent speaks.



Routing swaps an agent's STT, TTS, LLM and system prompt to match the caller's language. It cannot rewrite text a person wrote. A greeting, a voicemail line, and a workflow step's verbatim `say` are spoken as authored, in the language they were authored in. A correctly routed Spanish call still opens in English when English is the only greeting on file. Author that text per language instead.

## Configure the languages [#configure-the-languages]

`languageRouting.languages[]` is the agent's language table. Each entry names a language and carries the text and provider pins that language needs.

```bash
curl -X PATCH https://api.speko.dev/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "languageRouting": {
      "enabled": true,
      "languages": [
        {
          "language": "en",
          "firstMessage": "Hi, this is Alex from Iron Mike Delivery. Am I speaking with {{candidate_name}}?",
          "voicemailMessage": "Hi {{candidate_name}}, this is Alex from Iron Mike Delivery about the driver role. I will try again tomorrow."
        },
        {
          "language": "es",
          "allowedProviders": { "tts": ["elevenlabs"] },
          "voice": "QtY3JBOUKEB5xzrRfOKc",
          "firstMessage": "Hola, soy Alex de Iron Mike Delivery. Le llamo por el puesto de repartidor. ¿Hablo con {{candidate_name}}?",
          "voicemailMessage": "Hola {{candidate_name}}, soy Alex de Iron Mike Delivery. Le llamo mañana."
        }
      ]
    }
  }'
```

Up to four languages, each with a distinct primary subtag. Every text field is a Liquid template, compiled against the same variables as its agent-level counterpart. An unbound name is rejected at agent-write time with `400 MISSING_TEMPLATE_VARIABLES`, not at session create.

Each entry has four text slots, mirroring the agent-level fields:

| Wire name              | Spoken on                                                  |
| ---------------------- | ---------------------------------------------------------- |
| `firstMessage`         | Any leg with no direction-specific text                    |
| `inboundFirstMessage`  | Inbound calls                                              |
| `outboundFirstMessage` | Outbound calls                                             |
| `voicemailMessage`     | A mailbox, under `turnHandling.onMachine: 'leave_message'` |

The direction-specific greeting wins over `firstMessage`. Omit a slot to inherit the agent-level text. All three greetings accept an empty string, which is a real setting rather than a blank field: the call opens with silence and listens first. Only `voicemailMessage` rejects an empty string — a mailbox with silence recorded into it is not a policy.

## Pin one language without arming the switcher [#pin-one-language-without-arming-the-switcher]

`enabled` gates *switching* only. The `languages[]` array doubles as the text table and is read either way, so an agent with `enabled: false` still speaks the authored text for whatever language a call is pinned to.

```ts
const call = await speko.voice.dial({
  to: '+34911234567',
  agentId: 'agent_123',
  intent: { language: 'es' },
});
```

That call greets from the `es` entry and leaves the `es` mailbox message, with no mid-call detection running and no chance of a stack switch mid-sentence. Set `enabled: true` when a caller may genuinely change language during the call; leave it `false` when each call knows its language up front and you want the greeting to match.

## Translate a step that speaks [#translate-a-step-that-speaks]

A workflow step's `say` goes straight to TTS with no model in the path, so an instruction to answer in Spanish cannot reach it. Give the step a translation:

```json
{
  "id": "call_overview",
  "kind": "message",
  "say": "Let me explain how this call works: I'll tell you a little about Iron Mike Delivery.",
  "sayByLanguage": {
    "es": "Le explico cómo funciona esta llamada: le hablaré un poco de Iron Mike."
  },
  "instruction": "Confirm the candidate is still interested in the role.",
  "instructionByLanguage": {
    "es": "Confirme que el candidato sigue interesado en el puesto."
  }
}
```

Keys are bare primary subtags, so one `es` entry serves an `es-419` session. Each field takes up to four variants; `say` variants cap at 600 characters and `instruction` variants at 2000. Variant selection happens before variable substitution, so a translated line still renders its `{{variables}}`.

Author these rather than translating at runtime. `say` holds the text that has to be exact: disclosures, consent language, prices. A machine translation of it reintroduces the drift `say` exists to prevent, in a language nobody on your team is reading back.

## Language directives [#language-directives]

Each routed language also gets a short "respond only in this language" line appended to its system prompt. That line is what stops the model answering in the prompt's own language once the stack has switched. It resolves for all 44 supported agent languages as of `v0.0.505`.

Earlier releases resolved it from a 24-entry table, so 23 languages got no directive at all. Swedish, Danish, Polish, Turkish, Hebrew, Ukrainian, Greek, Czech, Hungarian, Romanian, Slovak, Croatian, Bulgarian, Finnish and the Indic set were all in that gap. Nothing to configure: existing agents pick the directive up on their next call.

## Next [#next]

<CardGroup cols="2">
  <Card title="Workflows" icon="git-branch" href="/concepts/workflows">
    Steps, slots, and the global edges that interrupt them.
  </Card>

  <Card title="Phone agents" icon="phone" href="/guides/phone-agents">
    Voicemail policy, answering-machine detection, and call reports.
  </Card>
</CardGroup>


# Narration (/guides/narration)

POST /v1/synthesize with workload=narration: long-form TTS, voice settings, sample rate, chunking.



Server-side TTS tuned for reading prose aloud - audiobooks, articles, video voiceover. Set `workload: "narration"` in the `/v1/synthesize` body:

```bash
curl -X POST https://api.speko.dev/v1/synthesize \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Chapter one. The harbor was quiet that morning, and the first ferry moved slowly through the mist.",
    "intent": { "language": "en" },
    "workload": "narration"
  }' \
  --output chapter-1.pcm
```

What `workload: "narration"` does:

* Applies narration defaults from the param registry where the winning provider has them - for ElevenLabs, `voice_settings: { stability: 0.5, similarity_boost: 0.75, use_speaker_boost: true }`. Your explicit values always override defaults.
* Prefers a 24 kHz output ladder when you set no `sampleRate` and at least one candidate serves that rate. An explicit `sampleRate` remains the hard contract.
* Reports the applied param names in the `X-Speko-Applied-Params` response header; dropped params and validation warnings arrive in `X-Speko-Warnings`.

## Voice settings [#voice-settings]

Per-provider generation knobs go in `providerOptions`. They are validated up front and apply only when that provider serves the request - on failover to another provider they never cross:

```json
{
  "text": "...",
  "intent": { "language": "en" },
  "workload": "narration",
  "providerOptions": {
    "elevenlabs": {
      "voice_settings": {
        "stability": 0.65,
        "similarity_boost": 0.8,
        "style": 0.2,
        "use_speaker_boost": true
      }
    }
  }
}
```

| Provider   | Param                      | Type    | Values                                                                                          | Effect                                                 |
| ---------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| ElevenLabs | `voice_settings`           | object  | `stability` 0-1, `similarity_boost` 0-1, `style` 0-1, `use_speaker_boost` bool, `speed` 0.7-1.2 | Overrides the voice's per-request generation settings. |
| ElevenLabs | `apply_text_normalization` | enum    | `auto`, `on`, `off`                                                                             | Controls provider-side text normalization.             |
| MiniMax    | `volume`                   | number  | 0.5-2                                                                                           | Output volume multiplier.                              |
| MiniMax    | `pitch`                    | integer | -12 to 12                                                                                       | Shifts pitch by semitones.                             |
| Cartesia   | `speed`                    | number  | 0.6-1.5                                                                                         | Speaking-rate multiplier.                              |
| Cartesia   | `volume`                   | number  | 0.5-2                                                                                           | Output volume multiplier.                              |
| Fish Audio | `latency`                  | enum    | `normal`, `low`                                                                                 | Normal quality or low-latency generation.              |
| Bland      | `expressiveness`           | number  | 0-1                                                                                             | Expressive variation.                                  |
| Bland      | `stability`                | number  | 0-1                                                                                             | Consistency in generated speech.                       |

Setting both the top-level `speed` and a provider speed spelling (`voice_settings.speed`, Cartesia `speed`) is rejected as `canonical_collision` - set one. Full registry and validation rules: [Provider params](/concepts/provider-params).

Pick a voice explicitly with `voice` (browse via `GET /v1/voices`) and pin the provider via `constraints.allowedProviders.tts` when a long run must stay on one voice.

## Long-form text [#long-form-text]

* The endpoint caps `text` at 50,000 characters per call.
* Upstream providers enforce their own per-request character limits below that cap, and very long inputs raise time-to-first-audio; the gateway fails a candidate over if it produces no audio within 10 seconds.
* Server-side chunking of long scripts into one stitched audio stream is a follow-up. Today, chunk the script yourself (paragraph boundaries work well) and call `/v1/synthesize` per chunk. Set an explicit `sampleRate` so every chunk - including any failover - returns the same rate, then concatenate the PCM.


# One-shot APIs (/guides/one-shot)

POST /v1/transcribe, /v1/synthesize, /v1/complete — single-turn calls without sessions.



For batch transcription, server-side TTS, and non-voice LLM completions you don't need a real-time session — just call the one-shot endpoints directly. Each is a single round-trip with built-in routing and failover.

## Auth [#auth]

Every one-shot call needs a bearer API key. Mint one at [API keys](https://platform.speko.ai/agents/keys).

```http
Authorization: Bearer sk_live_...
```

## Transcribe [#transcribe]

```bash
curl -X POST https://api.speko.dev/v1/transcribe \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: audio/wav" \
  -H "x-speko-intent: {\"language\":\"en-US\"}" \
  --data-binary @call.wav
```

Response:

```json
{
  "text": "...",
  "provider": "deepgram",
  "model": "nova-2",
  "confidence": 0.94,
  "failoverCount": 0,
  "scoresRunId": "..."
}
```

Notes:

* Audio body is binary. Wrap PCM/MP3/WAV/etc. in the request body — no base64.
* Intent goes in the `x-speko-intent` header (JSON), not the body. Constraints in `x-speko-constraints`.

## Synthesize [#synthesize]

```bash
curl -X POST https://api.speko.dev/v1/synthesize \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world.",
    "intent": { "language": "en-US" },
    "voice": null,
    "speed": 1
  }' \
  --output speech.bin
```

Response body is the audio. Content-Type indicates the format (e.g. `audio/pcm;rate=24000` for Cartesia, `audio/mpeg` for ElevenLabs). Routing headers (`X-Speko-Provider`, etc.) tell you which provider ran.

## Complete [#complete]

```bash
curl -X POST https://api.speko.dev/v1/complete \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are concise." },
      { "role": "user", "content": "Hi!" }
    ],
    "intent": { "language": "en" }
  }'
```

Response:

```json
{
  "text": "Hello!",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "usage": { "promptTokens": 14, "completionTokens": 4 },
  "failoverCount": 0,
  "scoresRunId": "..."
}
```

## With an SDK [#with-an-sdk]

Both SDKs wrap all three endpoints with matching shapes. See [`@spekoai/sdk`](/sdk/overview) and [`spekoai` (Python)](/sdk-python/overview).

<CodeGroup>
  ```ts TypeScript
  import { Speko } from '@spekoai/sdk';

  const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });

  const t = await speko.transcribe(buf, { language: 'en-US' });
  const a = await speko.synthesize('Hello', { language: 'en' });
  const c = await speko.complete({
    messages: [{ role: 'user', content: 'Hi!' }],
    intent: { language: 'en' },
  });
  ```

  ```python Python
  from spekoai import Speko

  speko = Speko(api_key=os.environ["SPEKO_API_KEY"])

  t = speko.transcribe(buf, language="en-US")
  a = speko.synthesize("Hello", language="en")
  c = speko.complete(
      messages=[{"role": "user", "content": "Hi!"}],
      intent={"language": "en"},
  )
  ```
</CodeGroup>

## When not to use one-shot [#when-not-to-use-one-shot]

If you need real-time voice with sub-second latency, barge-in, and partial transcripts — use [sessions](/concepts/sessions). One-shot endpoints are for batch and server-internal flows.


# Build a phone agent (/guides/phone-agents)

Inbound and outbound PSTN calls, phone-number routing, lifecycle webhooks, reports, and transfers.



Speko can run the same voice agent over browser sessions and PSTN calls. Phone calls use the platform-hosted LiveKit SIP path: Speko creates or receives the call leg, dispatches the agent worker, records the room, persists transcripts and events, and finalizes a call report after hangup.

Use this guide when you want a receptionist, appointment setter, callback workflow, or support line that can place calls, answer calls, and transfer callers to a human.

## Phone surfaces [#phone-surfaces]

| Need                         | API                                                       | SDK                                                          |
| ---------------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| Place an outbound phone call | `POST /v1/sessions/phone`                                 | `speko.voice.dial()`                                         |
| Buy or import numbers        | `/v1/phone-numbers/*`                                     | `speko.phoneNumbers`                                         |
| Route inbound calls          | `agentId` or `dispatchMetadataTemplate` on a phone number | `speko.phoneNumbers.update()`                                |
| Inspect calls and reports    | `/v1/calls/{id}`                                          | `speko.calls.get()`                                          |
| Read lifecycle events        | `/v1/calls/{id}/events`                                   | `speko.calls.events()`                                       |
| Transfer live calls          | `/v1/calls/{id}/transfers/*`                              | `speko.calls.blindTransfer()` / `speko.calls.warmTransfer()` |

## 1. Create an agent [#1-create-an-agent]

Phone calls work best with a persisted agent because the phone-number row can hydrate its prompt, routing intent, provider preferences, speech settings, and tools every time a call starts. Lifecycle webhooks are configured once at the workspace level and scoped to this agent when needed.

```bash
curl -X POST https://api.speko.dev/v1/agents \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Front desk",
    "systemPrompt": "You are the front-desk receptionist. Greet callers, collect their name and reason for calling, answer common questions, and transfer urgent calls.",
    "intent": { "language": "en-US", "optimizeFor": "latency" }
  }'
```

Create lifecycle endpoints in **Settings → Webhooks** or through `speko.webhooks`. See [Workspace webhooks](/docs/guides/webhooks) for event selection, agent scopes, tagged routing, signing, retries, and logs. Agent-level `webhooks` fields are deprecated compatibility fields through the current SDK major version.

## 2. Add a phone number [#2-add-a-phone-number]

You can use a platform-managed number or register a customer-owned SIP trunk number.

Managed number search and purchase is currently the US-number path. It requires phone-number business verification and sufficient credits:

```ts
const options = await speko.phoneNumbers.searchAvailable({ areaCode: '415' });

const number = await speko.phoneNumbers.create({
  e164: options[0]!.e164,
  direction: 'both',
  agentId: 'agent_123',
  label: 'Main line',
});
```

For numbers you already own, import the SIP trunk instead:

```ts
await speko.phoneNumbers.importSipTrunk({
  e164: '+442071234567',
  sipConnectionInstallationId: '00000000-0000-4000-8000-000000000010',
  direction: 'both',
  agentId: 'agent_123',
  label: 'London front desk',
});
```

`direction` controls whether the number can be used for inbound calls, outbound calls, or both. Inbound calls require either an `agentId` or a `dispatchMetadataTemplate`.

## 3. Place outbound calls [#3-place-outbound-calls]

Use `POST /v1/sessions/phone` or `speko.voice.dial()` for outbound PSTN calls. The response returns the Speko session id, room name, resolved caller ID, and SIP participant handle.

```ts
const call = await speko.voice.dial({
  to: '+12015551234',
  from: '+12015550199',
  agentId: 'agent_123',
  firstMessage: 'Hi, this is Ava from Acme. Is now still a good time?',
  telephony: {
    region: 'us-east',
    amd: { mode: 'agent', timeoutSeconds: 8 },
  },
  webhookTags: {
    environment: 'production',
  },
  metadata: {
    campaignId: 'renewal-q2',
    leadId: 'lead_456',
  },
});

console.log(call.sessionId, call.status);
```

`agentId` is required unless you pass an ad hoc `intent`. Per-call fields such as `systemPrompt`, `firstMessage`, `voice`, `llm`, `ttsOptions`, `sttOptions`, `constraints`, and `metadata` override or extend the agent defaults for that call.

### Voicemail handling [#voicemail-handling]

Outbound calls use native answering-machine detection by default. With `greetFirst: true` (the default), detection runs while the agent can speak; `greetFirst: false` briefly holds the opening for a verdict. `telephony.amd.mode: 'disabled'` disables native detection and transcript-based machine cues. `mode: 'carrier'` also disables native detection and requires carrier/trunk support; setting that mode alone does not supply carrier verdicts to the worker. A voicemail policy does not enable detection when it is disabled or carrier-managed.

When native detection identifies **recordable voicemail**, `turnHandling.onMachine` controls the response. Set it on the agent to inherit it across calls, or override individual fields per call. For example, passing only `{ profile: 'ivr' }` preserves the agent's `onMachine` and `voicemailMessage` settings:

```ts
const call = await speko.voice.dial({
  to: '+12015551234',
  agentId: 'agent_123',
  turnHandling: {
    onMachine: 'leave_message',
    voicemailMessage:
      "Hi, this is Ava from Acme about your renewal. I'll try again tomorrow, or call us back at 201-555-0199.",
  },
});
```

| `onMachine`               | What the agent does                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_decides` (default) | The verdict is handed to the model as a system note ("this is a voicemail greeting"). Your prompt's own rules apply — for example "on voicemail, call `end_call` immediately".                                                                                                                                                                                                                                                    |
| `hangup`                  | Ends the answered call when voicemail is detected, without a farewell or voicemail message. An opening may already have played with `greetFirst: true`.                                                                                                                                                                                                                                                                           |
| `leave_message`           | Waits for a 1.5-second quiet window, then speaks `voicemailMessage` once in the agent's voice and hangs up after playout. `voicemailMessage` renders the same `{{variables}}` as `firstMessage`, and can be authored per language — see [Multilingual agents](/guides/multilingual-agents). If the greeting stays active for 20 seconds, it ends without speaking the message. Quiet detection is a fallback, not beep detection. |

An **unavailable mailbox** (for example, full or not set up) always ends without attempting a message, regardless of `onMachine`. It is recorded as `endReason: "machine_unavailable"` with report outcome `unavailable`.

IVR and call-screening detections continue through the navigation flow. In IVR mode the agent can follow spoken prompts and send keypad digits. Machine silence after exhausted prompts and a separate 120-second machine-phase budget bound calls that make no progress. IVR timeouts are not reported as voicemail.

Calls ended by a voicemail policy use `endReason: "voicemail_reached"` and report outcome `voicemail`. This means a mailbox was reached, not that a message was saved: `worker.voicemail_delivery` separately records local playout success or failure, a greeting timeout, or a missing message.

## 4. Receive inbound calls [#4-receive-inbound-calls]

When a call arrives on a registered number, Speko matches the dialed E.164 number, checks `direction`, creates a voice session, hydrates the linked agent, dispatches the worker, and bridges the caller into the LiveKit room.

For forwarded calls, Speko attempts to preserve the original forwarding source. It looks at Telnyx payload fields such as `forwarded_from`, `original_to`, and `redirecting_number`, plus SIP headers such as `Diversion` and `History-Info`. The normalized value is exposed as:

* `forwardedFromNumber` in session metadata.
* `forwarded_from_number` in pre-call webhook payloads.
* call events and reports through the session metadata.

Use `dispatchMetadataTemplate` when you need static metadata or a legacy template alongside the linked agent:

```ts
await speko.phoneNumbers.update('pn_123', {
  agentId: 'agent_123',
  dispatchMetadataTemplate: {
    tenant: 'acme',
    line: 'front_desk',
    caller: '{{callerNumber}}',
    dialedNumber: '{{dialedNumber}}',
    forwardedFromNumber: '{{forwardedFromNumber}}',
  },
});
```

The agent fields are canonical. If `agentId` and `dispatchMetadataTemplate` set the same pipeline key, the persisted agent wins and the template fills the gaps.

Template keys split by name: keys from the pipeline vocabulary (`systemPrompt`, `firstMessage`, `voice`, `intent`, and the other agent-level fields) hydrate the call's pipeline config, while every other key (like `tenant` or `line` above) is static metadata — it surfaces on the session's `metadata`, in call events and reports, and in webhook payloads, but never changes call routing. A handful of server-internal key names (`native`, `proxy`, `tools`, `stages`, and similar) are reserved and rejected when you save the template.

## 5. Customize calls before answer [#5-customize-calls-before-answer]

Configure a workspace endpoint subscribed to `call.pre_call` and scoped to the agent when your application needs to look up the caller, choose a greeting, inject account context, or override the call pipeline before the worker starts speaking. Only one effective pre-call endpoint may match an agent/tag route.

Speko sends:

```json
{
  "type": "call.pre_call",
  "call_id": "session_123",
  "session_id": "session_123",
  "organization_id": "org_123",
  "direction": "inbound",
  "to": "+12015550199",
  "from": "+12015551234",
  "dialed_number": "+12015550199",
  "forwarded_from_number": null,
  "phone_number_id": "pn_123",
  "call_control_id": "sip_participant_123",
  "pipeline_config": {},
  "metadata": {}
}
```

Return any supported pipeline overrides at the top level or under `pipelineConfig` / `pipeline_config`:

```json
{
  "firstMessage": "Hi Maya, thanks for calling Acme.",
  "systemPrompt": "The caller is Maya Chen, a priority customer. Keep responses brief.",
  "metadata": {
    "customerId": "cus_123",
    "plan": "enterprise"
  }
}
```

Supported pre-call override keys include `intent`, `constraints`, `voice`, `systemPrompt`, `firstMessage`, `llm`, `ttsOptions`, `sttOptions`, `backgroundAudio`, `tools`, pronunciation and text replacement rules, and idle reprompts.

The response may also carry a top-level `toolSecrets` object — per-call values for **tools only** (a short-lived access token scoped to the caller you just looked up, a tenant API base URL). Unlike `variables`, these never enter the prompt, the transcript, or the worker's dispatch metadata; they are stored encrypted and released only to tool execution (`session.secrets.<name>` in custom-code tools, `{{name}}` in webhook tool `url`/`headers`). Same limits and semantics as the `toolSecrets` request field on `/v1/sessions` — see [Per-call secrets](/docs/guides/tool-calling#per-call-secrets-and-urls-toolsecrets). On outbound calls, values sent on the dial request win over the webhook's on a name collision. An invalid `toolSecrets` object is dropped with a warning (names logged, never values) and the call proceeds.

```json
{
  "firstMessage": "Hi Priya, thanks for calling back.",
  "variables": { "customer_name": "Priya" },
  "toolSecrets": { "access_token": "eyJhbGciOi...", "base_url": "https://acme.example.com" }
}
```

## 6. Track lifecycle and reports [#6-track-lifecycle-and-reports]

Speko records durable lifecycle events for LiveKit, Telnyx, Speko status updates, SIP cause codes, and transfer attempts.

```ts
const call = await speko.calls.get('session_123');
const { events } = await speko.calls.events('session_123');
const report = await speko.calls.report('session_123');
```

Endpoints subscribed to `call.status` receive call progress and failure information:

```json
{
  "type": "call.status",
  "call_id": "session_123",
  "event_type": "call.hangup",
  "provider": "telnyx",
  "status": "ended",
  "failure_cause": null,
  "sip_status_code": 200,
  "sip_status": "OK",
  "metadata": {}
}
```

After hangup, Speko finalizes a report with transcript entries, summary, outcome, structured data, cost breakdown, artifacts, metadata, and any scheduled callback created by analysis. Endpoints subscribed to `call.report` receive the same report payload. Report, analysis, and recording deliveries retry independently; inspect or manually redeliver them through `speko.webhooks.deliveries`.

### Recording link [#recording-link]

`recording_url` is a **presigned download URL** you can fetch directly with no auth headers (a `GET` on the URL streams the audio). It's a signed link valid for up to 7 days from delivery, so download or copy the file to your own storage rather than persisting the URL long-term. To fetch a recording on demand later, call the authenticated `GET /v1/calls/{id}/recording` endpoint with your API key instead.

A recording usually finishes uploading *after* the call ends, so the first `call.report` delivery often arrives with `recording_url: null` (and `artifacts.recording.status: "uploading"`). Once the recording finalizes, Speko &#x2A;*re-fires `call.report`** for the same `call_id` with `recording_url` populated and `artifacts.recording.status: "ready"`. Deduplicate on `call_id` and treat the later delivery as authoritative for the recording. `recording_url` stays `null` when recording is disabled for the org (`artifacts.recording.status: "suppressed"`), when the upload failed, or when the dial never connected (`artifacts.recording.status: "discarded"` — a refused or unanswered outbound leg captures only an empty room, so no recording is served).

### Dedicated analysis and recording webhooks [#dedicated-analysis-and-recording-webhooks]

If handling the `call.report` re-fire is awkward for your consumer (for example, your handler dedupes on `call_id` and drops the delivery that carries the recording), subscribe to the dedicated single-purpose webhooks instead. Each fires **once** per call — and unlike the `call.report` re-fire, any webhook-standard duplicate (e.g. a redelivery after a timeout) carries identical content, so deduplicating on `type` + `call_id` never loses data:

* **`call.analysis`** fires when the LLM analysis completes: `summary`, `outcome`, `structured_data`, `custom_data`, and an `analysis` object (`status`, `provider`, `model`, `completed_at`). No transcript, cost, or recording — and no recording re-fire to dedupe.
* **`call.recording`** fires when the recording reaches a terminal state. `recording_url` carries the presigned link (same 7-day-TTL semantics as above) when `recording.status` is `"ready"`, and `null` when it's `"failed"` — so your consumer can stop waiting either way. Suppressed recordings (recording disabled for the org) never fire this event.

```json
{
  "type": "call.recording",
  "call_id": "b2f7…",
  "session_id": "b2f7…",
  "organization_id": "org_…",
  "agent_id": "agent_…",
  "recording_url": "https://storage.googleapis.com/…",
  "recording": { "status": "ready", "duration_ms": 21625 },
  "created_at": "2026-07-09T15:15:19.131Z"
}
```

Subscribe one endpoint to any combination of these events:

```ts
await speko.webhooks.create({
  name: 'Call processing',
  url: 'https://example.com/speko/calls',
  events: ['call.report', 'call.analysis', 'call.recording'],
  allAgents: true,
});
```

Both events are fully additive: `call.report` keeps its combined payload and its recording re-fire, so existing `postCall` consumers are unaffected. Failed deliveries retry with the same backoff as `call.report`.

### Custom data extraction [#custom-data-extraction]

Add `extractionFields` to a workspace endpoint subscribed to `call.report` or `call.analysis` to have Speko pull structured values out of every call. Each field has a `name`, a `type` (`string`, `number`, `boolean`, or `enum`), and a `description` that tells the analysis model what to extract — `enum` fields also take an `options` list. After the call, the model fills each field from the transcript, coerced to its declared type (or `null` when the call gives no basis for it), and the values arrive as a top-level `custom_data` object keyed by field name:

```json
{
  "type": "call.report",
  "summary": "Jane booked a table for four.",
  "outcome": "scheduled",
  "structured_data": { "...": "..." },
  "custom_data": {
    "caller_intent": "booking",
    "party_size": 4,
    "wants_callback": true
  }
}
```

`custom_data` always carries one key per configured field, so the payload schema stays stable. Manage these fields from **Settings → Webhooks** in the dashboard.

Limits: up to 30 fields per webhook, each `description` up to 10,000 characters, with at most 40,000 characters of descriptions combined across all fields. Detailed rubric-style descriptions are encouraged for classification fields — the analysis model follows them closely.

## 7. Transfer callers [#7-transfer-callers]

Use the Calls API for operator-driven transfers, or add the built-in `transfer_call` tool to let the agent transfer based on conversation context.

```ts
await speko.calls.blindTransfer('session_123', {
  to: '+12015554321',
  ringingTimeout: 25,
  metadata: { reason: 'billing escalation' },
});

const transfer = await speko.calls.warmTransfer('session_123', {
  from: '+12015550199',
  destinations: [
    { to: '+12015551234', label: 'Front desk' },
    { to: '+12015554321', label: 'Overflow' },
  ],
  screeningPrompt: 'Confirm the recipient can help before bridging.',
  fallback: { strategy: 'take_message' },
  voicemailDetection: { mode: 'agent', timeoutSeconds: 10 },
});
```

Warm transfer starts a consultation leg first. Complete the transfer when the screened recipient accepts, or cancel with `tryNext: true` to continue through the destination list.

## Next [#next]

<CardGroup cols="2">
  <Card title="Phone number SDK" icon="phone" href="/sdk/phone-numbers">
    Provision, import, update, and release phone numbers.
  </Card>

  <Card title="Calls SDK" icon="messages-square" href="/sdk/calls">
    Inspect reports, events, recordings, and live transfers.
  </Card>

  <Card title="Outbound voice SDK" icon="phone-call" href="/sdk/voice">
    Place outbound phone calls from TypeScript.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/sessions-phone">
    Full request and response schemas for phone calls.
  </Card>
</CardGroup>


# Provider-direct speech-to-speech (/guides/realtime-conversation)

Mint a short-lived OpenAI, Gemini Live, or xAI session and connect the browser directly to the provider.



Provider-direct speech-to-speech (S2S) keeps Speko in the control and billing path without putting Speko in the media path:

1. Your backend calls `POST /v1/sessions` with `mode: 's2s'` and its Speko API key.
2. Speko reserves a bounded entitlement and returns a scoped, short-lived provider credential.
3. The browser connects directly to OpenAI Realtime, Gemini Live, or xAI Grok Voice.
4. Speko stores content-free lifecycle and billing evidence. Audio never traverses a Speko media proxy or LiveKit room.

Use this path for the lowest possible browser-to-model latency. If you need Speko's routed STT → LLM → TTS pipeline, recordings, or server-persisted transcripts, use a [`VoiceConversation` cascade session](/client/voice-conversation) instead.

## Install [#install]

```bash
npm install @spekoai/client
```

## 1. Mint an S2S session on your backend [#1-mint-an-s2s-session-on-your-backend]

Keep `SPEKO_API_KEY` on your server. Return the S2S response to the browser unchanged; it contains a scoped provider credential and Speko control URLs, never a provider root key.

```ts server.ts
import crypto from 'node:crypto';

app.post('/api/realtime-session', async (req, res) => {
  const idempotencyKey = req.get('Idempotency-Key') || crypto.randomUUID();
  const response = await fetch('https://api.speko.dev/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      mode: 's2s',
      s2s: {
        provider: 'google',
        model: 'gemini-3.1-flash-live-preview',
        voice: 'Puck',
        systemPrompt: 'You are a concise voice assistant.',
      },
      ttlSeconds: 900,
    }),
  });

  const body = await response.json();
  res.status(response.status).json(body);
});
```

`Idempotency-Key` is required for S2S. Reuse the same value only when retrying an ambiguous bootstrap timeout; Speko will return the same reservation instead of minting a second one.

## 2. Connect directly from the browser [#2-connect-directly-from-the-browser]

```tsx RealtimePanel.tsx
import { useEffect, useRef, useState } from 'react';
import { RealtimeVoiceConversation } from '@spekoai/client';

export function RealtimePanel() {
  const conversationRef = useRef<RealtimeVoiceConversation | null>(null);
  const [status, setStatus] = useState('idle');
  const [transcript, setTranscript] = useState<string[]>([]);

  async function start() {
    setStatus('connecting');
    const response = await fetch('/api/realtime-session', { method: 'POST' });
    if (!response.ok) throw new Error('Could not create an S2S session');
    const session = await response.json();

    const conversation = await RealtimeVoiceConversation.create({
      ...session,
      onStatusChange: setStatus,
      onMessage: ({ source, text, isFinal }) => {
        if (isFinal) setTranscript((items) => [...items, `${source}: ${text}`]);
      },
      onError: (error) => console.error(error),
      onDisconnect: () => setStatus('idle'),
    });

    conversationRef.current = conversation;
  }

  async function stop() {
    await conversationRef.current?.endSession();
    conversationRef.current = null;
  }

  useEffect(() => () => { void conversationRef.current?.endSession(); }, []);

  return (
    <div>
      <button onClick={start} disabled={status !== 'idle'}>Start</button>
      <button onClick={stop} disabled={status === 'idle'}>Stop</button>
      <p>Status: {status}</p>
      <ul>{transcript.map((item, index) => <li key={index}>{item}</li>)}</ul>
    </div>
  );
}
```

`RealtimeVoiceConversation` acquires the microphone, performs the provider handshake, plays response audio, normalizes transcript events, reports content-free telemetry, and tears down every media resource in `endSession()`.

## Providers and defaults [#providers-and-defaults]

| Provider | Default model                   | Default voice | Direct transport      | PCM input / output |
| -------- | ------------------------------- | ------------- | --------------------- | ------------------ |
| OpenAI   | `gpt-realtime-2.1`              | `marin`       | WebRTC                | 24 kHz / 24 kHz    |
| Google   | `gemini-3.1-flash-live-preview` | `Puck`        | Gemini Live WebSocket | 16 kHz / 24 kHz    |
| xAI      | `grok-voice-latest`             | `eve`         | Grok Voice WebSocket  | 24 kHz / 24 kHz    |

You may omit `s2s.provider` and `s2s.model` to let Speko choose an eligible S2S route. If you set one, set both. Use `constraints.allowedProviders.s2s` to limit routing to provider names or exact `provider:model` pairs.

## Duration and billing [#duration-and-billing]

For S2S, `ttlSeconds` is the requested maximum session horizon, not a LiveKit join-token TTL. The API defaults to 1,800 seconds and accepts up to 3,600 seconds. Provider credential limits can make the first authorized slice shorter:

* OpenAI uses a provider-authenticated sideband to bind the WebRTC call, collect provider events, and enforce the authorized deadline without receiving media.
* Gemini Live uses renewable entitlement slices. `RealtimeVoiceConversation` reserves the next slice and resumes the Gemini session automatically while it remains inside the requested horizon.
* Browser telemetry is operational evidence and may update the dashboard estimate, but it is not trusted to reduce the final charge. When exact provider-side evidence is unavailable, Speko settles the bounded entitlement that was authorized before the credential was minted.

The create response reports `reservation.authorizedDurationSeconds`, `reservation.billing.maximumAmountMicros`, and any `reservation.billing.renewalUrl`. Treat those returned values—not only the requested `ttlSeconds`—as the active authorization.

## Current artifact behavior [#current-artifact-behavior]

* S2S transcript callbacks are available in the browser, but Speko does not yet persist them to `GET /v1/sessions/{id}/transcript`.
* Speko does not record provider-direct S2S media. `recordingStatus` is `null`, and the recording endpoint has no artifact for these sessions.
* `endSession()` closes the direct provider connection locally. The provider credential and server-side entitlement remain bounded even if a modified client omits the final telemetry event.

## Next [#next]

<CardGroup cols="2">
  <Card title="Realtime client API" icon="waveform" href="/client/realtime-voice-conversation">
    Browser callbacks, device controls, and transport behavior.
  </Card>

  <Card title="Sessions concept" icon="route" href="/concepts/sessions">
    Compare provider-direct S2S, cascade, phone, and one-shot flows.
  </Card>
</CardGroup>


# Tool calling (/guides/tool-calling)

Give a Speko voice agent the ability to invoke webhook tools mid-call. Register once in the dashboard, fire from any voice session.



Tool calling lets the LLM driving your voice session take action: query a database, schedule a visit, transfer to a human. The model decides when to invoke a tool from your prompt; Speko POSTs a [Standard Webhooks](https://www.standardwebhooks.com)-signed request to your endpoint, folds the JSON response back into the model's next turn, and the agent verbalizes the result.

This guide walks through registering a tool, hooking it into a Speko voice session, and confirming it fires.

## Architecture [#architecture]

```
Voice session                 Speko proxy                  Your endpoint
─────────────                 ───────────                  ─────────────
LLM emits tool call    ─→   /v1/complete loop      ─→     POST /your/webhook
                                                          (signed body)
LLM verbalizes result  ←─   response folded back   ←─     200 + JSON
```

Three pieces meet:

1. **Your endpoint** — a public HTTPS URL that receives the tool call and returns JSON.
2. **The Speko dashboard** — where you register the tool (name, description, JSON Schema parameters, your endpoint URL). Speko stores an HMAC signing secret you save once.
3. **A Speko voice session** — the worker fetches your registered tools at session start, exposes them to the LLM, and routes invocations through the executor.

## 1. Build your endpoint [#1-build-your-endpoint]

The executor POSTs an envelope with the LLM-generated arguments nested under `args`. Read them from there, not from the body root — see [what gets sent over the wire](#what-gets-sent-over-the-wire). Whatever you return becomes the model's next observation, so keep responses small and specific.

```ts src/server.ts
import { Hono } from 'hono';

const PETS: Record<string, unknown> = {
  luna: { name: 'Luna', species: 'corgi', age: 3, status: 'available' },
  max: { name: 'Max', species: 'tabby cat', age: 5, status: 'available' },
};

const app = new Hono();

app.post('/lookup', async (c) => {
  const { args } = (await c.req.json()) as { args?: { name?: string } };
  const name = args?.name;
  const pet =
    PETS[
      String(name ?? '')
        .toLowerCase()
        .trim()
    ];
  if (!pet) return c.json({ error: 'Pet not found' }, 404);
  return c.json(pet);
});

export default { port: Number(process.env.PORT ?? 8080), fetch: app.fetch };
```

Deploy this anywhere with a public HTTPS URL — Cloud Run, Fly.io, Render, Vercel functions.

### Verifying the signature [#verifying-the-signature]

Production endpoints MUST verify the [Standard Webhooks](https://www.standardwebhooks.com) signature on every request. Speko sends three headers:

| Header              | Meaning                                                                                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webhook-id`        | Idempotency key for this delivery. Skip duplicates.                                                                                                                       |
| `webhook-timestamp` | Unix seconds when Speko signed the body. Reject anything older than \~5 minutes to prevent replay.                                                                        |
| `webhook-signature` | `v1,<base64(HMAC-SHA256("{webhook-id}.{webhook-timestamp}.{body}", secret))>`. Multiple comma-separated signatures may appear during rotation; accept if any one matches. |

Use the [`standardwebhooks`](https://www.npmjs.com/package/standardwebhooks) package — constant-time comparison and clock-skew tolerance are tricky to roll yourself.

<Warning>
  **Secrets issued before 2026-07-28 need `{ format: 'raw' }`.** Those secrets were
  minted with the base64url alphabet, and the package's strict base64 decoder throws
  `Base64Coder: incorrect characters for decoding` on the `-` and `_` they contain —
  at construction, before any request is examined. If your signing secret contains
  `-` or `_`, either rotate it from **API keys → Organization credentials** to get a
  current-format one, or construct the verifier as
  `new Webhook(secret, { format: 'raw' })`. Secrets issued after that date, and any
  custom `signingSecret` you supply that is not `whsec_` + standard base64, behave
  the same way. Speko signs every request under both key derivations, so whichever
  form you use will match.
</Warning>

```ts
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.LOOKUP_PET_SIGNING_SECRET!);
app.post('/lookup', async (c) => {
  const raw = await c.req.text();
  try {
    wh.verify(raw, Object.fromEntries(c.req.raw.headers));
  } catch {
    return c.text('signature mismatch', 401);
  }
  const { args } = JSON.parse(raw) as { args?: { name?: string } };
  // …
});
```

## 2. Register the tool [#2-register-the-tool]

### Via the dashboard [#via-the-dashboard]

Open [Tools](https://platform.speko.ai/agents/tools) in the dashboard, click **Add tool**, fill in:

* **Name** — `snake_case`, ≤ 64 chars (e.g. `lookup_pet`). The model sees this; pick something it'll match against the user's intent.

* **Description** — tell the model *when* to call this. Be explicit ("ALWAYS call this when the user asks about a specific pet by name").

* **Parameters** — a JSON Schema. Strict typing works; vague typing leads to the model passing garbage args.

* **Webhook URL** — your public HTTPS endpoint from step 1. Speko rejects HTTP, private/loopback hosts, and known cloud-metadata IPs at registration time.

* **Signing secret** — leave it blank and Speko generates one (shown **once** on create — copy it into your secrets manager), or supply your own to pre-configure verification on your side. You can rotate it any time from the tool's edit page by entering a new value; the existing secret is never displayed again.

* **Auth headers** — credentials Speko must send *to* your endpoint (see [Authenticating to your endpoint](#authenticating-to-your-endpoint)).

### Via the API [#via-the-api]

```bash
curl -X POST "https://api.speko.dev/v1/agents/$SPEKO_AGENT_ID/tools" \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "lookup_pet",
    "description": "Look up a pet by name. ALWAYS call this when the user asks about a specific pet.",
    "parameters": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": { "type": "string", "description": "First name of the pet." }
      }
    },
    "source": {
      "kind": "webhook",
      "url": "https://your-endpoint.example.com/lookup",
      "secret": "<32-char hex you supply — Speko stores it encrypted>"
    }
  }'
```

The `secret` you POST is what Speko uses to sign webhook deliveries. The server stores an encrypted copy and never echoes it back, so keep your local copy. Omit `secret` on a `PATCH` to keep the existing one; supply a new value to rotate it.

### Timeouts [#timeouts]

The optional `timeoutMs` on a webhook source accepts 100-4000 and defaults to 4000. The executor clamps every webhook read to 4000ms regardless of the value sent — a live call cannot wait longer on a tool. `builtin` tools run on the same 4000ms budget; `integration` actions get 8000ms. If your endpoint cannot answer inside the budget, return a small "still working" payload quickly and let the model call the tool again, or use an async webhook (below) when the caller does not need the result.

### Authenticating to your endpoint [#authenticating-to-your-endpoint]

The signing secret lets *your* endpoint verify that a request genuinely came from Speko. To go the other way — so Speko can authenticate *to* an endpoint that requires its own credential (a Bearer token, an `X-Api-Key`, …) — attach **auth headers**. Each value is encrypted at rest in Speko's secrets store and injected on every delivery; it never lives on the tool definition and the API never returns it.

In the dashboard, open the webhook tool's auth section and add a header name and its secret value. Via the API, pass `authHeaders`:

```bash
curl -X PATCH "https://api.speko.dev/v1/agents/$SPEKO_AGENT_ID/tools/$TOOL_ID" \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "kind": "webhook",
      "url": "https://your-endpoint.example.com/lookup",
      "authHeaders": [
        { "name": "Authorization", "value": "Bearer your-endpoint-token" }
      ]
    }
  }'
```

Speko resolves each `authHeaders` value at call time and merges it into the outbound request alongside the Standard Webhooks signature. A few rules:

* **Reserved names are rejected.** Speko's signer always controls `content-type`, `accept`, `user-agent`, and the `webhook-*` headers, so you can't set those.
* **The list replaces the stored set.** On update, omit a header's `value` to keep the secret already stored under that name; drop a header from the list to remove it; add one with a `value` to set or rotate it.
* **Plaintext headers vs. secrets.** `authHeaders` values are encrypted. If you only need a non-sensitive static header, the separate `headers` map carries plaintext as-is.

Workspace lifecycle endpoints accept the same `authHeaders` and can use either the organization signing secret or one custom signing secret per endpoint. Configure them in **Settings → Webhooks** or with `speko.webhooks`; agent-level lifecycle webhook fields are deprecated.

### Per-call secrets and URLs (`toolSecrets`) [#per-call-secrets-and-urls-toolsecrets]

`authHeaders` covers credentials that are the same on every call. When a credential is minted **per call** — a short-lived access token scoped to the person being called, or a tenant-specific API base URL — pass it on the session or dial request as `toolSecrets`:

```json
{
  "agentId": "agent_abc123",
  "to": "+12015551234",
  "toolSecrets": {
    "base_url": "https://acme.example.com",
    "access_token": "eyJhbGciOi..."
  }
}
```

Then reference the names from the tool definition:

* **Webhook tools** — `{{name}}` in `url` and in `headers` values:

  ```json
  {
    "url": "{{base_url}}/api/interviews/answer",
    "headers": { "authorization": "Bearer {{access_token}}" }
  }
  ```

* **Custom code tools** — `session.secrets.<name>` (and `session.variables.<name>` for the prompt `variables`):

  ```js
  const res = await fetch(`${session.secrets.base_url}/api/interviews/answer`, {
    method: 'POST',
    headers: { authorization: `Bearer ${session.secrets.access_token}` },
    body: JSON.stringify(args),
  });
  return await res.json();
  ```

What makes `toolSecrets` different from `variables`:

* **Never visible to the model.** `variables` render into the system prompt; `toolSecrets` are never compiled into any prompt, never appear in the transcript or call metadata, and are not returned by any read endpoint. They are stored encrypted and released only to tool execution.
* **Redacted on the way back.** A value echoed verbatim in a tool result is replaced with `[redacted:name]` before the model sees it (best-effort — derived values such as a base64 encoding survive).
* **Unresolved names fail the call.** A `{{name}}` with no matching entry returns `webhook_template_invalid` instead of sending the braces. Prompt `variables` are also available to `{{name}}` in webhook tools; a `toolSecrets` entry wins on a name collision.
* **A `{{base_url}}` host may only carry per-call values.** A template may choose the path freely, but when it chooses the *host*, nothing constant configured on the tool may ride along: the tool must have no `authHeaders`, no [`body` template](#shaping-the-request-body), and every `headers` value must be exactly one per-call `{{name}}`, optionally behind `Bearer`, `Basic`, `Token`, `ApiKey` or `Digest` (`Bearer {{access_token}}`) — no other literal text (`org-key-{{nonce}}` is refused). A constant header, an `authHeaders` entry or a body template is somewhere a long-lived credential can hide, and none of them may follow a caller-chosen host — hard-code the origin for those tools.
* **Limits.** Names are identifiers (`[A-Za-z_][A-Za-z0-9_]*`), up to 32 entries, 6 characters to 4 KB per value, 16 KB total (the floor exists because shorter values cannot be redacted from tool output — put short non-secret values in `variables`). Values are inserted verbatim into URLs and headers; the assembled URL must be `http(s)` and still passes the SSRF guard.

### HTTP method [#http-method]

<Note>
  `method`, `body`, `responseMode` and `asyncAck` take effect on a live call from
  **v0.0.505**. Earlier releases accepted them, stored them, and read them back,
  but the tool snapshot handed to a dispatched session dropped all four — a tool
  configured `PUT` with a `body` template delivered a `POST` with the default
  envelope, and an `async` tool ran `sync`. Nothing needs re-saving: the fix is in
  the snapshot, not in your stored configuration.
</Note>

Webhook tools `POST` by default. Set `method` to `PUT`, `PATCH`, `DELETE` or `GET` when the endpoint you are calling expects a different verb:

```json
{
  "source": {
    "kind": "webhook",
    "url": "https://your-endpoint.example.com/interviews/42",
    "secret": "<32-char hex you supply>",
    "method": "PATCH"
  }
}
```

`GET` and `DELETE` send **no request body** — not a `body` template, and not the default envelope either. Pairing either with `body` is rejected at save time with `422 WEBHOOK_TEMPLATE_INVALID` rather than dropping the body on every call. The Standard Webhooks signature is still sent (computed over an empty payload), so `webhook-id` and `webhook-timestamp` stay authenticated and replay protection still works.

Because a body-less request carries no `args`, a `GET` or `DELETE` tool cannot convey the model's arguments today — `{{name}}` in the `url` resolves session values only, not arguments. Use `POST`/`PUT`/`PATCH` when the endpoint needs the arguments.

### Shaping the request body [#shaping-the-request-body]

By default Speko sends one fixed envelope, in which only `args` varies:

```json
{
  "tool": "ATS_Interview_Success",
  "args": { "conversation_id": "85e2de9c-a8cc-41e3-a5f4-7f25b0bab7fa" },
  "idempotency_key": "85e2de9c-…:graph_9084b1d0140e",
  "session_id": "85e2de9c-…",
  "tool_call_id": "graph_9084b1d0140e"
}
```

That works when you own the endpoint and can unwrap it. When the endpoint is a third-party API with its own payload contract, set `body` to a JSON template. Every **string leaf** interpolates `{{name}}`, and the template replaces the envelope entirely:

```json
{
  "source": {
    "kind": "webhook",
    "url": "https://api.vendor.example.com/v2/events",
    "secret": "<32-char hex you supply>",
    "method": "POST",
    "body": {
      "event_type": "interview_completed",
      "tenant": "{{tenant}}",
      "candidate": { "name": "{{args.name}}", "score": "{{args.score}}" },
      "trace": { "call": "{{session_id}}", "dedupe": "{{idempotency_key}}" }
    }
  }
}
```

Omit `body` and the envelope above is sent exactly as it always was.

Here is a template and the request one endpoint actually received from it:

```json title="body template"
{
  "event_type": "candidate_withdrew",
  "conversation": "{{args.conversation_id}}",
  "speko_session": "{{session_id}}",
  "idem": "{{idempotency_key}}",
  "tenant": { "host": "{{api_hostname}}", "token": "{{api_token}}" },
  "raw_args": "{{args}}"
}
```

```json title="delivered body"
{
  "event_type": "candidate_withdrew",
  "conversation": "priya_raman_delivery_driver",
  "speko_session": "b782ba43-…",
  "idem": "b782ba43-…:toolu_01ShrY3g…",
  "tenant": { "host": "your-sink.example.com", "token": "precall-tagged-token" },
  "raw_args": { "conversation_id": "priya_raman_delivery_driver" }
}
```

Read `raw_args` closely: it arrived as an **object**, not as a JSON string. `"{{args}}"` is a whole-value placeholder, so the quotes belong to the template and never reach the payload — a receiver that calls `JSON.parse` on that field will throw. `tenant.host` shows that a session value may name a host *inside* the body; only the `url`'s origin has to be constant.

#### Reserved names [#reserved-names]

Inside `body` you can reference every session `variables` and `toolSecrets` entry, plus these:

| Name                  | Substitutes                                        |
| --------------------- | -------------------------------------------------- |
| `{{tool_name}}`       | The tool's name                                    |
| `{{session_id}}`      | The session id                                     |
| `{{tool_call_id}}`    | The model's tool-call id                           |
| `{{idempotency_key}}` | `<session_id>:<tool_call_id>`                      |
| `{{args.<name>}}`     | One argument, with its JSON type preserved         |
| `{{args}}`            | The whole arguments object — as a whole value only |

A reserved name wins over a session value of the same name, so a caller cannot change what `{{session_id}}` means by passing a variable called `session_id`.

#### Rules [#rules]

Two of these refuse the whole configuration at save time rather than a single field, so read them first:

* **A templated origin forbids a body template.** When a session value chooses the *host* (`{{base_url}}/events`), the tool may not carry a `body` template at all — for the same reason it may not carry `authHeaders` or a constant header. A template can hold a credential (`{"api_key": "sk_live_…"}` is how many vendors authenticate) and we cannot tell one from a discriminator by looking, so nothing configured on the tool follows a caller-chosen host. Hard-code the origin if you need to shape the body; a templated *path* under a constant origin is fine.
* **`GET` and `DELETE` forbid a body template.** Those verbs send no request body at all, so pairing either with `body` is refused at save time instead of dropping the template on every call — see [HTTP method](#http-method).

The rest apply per field:

* **Types are preserved in a whole value.** `"score": "{{args.score}}"` sends the number `42`, not the string `"42"`, when the argument is a number. Placeholders *inside* a longer string always produce text: `"note": "scored {{args.score}}"` sends `"scored 42"`.
* **`{{args}}` must be the whole value.** `"payload": "{{args}}"` substitutes the object. `"payload": "args: {{args}}"` is rejected at save time — silently JSON-stringifying an object into a text slot is a footgun, so name a single `{{args.<field>}}` instead.
* **Only values interpolate, never keys.** A key containing `{{` is rejected rather than sent with the braces intact.
* **Unresolved names fail the call.** Same as the url and headers: `webhook_template_invalid`, before any request goes out.
* **Limits.** 8 KB serialized, 8 levels of nesting, and 64 KB after substitution. `__proto__`, `constructor` and `prototype` are rejected as keys.

Values are never spliced into serialized JSON — Speko builds a value tree and serializes it once, so a substituted value containing quotes, braces or newlines is escaped and cannot alter the structure of the payload.

### Async webhook tools [#async-webhook-tools]

Webhook tools default to `responseMode: "sync"`: Speko waits for your endpoint response and feeds the JSON body into the next model turn. For work that should not block the conversation, set `responseMode: "async"` and provide an `asyncAck`:

```json
{
  "source": {
    "kind": "webhook",
    "url": "https://your-endpoint.example.com/create-ticket",
    "secret": "<32-char hex you supply>",
    "responseMode": "async",
    "asyncAck": "I started that request and will continue helping while it runs."
  }
}
```

In async mode, Speko dispatches the signed webhook in the background and immediately returns the acknowledgement text to the model. Use this for ticket creation, CRM updates, notifications, and other side effects where the caller does not need the result before the next assistant turn.

### Use the actual agent id [#use-the-actual-agent-id]

Tools are scoped to one persisted agent. Use the agent id returned by `POST /v1/agents` or shown on the dashboard agent page. The unique key is `(organization, agentId, toolName)`, so two agents can use the same tool name without sharing webhook config.

## 3. Wire the worker [#3-wire-the-worker]

If you run a LiveKit Agents worker, the adapter loads your registered tools at session start and merges them with anything the framework provides at runtime. Use `createSpekoComponents` with the registered-tools options:

```ts agent.ts
import { defineAgent, voice } from '@livekit/agents';
import * as silero from '@livekit/agents-plugin-silero';
import { Speko } from '@spekoai/sdk';
import { createSpekoComponents } from '@spekoai/adapter-livekit';

const speko = new Speko({
  apiKey: process.env.SPEKO_API_KEY!,
  baseUrl: process.env.SPEKO_BASE_URL,
});

export default defineAgent({
  prewarm: async (proc) => {
    proc.userData.vad = await silero.VAD.load();
  },
  entry: async (ctx) => {
    const vad = ctx.proc.userData.vad as silero.VAD;

    const { stt, llm, tts } = createSpekoComponents({
      speko,
      vad,
      intent: { language: 'en-US', optimizeFor: 'latency' },
      // Enable the registered-tools loader. The adapter calls
      // speko.agents.tools.listChatTools(agentId) once per session — reusing
      // the Speko client above for auth and base URL — and merges the result
      // with whatever LiveKit's ToolContext provides. Registered tools win on
      // name collision.
      agentId: process.env.SPEKO_AGENT_ID!,
      onRegisteredToolsError: (err) =>
        console.error('SpekoWorker: tools fetch failed', err),
    });

    const session = new voice.AgentSession({ vad, stt, llm, tts });
    await session.start({
      agent: new voice.Agent({
        instructions:
          'You are a brief, friendly assistant. ' +
          'When the user asks about a specific pet by name, ' +
          'IMMEDIATELY call lookup_pet — never make up information.',
      }),
      room: ctx.room,
    });
    await ctx.connect();
  },
});
```

Without `agentId`, the loader stays disabled and the agent only sees runtime tools — useful when you want to opt in selectively.

Outside a LiveKit worker, load the same tools yourself with `speko.agents.tools.listChatTools(agentId)` and pass them to `speko.complete({ tools })`. It returns every source kind (`inline`, `webhook`, `builtin`, `integration`) already in the `ChatTool[]` shape `/v1/complete` accepts.

## 4. Run a call [#4-run-a-call]

The simplest client is a browser using [`@spekoai/client`](/client/overview):

```ts
import { VoiceConversation } from '@spekoai/client';

const res = await fetch('/api/session', { method: 'POST' });
const { transportToken, transportUrl } = await res.json();

const conv = await VoiceConversation.create({
  transportToken,
  transportUrl,
  onModeChange: (mode) => console.log(mode), // 'listening' | 'speaking'
});
```

Your `/api/session` server route mints browser-safe transport credentials via Speko:

```ts
const r = await fetch(process.env.SPEKO_BASE_URL + '/v1/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + process.env.SPEKO_API_KEY,
  },
    body: JSON.stringify({
      mode: 'cascade',
      agentId: process.env.SPEKO_AGENT_ID!,
      ttlSeconds: 900,
    }),
});
const { transportToken, transportUrl } = await r.json();
```

## What gets sent over the wire [#what-gets-sent-over-the-wire]

When the model invokes a registered tool, Speko's executor signs the request with your secret and POSTs to your URL:

```http
POST https://your-endpoint.example.com/lookup
content-type: application/json
webhook-id: sess_2KQfP3QH8Gv7B:call_9084b1d0140e
webhook-timestamp: 1735603214
webhook-signature: v1,F7ZxQk8j3p6m2N9...

{
  "tool": "lookup_pet",
  "args": { "name": "Luna" },
  "idempotency_key": "sess_2KQfP3QH8Gv7B:call_9084b1d0140e",
  "session_id": "sess_2KQfP3QH8Gv7B",
  "tool_call_id": "call_9084b1d0140e"
}
```

The model's arguments are under `args`; the envelope around them identifies the call so you can deduplicate retries on `idempotency_key`. Set `body` to send a different shape instead — see [Shaping the request body](#shaping-the-request-body).

Your response body is what the model sees as the tool result. Errors propagate too — if your endpoint returns 4xx/5xx, the executor surfaces the error so the agent can apologize or retry instead of silently swallowing it.

## Debugging [#debugging]

Common failure modes:

* **Tool never invoked.** The model didn't decide to call it. Tighten the description (be explicit about *when* to call), or set `toolChoice: "required"` in your call options to force one.
* **Webhook never lands.** Check the worker logs for the executor span. Common: 403 from your endpoint (signature mismatch), 5xx (your code threw), or timeout (your endpoint is too slow — the executor hard-caps webhook reads at 4000ms; see Timeouts above).
* **Agent says "couldn't find" instead of the real result.** Your endpoint returned 4xx. Either the query genuinely missed, or the model passed empty/wrong args. During development, have your endpoint echo back the body it received so you can spot the latter.
* **Two voices overlap in the room.** A second agent dispatched into the same room without ending the previous session. Always call `endSession()` on your `VoiceConversation` (or disconnect the participant) before opening a new conversation.

## Beyond webhooks [#beyond-webhooks]

Webhook tools are the most common, but a registered tool's `source` can also be:

* **`builtin`** — Speko-managed helpers you opt into without running your own endpoint. Current built-ins include `search_knowledge_base`, `transfer_call`, and `end_call` (always enabled — the agent can hang up once the conversation is done; the legacy `endCall` create field is accepted but ignored). `transfer_call` supports warm or blind transfers from the active phone session when configured with destinations.
* **`integration`** — an action from an org-installed Speko app (Google Calendar, Slack, …), resolved and executed server-side.
* **`inline`** — your own worker runs the tool; Speko just ships the schema to the model and returns the call to you.

All four kinds come back from `speko.agents.tools.listChatTools(agentId)` ready to hand to `speko.complete`.

## What's next [#whats-next]

* Streaming tool results for long-running queries.

Track progress on the [public roadmap](https://github.com/SpekoAI/platform).


# Batch transcription (/guides/transcription)

POST /v1/transcribe with workload=transcription: diarization, formatting, and per-provider batch params.



Recorded audio in, formatted transcript out. Set `workload: "transcription"` in the `X-Speko-Stt-Options` header to apply transcript-reading defaults such as smart formatting instead of the conversational defaults live agents use.

```bash
curl -X POST https://api.speko.dev/v1/transcribe \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: audio/wav" \
  -H "x-speko-intent: {\"language\":\"en-US\"}" \
  -H "x-speko-stt-options: {\"workload\":\"transcription\"}" \
  --data-binary @meeting.wav
```

The response is the usual SSE stream. When the request uses `workload` or any provider param, the final `done` event reports what actually applied:

```json
{
  "text": "...",
  "provider": "deepgram",
  "model": "nova-3",
  "confidence": 0.96,
  "failoverCount": 0,
  "effectiveParams": {
    "provider": "deepgram",
    "model": "nova-3",
    "applied": ["smartFormat"],
    "defaultsVersion": "2026-08-06"
  }
}
```

`warnings` appears alongside `effectiveParams` when params were dropped or candidates excluded. The per-provider defaults each workload applies are listed in [Provider params](/concepts/provider-params#workload-defaults).

## Diarization [#diarization]

```bash
curl -X POST https://api.speko.dev/v1/transcribe \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: audio/wav" \
  -H "x-speko-intent: {\"language\":\"en-US\"}" \
  -H "x-speko-stt-options: {\"workload\":\"transcription\",\"diarization\":true,\"speakersExpected\":2}" \
  --data-binary @interview.wav
```

* `diarization` is batch-only and demote-class: providers that cannot diarize are removed from the failover ladder before the first attempt, each reported as a `candidate_excluded` warning. If no capable provider remains, the request fails with `422` `{ "error": "no_capable_provider", "param": "diarization" }` rather than silently transcribing without speakers.
* `speakersExpected` is a hint, forwarded where supported (AssemblyAI `speakers_expected`, ElevenLabs `num_speakers`, Google `diarizationConfig.maxSpeakerCount`) and dropped elsewhere.
* Speaker labels are normalized to `S0`, `S1`, ... across providers on word-level output. Today the `/v1/transcribe` response returns the merged transcript text; exposing the per-word speaker labels on this endpoint is a follow-up.

## Batch formatting params [#batch-formatting-params]

Provider-specific batch knobs go in `providerOptions`. They are validated up front and apply only when that provider serves the request:

```bash
curl -X POST https://api.speko.dev/v1/transcribe \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: audio/wav" \
  -H "x-speko-intent: {\"language\":\"en-US\"}" \
  -H "x-speko-stt-options: {\"workload\":\"transcription\",\"providerOptions\":{\"deepgram\":{\"dictation\":true}}}" \
  --data-binary @meeting.wav
```

Common batch params:

| Provider   | Param                    | Type    | Values              | Effect                                                  |
| ---------- | ------------------------ | ------- | ------------------- | ------------------------------------------------------- |
| Deepgram   | `detect_language`        | boolean |                     | Detects the dominant language of each channel.          |
| AssemblyAI | `multichannel`           | boolean |                     | Transcribes each channel of a recording separately.     |
| AssemblyAI | `language_detection`     | boolean |                     | Detects the language of a prerecorded transcript.       |
| ElevenLabs | `timestamps_granularity` | enum    | `word`, `character` | Selects word- or character-level transcript timestamps. |
| ElevenLabs | `tag_audio_events`       | boolean |                     | Includes non-speech audio event tags in the transcript. |

Full registry, validation rules, and failover semantics: [Provider params](/concepts/provider-params).

## Picking providers [#picking-providers]

* `POST /v1/recommend-stack` with `{ "useCase": "<vertical id>" }` returns ranked stacks per vertical; `POST /v1/recommend-stack/from-description` classifies a freeform description first.
* To pin the STT pool directly, use the `x-speko-constraints` header: `{"allowedProviders":{"stt":["deepgram","assemblyai"]}}`. Routing still ranks within the allow-list.

## Limits [#limits]

* `X-Speko-Stt-Options` is capped at 4 KB.
* `/v1/transcribe` validates params against the `batch` surface. Streaming-only params (Deepgram `endpointing`, AssemblyAI turn thresholds) belong to the streaming WebSocket, `/v1/transcribe/stream`.


# Build a voice agent (/guides/voice-agent)

Real-time STT → LLM → TTS pipeline using @spekoai/adapter-livekit on a LiveKit Agents worker.



This guide walks through standing up a LiveKit Agents worker that uses Speko for every modality. The worker registers with LiveKit Cloud, joins rooms on demand, and runs a streaming voice pipeline backed by Speko's routing.

If you only want browser-side conversation logic and don't run your own worker, see the [hosted session flow](/guides/realtime-conversation) instead.

## Architecture [#architecture]

```
Browser ⟷ LiveKit room ⟷ your agent worker
                              │
                              └─→ @spekoai/sdk → Speko gateway → providers
```

Three processes meet in a LiveKit room:

1. **Browser** uses [`@spekoai/client`](/client/overview) to join with a session token your server mints.
2. **Your API server** mints the token (`POST /v1/sessions` or your own `livekit-server-sdk` flow) and dispatches the agent worker.
3. **Your agent worker** (this guide) runs `@livekit/agents` with Speko-backed STT/LLM/TTS.

Audio flows browser ↔ LiveKit ↔ worker. Speko sits in the control path, not the audio path.

## Install [#install]

```bash
npm install @spekoai/sdk @spekoai/adapter-livekit \
            @livekit/agents @livekit/agents-plugin-silero @livekit/rtc-node
```

`@livekit/agents` and `@livekit/rtc-node` are peers — pin the versions you actually run.

## Worker entry [#worker-entry]

```ts agent.ts
import {
  type JobContext,
  type JobProcess,
  ServerOptions,
  cli,
  defineAgent,
  voice,
} from '@livekit/agents';
import * as silero from '@livekit/agents-plugin-silero';
import { Speko } from '@spekoai/sdk';
import { createSpekoComponents } from '@spekoai/adapter-livekit';
import { fileURLToPath } from 'node:url';

const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });

export default defineAgent({
  prewarm: async (proc: JobProcess) => {
    proc.userData.vad = await silero.VAD.load();
  },
  entry: async (ctx: JobContext) => {
    const vad = ctx.proc.userData.vad as silero.VAD;

    const { stt, llm, tts } = createSpekoComponents({
      speko,
      vad,
      intent: { language: 'en-US', optimizeFor: 'balanced' },
      // optional: pin providers
      // constraints: { allowedProviders: { tts: ['cartesia'] } },
    });

    const session = new voice.AgentSession({ vad, stt, llm, tts });

    await session.start({
      agent: new voice.Agent({
        instructions: 'You are a helpful voice assistant. Be concise.',
      }),
      room: ctx.room,
    });

    await ctx.connect();
    session.generateReply({ instructions: 'Greet the user and offer your assistance.' });
  },
});

cli.runApp(
  new ServerOptions({
    agent: fileURLToPath(import.meta.url),
    agentName: 'speko-demo',
  }),
);
```

Run it with `node agent.js` (after build) or your `tsx` setup of choice. The worker registers with LiveKit Cloud under `agentName` and waits for dispatches.

## Per-session config from dispatch metadata [#per-session-config-from-dispatch-metadata]

When your server creates a session, the dispatcher passes JSON metadata to the worker. Read it in `entry` to build pipeline-per-session:

```ts
import { z } from 'zod';

const dispatchSchema = z.object({
  sessionId: z.string(),
  intent: z.object({
    language: z.string(),
    optimizeFor: z.enum(['balanced', 'accuracy', 'latency', 'cost']).optional(),
  }),
  constraints: z.any().optional(),
  voice: z.string().optional(),
  systemPrompt: z.string().optional(),
});

const meta = dispatchSchema.parse(JSON.parse(ctx.job.metadata ?? '{}'));

const { stt, llm, tts } = createSpekoComponents({
  speko,
  vad,
  intent: meta.intent,
  constraints: meta.constraints,
  voice: meta.voice,
});
```

## Limitations of v1 [#limitations-of-v1]

* **STT upload is utterance-bounded.** `/v1/transcribe` streams transcript events back, but the LiveKit adapter still uploads one VAD-segmented WAV per utterance.
* **TTS is sentence-bounded in LiveKit.** `/v1/synthesize` streams audio bytes while the adapter calls it once per tokenized sentence.
* **Tool calls are supported.** Inline tools return to the LiveKit runtime; registered webhook, builtin, and integration tools run server-side through `/v1/complete`.
* **TTS format constraints.** Cartesia (PCM) and WAV TTS work. ElevenLabs MP3 currently throws — pin a PCM-capable provider via `constraints.allowedProviders.tts` or rely on the router's score-driven default.
* **STT input.** Mono PCM16 frames; multi-channel throws.

See [`@spekoai/adapter-livekit` reference](/adapter-livekit/overview) for the full surface.

## Next [#next]

<CardGroup cols="2">
  <Card title="Browser side" icon="browser" href="/guides/realtime-conversation">
    Wire `@spekoai/client` into your dashboard / web app.
  </Card>

  <Card title="Adapter API" icon="plug" href="/adapter-livekit/overview">
    Full adapter reference.
  </Card>
</CardGroup>


# Workspace webhooks (/guides/webhooks)

Route lifecycle events to organization endpoints by event, agent, and session tags, then inspect every delivery attempt.



Workspace webhooks are managed independently from agents. Configure them in **Settings → Webhooks** or through `/v1/webhooks`. One endpoint can subscribe to several lifecycle events and either every agent or an explicit agent set.

## Create an endpoint [#create-an-endpoint]

```ts
const endpoint = await speko.webhooks.create({
  name: 'Production call events',
  url: 'https://hooks.example.com/speko',
  events: ['call.status', 'call.report', 'call.analysis', 'call.recording'],
  allAgents: true,
  filterTags: { environment: 'production' },
  headers: { 'x-source': 'speko' },
  authHeaders: [{ name: 'Authorization', value: 'Bearer secret-token' }],
  timeoutMs: 4000,
});
```

Supported voice-session events are:

| Event            | When it fires                                                                    | Automatic retries |
| ---------------- | -------------------------------------------------------------------------------- | ----------------- |
| `call.pre_call`  | Before the worker starts; the response may override supported call configuration | No                |
| `call.status`    | When a call lifecycle event is recorded                                          | No; best effort   |
| `call.report`    | When the report is finalized, and again when a recording becomes ready           | Yes               |
| `call.analysis`  | When post-call analysis completes                                                | Yes               |
| `call.recording` | When recording reaches ready or failed                                           | Yes               |

### Call control events [#call-control-events]

These describe a **human** call — a broker on a browser softphone talking to a phone — leg by leg, rather than an AI voice session. None are retried: they project a live event history that stays readable at `GET /v1/voice/calls/{callId}/events`, so a redelivery would land too late to be worth anything.

| Event                                                                          | When it fires                                                               | Automatic retries |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ----------------- |
| `call.initiated`                                                               | A call is created, before anyone is reachable                               | No                |
| `call.ringing`                                                                 | A leg starts ringing (an outbound INVITE is out, or a broker is being rung) | No                |
| `call.answered`                                                                | A leg answers; the first one to answer also starts the call                 | No                |
| `call.bridged`                                                                 | A leg is pulled into another leg's conversation                             | No                |
| `call.hold` / `call.unhold`                                                    | A leg is parked or resumed                                                  | No                |
| `call.mute` / `call.unmute`                                                    | A leg's own audio is muted or restored, server-side                         | No                |
| `call.dtmf.sent`                                                               | Speko sent tones towards a PSTN leg                                         | No                |
| `call.transfer.initiated` / `call.transfer.completed` / `call.transfer.failed` | A blind or warm transfer progresses                                         | No                |
| `call.leg.hangup`                                                              | One leg drops                                                               | No                |
| `call.hangup`                                                                  | The whole call ends                                                         | No                |

Every call-control payload carries `call_id`, `control_id` (null for the call-scoped `call.initiated` and `call.hangup`), `event_id` and `occurred_at` beside the event's own fields. Human calls have no agent, so an endpoint scoped to `agentIds` never receives them — subscribe with `allAgents`.

Inbound DTMF (a key the far end pressed) is deliberately absent. It arrives as an in-room data packet addressed to room participants: a connected softphone sees it, the server does not. A subscription that can never deliver is worse than none.

Every delivery includes a stable `webhook_id` for that event occurrence and the session's `webhook_tags`. A report's initial and recording-ready emissions are separate occurrences with different IDs; retries and redeliveries reuse the original.

## Agent and tag routing [#agent-and-tag-routing]

`allAgents` defaults to `true`. Set it to `false` and provide `agentIds` to narrow the endpoint. New agents automatically match all-agent endpoints.

Tags are free-form, case-sensitive string pairs — up to 20 per session, keys to 64 characters and values to 256. Attach them when creating an agent-backed browser, realtime, or phone session:

```ts
await speko.voice.dial({
  to: '+12015551234',
  agentId: 'agent_123',
  webhookTags: {
    environment: 'production',
    customer: 'acme',
  },
});
```

An endpoint matches when all of its `filterTags` exist on the session with equal values. If any tagged endpoint matches, Speko sends to every matching tagged endpoint and ignores untagged defaults; if none match, it falls back to all matching untagged endpoints. Agentless sessions reject `webhookTags` with a 400 `WEBHOOK_TAGS_REQUIRE_AGENT` — there is no agent-scoped route to resolve.

There is no per-dial webhook URL: a request cannot carry a URL for Speko to call. Every destination is an endpoint registered ahead of time with `POST /v1/webhooks`, and the only per-call control is `webhookTags` choosing between them through their `filterTags`. To route by tenant or environment, register one endpoint per destination and tag the session.

## Pre-call webhook [#pre-call-webhook]

`call.pre_call` fires before the worker starts and its response may override supported call configuration — the place to look the caller up, choose a greeting, or inject account context. Phone calls fire it automatically. A browser or realtime session asks for it per session, on `POST /v1/sessions`:

```json
{
  "agentId": "agent_123",
  "preCallWebhook": true,
  "webhookTags": { "tenant": "acme" }
}
```

It is opt-in here for two reasons. Your own backend mints a web session and usually already holds the values a lookup would return, so it can send them as `variables`. And an organization already running `call.pre_call` for phone traffic should not find its web sessions failing the first time that handler throws. Requires `agentId` and a subscribed endpoint; with neither, the session is created normally. Dashboard test calls and eval runs never fire it.

The webhook writes last on pipeline configuration. A returned `firstMessage` replaces both one sent on the create request and anything the agent supplies per language. `turnHandling` merges field by field: a handler returning `turnHandling: { onMachine: 'hangup' }` changes that one field and leaves an inherited [`voicemailMessage`](/docs/guides/phone-agents#voicemail-handling) in place. `toolSecrets` is the exception below.

The payload is the shape documented under [phone agents](/docs/guides/phone-agents#5-customize-calls-before-answer). One difference: a session sends `direction: "web"`, with `to`, `from`, `dialed_number`, `forwarded_from_number`, `phone_number_id` and `call_control_id` all `null`. A handler can tell a session from a call on that alone. Overrides land before prompt compilation, so `variables` still render. `toolSecrets` is the exception to the ordering above — there the create request wins.

The pre-call is fail-closed on every path. A delivery that refuses, times out or answers non-2xx fails session creation with 502 `PRE_CALL_WEBHOOK_FAILED`, rather than starting a session without the context its handler was meant to supply. Only one effective `call.pre_call` endpoint may match an agent/tag route. When more than one does, creation fails with 409 `PRE_CALL_WEBHOOK_AMBIGUOUS`; the attempt is still recorded in the logs below.

## Signing and secrets [#signing-and-secrets]

Requests use Standard Webhooks headers and the workspace signing secret by default. Set `signingSecretSource: 'custom'` with a write-only `signingSecret` to override it per endpoint. Auth-header values are encrypted and read back only as `{ name, configured: true }`; on update, omit a value to keep it or supply one to rotate it.

Query values, signatures, authorization, cookies, API keys, and credential-shaped headers are redacted from delivery logs. Response bodies are capped at 64 KiB and expose `responseTruncated`.

Lifecycle payloads are not templated. Unlike a [webhook tool](/docs/guides/tool-calling#shaping-the-request-body), an endpoint cannot pick its HTTP method or shape its own body — every payload is a fixed object composed server-side. Its `headers` map is static plaintext, which is why credential-shaped names are rejected there.

## Extraction fields [#extraction-fields]

Endpoints subscribed to `call.report` or `call.analysis` can request `extractionFields`. Speko runs one extraction pass over the union all matching endpoints require, then includes only each endpoint's own fields in its `custom_data`. Identical definitions deduplicate; conflicting ones are rejected.

## Delivery logs and redelivery [#delivery-logs-and-redelivery]

Every attempt is queryable at `GET /v1/webhook-deliveries`, or in the **Logs** tab in Settings:

```ts
const page = await speko.webhooks.deliveries.list({
  endpointId: endpoint.id,
  event: 'call.report',
  status: 'failed',
  limit: 50,
});

const detail = await speko.webhooks.deliveries.get(page.data[0]!.id);
await speko.webhooks.deliveries.redeliver(detail.id);
```

A record holds the endpoint-specific request, sanitized URL and headers, HTTP result, duration, bounded response, error, routing tags, and chronological attempts, and is retained for 30 days. Private phone-number API deliveries (`imessage.received`, `imessage.reaction_received`, `imessage.sent`, `imessage.delivered`, `imessage.delivery_failed`) appear in the same place under the stable Inkbox event ID.

Check `canRedeliver` before retrying one. It is false for `call.pre_call`, for an expired record, and once the endpoint is deleted. A redelivery replays the stored payload and webhook ID against the endpoint's current URL and credentials, adding an attempt to the existing record. It neither schedules a new automatic retry nor cancels a pending one, and a delivery that already succeeded stays successful. Inkbox owns retry scheduling for `imessage.*`, so those records are view-only.

## Migrating agent webhooks [#migrating-agent-webhooks]

Agent webhook configuration is backfilled to central endpoints, and dispatch reads only those. `agent.webhooks` stays supported through the current SDK major version, with legacy writes synchronizing legacy-managed endpoints. New integrations should use `speko.webhooks`.


# exe.dev (/quickstart/exe)

Build Speko voice apps on exe.dev VMs — teach Shelley with Agent Skills, or launch the voice-agent starter with one click.





Speko works on [exe.dev](https://exe.dev) three ways: teach Shelley the Speko skills, launch the voice-agent starter into a fresh VM with one click, or connect the hosted MCP server to the Claude Code and Codex agents preinstalled on every VM.

## Teach Shelley the Speko skills [#teach-shelley-the-speko-skills]

Shelley discovers [Agent Skills](https://agentskills.io) from `~/.config/agents/skills` and from `.skills/` directories inside a repo. Install both Speko skills on a VM:

```bash
rm -rf /tmp/speko-skills \
  && git clone --depth 1 https://github.com/SpekoAI/agent-skills /tmp/speko-skills \
  && mkdir -p ~/.config/agents/skills \
  && cp -r /tmp/speko-skills/skills/* ~/.config/agents/skills/
```

`speko-voice-app` teaches Shelley to build against the Speko API — keys, the dial/poll/report loop, the speech endpoints, the traps. `speko-phone-call` teaches it to place one confirmed phone call and read back the transcript. To pin a skill to a single project instead, copy its folder into the repo's `.skills/` directory — every VM launched from that repo gets it automatically.

Things to ask Shelley once the skills are in place:

* "Build me a web app that calls a phone number I give it and shows the transcript."
* "Add voice input to this app — transcribe uploads with Speko."
* "Call +1 415 555 0142 and tell me if they picked up." Shelley reads the number back and asks for a yes before dialing.

Both skills authenticate with a platform key: mint one at [platform.speko.ai/agents/keys](https://platform.speko.ai/agents/keys) and export it as `SPEKO_API_KEY` in the VM.

## Launch the voice-agent starter [#launch-the-voice-agent-starter]

[<img alt="Deploy on exe.dev" src="__img0" />](https://exe.dev/new?repo=https://github.com/SpekoAI/voice-agent-starter)

One click creates a VM, clones [voice-agent-starter](https://github.com/SpekoAI/voice-agent-starter), and opens Shelley. Following the repo's `AGENTS.md`, Shelley asks for your `SPEKO_API_KEY`, installs dependencies, and starts the app: a browser page where you talk to a Speko voice agent over WebRTC.

The same button works from the starter's README, and you can put it on your own Speko-powered repos: link `https://exe.dev/new?repo=<your-repo-url>`.

## Use MCP from Claude Code or Codex [#use-mcp-from-claude-code-or-codex]

Every exe.dev VM ships with Claude Code and Codex preinstalled, and both speak MCP — Shelley itself does not, which is why the skills above are its native path. Connect the hosted server:

```
https://mcp.speko.ai/mcp
```

Setup, auth options, and prompts that work well: [MCP](/quickstart/mcp).

## Next steps [#next-steps]

<Columns cols="2">
  <Card title="Agent Skills repo" href="https://github.com/SpekoAI/agent-skills">
    The two skills, their install options, and the safety rules they encode.
  </Card>

  <Card title="Speko MCP" href="/quickstart/mcp">
    The hosted MCP server in Claude Code, Codex, and Cursor.
  </Card>

  <Card title="One-shot APIs" href="/guides/one-shot">
    `transcribe`, `synthesize`, `complete` — shapes, intents, constraints.
  </Card>

  <Card title="Routing" href="/concepts/routing">
    How Speko scores providers per language and optimization target.
  </Card>
</Columns>


# Quickstart (/quickstart)

From sign-up to your first transcribe call in under five minutes.



<Tip>
  Using Claude Code, Codex, OpenCode, Cursor, or another AI coding tool? Start by
  connecting [Speko MCP](/quickstart/mcp).
</Tip>

## 1. Create an account and an API key [#1-create-an-account-and-an-api-key]

Sign up at [platform.speko.ai](https://platform.speko.ai), then open [API keys](https://platform.speko.ai/agents/keys) and click **Create key**. Copy the raw value - it is shown once and starts with `sk_live_`.

```bash
export SPEKO_API_KEY=sk_live_xxx
```

## 2. Configure providers (optional) [#2-configure-providers-optional]

Speko uses platform-managed provider credentials by default. To bring your own keys (BYOK), open [Settings > Provider keys](https://platform.speko.ai/settings/provider-keys) and paste each provider's API key. Speko still picks the best provider per call; your keys are billed by the provider directly. See [BYOK](/concepts/byok).

## 3. Make your first call [#3-make-your-first-call]

<CodeGroup>
  ```bash cURL
  curl -X POST https://api.speko.dev/v1/transcribe \
    -H "Authorization: Bearer $SPEKO_API_KEY" \
    -H "Content-Type: audio/wav" \
    -H "x-speko-intent: {\"language\":\"en-US\"}" \
    --data-binary @call.wav
  ```

  ```ts TypeScript
  import { Speko } from '@spekoai/sdk';
  import { readFile } from 'node:fs/promises';

  const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });
  const audio = await readFile('./call.wav');

  const { text, provider, model, confidence } = await speko.transcribe(audio, {
    language: 'en-US',
  });

  console.log(text, 'from', provider, model, confidence);
  ```

  ```py Python
  import os
  from pathlib import Path

  from spekoai import Speko

  speko = Speko(api_key=os.environ["SPEKO_API_KEY"])
  audio = Path("call.wav").read_bytes()

  result = speko.transcribe(audio, language="en-US")
  print(result.text, "from", result.provider, result.model, result.confidence)
  ```
</CodeGroup>

The response includes `provider`, `model`, `confidence`, and `failoverCount` so you can see what actually ran. Routing headers are also returned: `X-Speko-Provider`, `X-Speko-Model`, `X-Speko-Failover-Count`, `X-Speko-Scores-Run-Id`.

## 4. Pick your next path [#4-pick-your-next-path]

<CardGroup cols="2">
  <Card title="Connect Speko MCP" icon="plug" href="/quickstart/mcp">
    Let your AI coding tool search docs, scaffold integrations, and use account tools.
  </Card>

  <Card title="Add voice to a browser app" icon="browser" href="/guides/realtime-conversation">
    Provider-direct S2S with OpenAI, Gemini Live, or xAI.
  </Card>

  <Card title="Use a framework adapter" icon="microphone" href="/guides/voice-agent">
    Connect Speko to a self-hosted LiveKit worker.
  </Card>

  <Card title="Use the one-shot APIs" icon="terminal" href="/guides/one-shot">
    `/v1/transcribe`, `/v1/synthesize`, `/v1/complete` for batch and server flows.
  </Card>

  <Card title="Transcribe recordings" icon="file-audio" href="/guides/transcription">
    `workload=transcription` with diarization and formatting params.
  </Card>

  <Card title="Narrate long-form text" icon="book-open" href="/guides/narration">
    `workload=narration` with per-provider voice settings.
  </Card>
</CardGroup>

## 5. Or let your coding agent build it [#5-or-let-your-coding-agent-build-it]

The fastest path to a working voice agent is to hand the rest to your AI coding tool. Install [Speko MCP](/quickstart/mcp):

```bash
npx @spekoai/mcp@latest init
```

Then paste this prompt into your agent:

```text
Using the Speko MCP tools, build me a voice agent:

1. Search the Speko docs for current voice agent best practices.
2. Create an agent named "my-first-agent" with a friendly assistant
   system prompt and the recommended STT, LLM, and TTS for my language.
3. Deploy it and start a test session so I can talk to it.
4. Scaffold a minimal web app that connects to it with @spekoai/client.
```

The agent uses Speko MCP to create, deploy, and test the voice agent against your account, then wires up a local app you can run immediately.


# MCP (/quickstart/mcp)

Connect Speko to Claude Code, Codex, OpenCode, Cursor, and other AI coding tools.



Speko MCP gives coding agents authenticated access to organizations, agents,
sessions, calls, phone numbers, knowledge bases, evals, deployment, migration
helpers, and usage data.

Tool surfaces are bound to hostnames. This page documents the full surface at
`mcp.speko.ai`; assistant directories are published on narrower hosts, listed
under [Directory hosts](#directory-hosts).

## Install in your tool [#install-in-your-tool]

Run the guided installer and choose OAuth browser sign-in:

```bash
npx @spekoai/mcp@latest init
```

The hosted endpoint is `https://mcp.speko.ai/mcp`. It uses stateless JSON HTTP
with MCP `2026-07-28`. Better Auth owns OAuth state while the MCP service
validates every access token independently, so requests can reach any replica.
Automation can instead use a Speko Platform API key from
[API keys](https://platform.speko.ai/agents/keys).

MCP does not expose API-key lifecycle tools. Create and revoke product-wide
Platform keys from [API keys](https://platform.speko.ai/agents/keys).

<Tabs defaultValue="claude-code" groupId="speko-mcp-client">
  <TabsList>
    <TabsTrigger value="claude-code">
      Claude Code
    </TabsTrigger>

    <TabsTrigger value="codex">
      Codex
    </TabsTrigger>

    <TabsTrigger value="opencode">
      OpenCode
    </TabsTrigger>

    <TabsTrigger value="cursor">
      Cursor
    </TabsTrigger>

    <TabsTrigger value="other">
      Other clients
    </TabsTrigger>
  </TabsList>

  <TabsContent value="claude-code">
    ```bash
    claude mcp add --transport http speko https://mcp.speko.ai/mcp
    ```
  </TabsContent>

  <TabsContent value="codex">
    Add to `~/.codex/config.toml`:

    ```toml
    [mcp_servers.speko]
    url = "https://mcp.speko.ai/mcp"
    ```
  </TabsContent>

  <TabsContent value="opencode">
    Add to `opencode.json`:

    ```json
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "speko": {
          "type": "remote",
          "url": "https://mcp.speko.ai/mcp",
          "enabled": true
        }
      }
    }
    ```
  </TabsContent>

  <TabsContent value="cursor">
    Open **Cursor Settings > MCP > Add new global MCP server**, then add:

    ```json
    {
      "mcpServers": {
        "speko": {
          "url": "https://mcp.speko.ai/mcp"
        }
      }
    }
    ```
  </TabsContent>

  <TabsContent value="other">
    Configure a remote HTTP MCP server:

    | Setting        | Value                      |
    | -------------- | -------------------------- |
    | Name           | `speko`                    |
    | URL            | `https://mcp.speko.ai/mcp` |
    | Authentication | OAuth browser sign-in      |
  </TabsContent>
</Tabs>

For API-key automation, add `Authorization: Bearer ${SPEKO_API_KEY}` using the
client's environment-variable syntax.

## What to ask your agent [#what-to-ask-your-agent]

Once connected to `mcp.speko.ai`, ask your agent to:

* inspect organization usage and credit balance;
* create, update, deploy, or roll back agents;
* create sessions and inspect call transcripts or recordings;
* create phone numbers, knowledge bases, and evals;
* convert external voice-agent configs with `migration.workspace.inspect`,
  `migration.external_config.parse`, and `migration.session_config.build`.

## Directory hosts [#directory-hosts]

Assistant directories run on their own hosts. Each surface is a property of the
host — no query parameter, header, or account setting widens it.

| Host                   | Tools | Surface                                                                 |
| ---------------------- | ----- | ----------------------------------------------------------------------- |
| `mcp.speko.ai`         | 101   | Full operational surface. Coding agents use this.                       |
| `anthropic.speko.ai`   | 35    | Anthropic MCP Directory. Reads, `audio.transcribe`, outbound calling.   |
| `chatgpt.speko.ai`     | 20    | OpenAI Plugin Directory.                                                |
| `builder-mcp.speko.ai` | 12    | App builders (v0, Lovable, Bolt, Base44, Figma Make).                   |
| `replit.speko.ai`      | 28    | Replit. Build-time tools first, plus knowledge bases and phone numbers. |

### Anthropic MCP Directory [#anthropic-mcp-directory]

`https://anthropic.speko.ai/mcp` serves 35 tools: reads across agents,
sessions, calls, transcripts, recordings, phone numbers, knowledge bases,
credits and usage, plus `audio.transcribe`, `docs.search`, the migration
helpers, `sessions.phone.create` for placing a call, and
`phone_numbers.kyb.{get,submit}` for the declaration that unlocks calling.

Six groups are absent from that host:

| group                                  | absent                                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------------------------- |
| audio generation                       | `audio.synthesize`                                                                          |
| live session / call creation           | `sessions.create`, `agents.test_call`                                                       |
| agent configuration and deployment     | `agents.create`, `agents.update`, `agents.deploy`, `agents.rollback`, `agents.tools` writes |
| knowledge-base and phone-number writes | `knowledge_bases` writes, `phone_numbers.create`, `phone_numbers.update`                    |
| bulk evaluation and monitoring         | `agents.evals.*`, `agents.monitors.*`                                                       |
| irreversible and outward-facing writes | `agents.delete`, `phone_numbers.delete`, `knowledge_bases.delete`, `share_cards.create`     |

Configuring an agent is equivalent to arming it — a deployed agent speaks on
inbound traffic with no further tool call — so agent configuration is withheld
alongside speech generation itself. `audio.transcribe` remains, because
speech-to-text produces no audio and returns only text. Calling a withheld tool
returns `Unknown tool`, indistinguishable from a name that was never
registered.

Before any outbound call the workspace files a business declaration: the
business name, what calling is for, and an attestation. It is two fields, it
takes effect the moment it is submitted, and `phone_numbers.kyb.get` returns the
prefilled name and the exact attestation text to show. Calls from the shared
caller-ID pool dial from a Speko-owned number, so the declaration is what keeps
a named business behind every call.

`sessions.phone.create` is served here. It places one call, to one number, per
explicit tool call, using an agent you deployed elsewhere — no bulk, scheduled
or unattended path reaches it, and the caller cannot configure the agent that
speaks. Every call created on a directory host has AI disclosure injected
server side: the first thing said on the line is that the caller is an AI, and
no prompt can override it.

To create agents or synthesize speech, use `mcp.speko.ai`, the
[REST API](/api-reference), or an SDK.


# Replit (/quickstart/replit)

Add voice — STT, TTS, and LLM with provider routing and failover — to any Replit app.



Speko works on Replit two ways: connect the hosted MCP server so Replit Agent can operate Speko for you, or call the API from your Repl with the Python or TypeScript SDK.

## Add Speko to Replit Agent (MCP) [#add-speko-to-replit-agent-mcp]

One click installs the hosted Speko MCP server into Replit Agent:

<a href="https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlNwZWtvIiwiYmFzZVVybCI6Imh0dHBzOi8vcmVwbGl0LnNwZWtvLmFpL21jcCJ9">
  <img src="/images/add-to-replit.png" alt="Add Speko to Replit" width="171" height="36" />
</a>

Or add it by hand — **+ Add MCP server**, name `Speko`, then **Test & save**:

```
https://replit.speko.ai/mcp
```

Either route opens Speko's OAuth sign-in, after which Agent has Speko tools across all your projects. For API-key auth instead of OAuth, add an `Authorization: Bearer sk_live_xxx` header under Advanced settings.

Things to ask Agent once connected:

* "Use the Speko MCP server to create a voice agent that answers in Spanish."
* "Show me the available Speko voices and models."
* "Generate the Speko integration code for this app."

For the full operational surface in Claude Code, Codex, and Cursor, see
[MCP](/quickstart/mcp).

## Call the API from your Repl [#call-the-api-from-your-repl]

### 1. Get an API key [#1-get-an-api-key]

Sign up at [platform.speko.ai](https://platform.speko.ai) — new organizations get $10 of starter credit. Open [API keys](https://platform.speko.ai/agents/keys), click **Create key**, and copy the `sk_live_` value.

### 2. Store the key in Replit Secrets [#2-store-the-key-in-replit-secrets]

In your Repl, open **Tools → Secrets** and add `SPEKO_API_KEY` with your `sk_live_` value. Secrets become environment variables at runtime. They stay out of your code and version history, and carry over when the app is deployed. Agent can do it too — ask it to add a `SPEKO_API_KEY` secret and it will prompt you for the value.

### 3. Install the SDK [#3-install-the-sdk]

```bash
pip install spekoai        # Python
npm install @spekoai/sdk   # Node / TypeScript
```

### 4. Make your first call [#4-make-your-first-call]

<CodeGroup>
  ```py Python
  import os

  from spekoai import Speko

  speko = Speko(api_key=os.environ["SPEKO_API_KEY"])

  speech = speko.synthesize("Salom, dunyo!", language="uz")
  with open("hello.mp3", "wb") as f:
      f.write(speech.audio)
  print(speech.provider, speech.content_type)
  ```

  ```ts TypeScript
  import { Speko } from '@spekoai/sdk';
  import { writeFile } from 'node:fs/promises';

  const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY! });

  const speech = await speko.synthesize('Salom, dunyo!', { language: 'uz' });
  await writeFile('hello.mp3', Buffer.from(speech.audio));
  ```

  ```bash cURL
  curl -X POST https://api.speko.dev/v1/synthesize \
    -H "Authorization: Bearer $SPEKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "text": "Salom, dunyo!", "intent": { "language": "uz" } }' \
    --output hello.mp3
  ```
</CodeGroup>

### 5. Chain the voice loop [#5-chain-the-voice-loop]

`transcribe → complete → synthesize` is a multilingual voice agent — each leg routed and failed over independently.

```py
from spekoai import ChatMessage, RoutingIntent

result = speko.transcribe(audio_bytes, language="es-MX")

reply = speko.complete(
    messages=[ChatMessage(role="user", content=result.text)],
    intent=RoutingIntent(language="es-MX"),
)

speech = speko.synthesize(reply.text, language="es-MX")
```

Full request and response shapes: [One-shot APIs](/guides/one-shot).

## Prompts that work well with Replit Agent [#prompts-that-work-well-with-replit-agent]

Paste these into Agent once `SPEKO_API_KEY` is in Secrets:

* "Build a Flask app with a record button. Transcribe with `POST https://api.speko.dev/v1/transcribe`, answer with `POST /v1/complete`, speak the reply with `POST /v1/synthesize`. Bearer `SPEKO_API_KEY`, language from a dropdown."
* "Add a voice note feature: upload audio, transcribe it with the `spekoai` package, store the text."
* "Make the app reply in the same language the user spoke — pass the selected language as the `intent` on every Speko call."

<Tip>
  Speko's docs are agent-readable. Point Agent at [/llms.txt](/llms.txt) when it
  needs the full API surface.
</Tip>

## Next steps [#next-steps]

<Columns cols="2">
  <Card title="Speko MCP" href="/quickstart/mcp">
    The same hosted MCP server in Claude Code, Codex, and Cursor.
  </Card>

  <Card title="One-shot APIs" href="/guides/one-shot">
    `transcribe`, `synthesize`, `complete` — shapes, intents, constraints.
  </Card>

  <Card title="Routing" href="/concepts/routing">
    How Speko scores providers per language and optimization target.
  </Card>

  <Card title="Python SDK" href="/sdk-python/overview">
    Full `spekoai` reference — sync, async, and realtime.
  </Card>
</Columns>


# Agent send_sms tool (/sms/agent-tool)

Bind a sender to an agent and queue compliant SMS from tool calls.



Bind the `send_sms` builtin to an agent with a fixed `fromPhoneNumberId`. The model only supplies `to` and `text`; it cannot choose a different sender or spoof a campaign.

```json
{
  "name": "send_confirmation_text",
  "description": "Send the customer the confirmation they requested.",
  "parameters": {
    "type": "object",
    "required": ["to", "text"],
    "properties": {
      "to": { "type": "string" },
      "text": { "type": "string", "maxLength": 1600 }
    }
  },
  "executionMode": "builtin",
  "source": {
    "kind": "builtin",
    "name": "send_sms",
    "config": { "fromPhoneNumberId": "8f0e9a96-..." }
  }
}
```

At execution Speko verifies that the bound number belongs to the same workspace and agent, then applies the same readiness, consent, suppression, quiet-hour, idempotency, and credit-reservation pipeline as the public API. The tool returns the durable message ID and current status. It never claims immediate delivery.

Inbound auto-replies use the same central send service and incur both the existing LLM charge and SMS segment charge. They remain off until explicitly enabled on the organization, number, and conversation.


# Registration API (/sms/api)

Automate 10DLC brand, campaign, and number registration with the /v1/sms/10dlc endpoints.



Everything in the [registration walkthrough](/sms/registration) is available programmatically. Base URL `https://api.speko.dev`, authenticated with your API key. All endpoints return `403` with code `SMS_10DLC_DISABLED_FOR_ORG` unless [SMS is enabled for your workspace](/sms#prerequisites).

## Overview [#overview]

```bash
curl https://api.speko.dev/v1/sms/10dlc \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

Returns the full registration state:

```json
{
  "ownBrand": { "status": "verified", "identityStatus": "VERIFIED", "profile": { "..." : "..." }, "reviewErrors": [], "submittedAt": "2026-07-01T22:04:11.000Z" },
  "ownCampaign": { "status": "active", "useCase": "ACCOUNT_NOTIFICATION", "reviewErrors": [], "submittedAt": "2026-07-02T18:30:00.000Z" },
  "sharedCampaign": { "available": false, "label": null, "campaignId": null, "status": null },
  "numbers": [
    { "id": "pn_...", "e164": "+15551234567", "smsEligible": true, "smsAssignmentStatus": "ASSIGNED", "assignedTo": "own", "...": "..." }
  ],
  "smsReady": true,
  "activeCampaignSource": "own"
}
```

`smsReady` is `true` once at least one number is assigned to a currently approved campaign. Statuses are stored snapshots — they refresh when you resubmit the brand (safe) or perform a new action, not on their own.

## Brand [#brand]

Save the business profile, then submit it to the carriers:

```bash
curl -X PUT https://api.speko.dev/v1/sms/10dlc/brand \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "MoonAI Inc",
    "displayName": "MoonAI",
    "entityType": "PRIVATE_PROFIT",
    "vertical": "TECHNOLOGY",
    "ein": "365142965",
    "website": "https://example.com/",
    "country": "US",
    "street": "131 Continental Dr Suite 305",
    "city": "Newark",
    "state": "DE",
    "postalCode": "19713",
    "supportEmail": "support@example.com",
    "supportPhone": "+15551234567",
    "authorizedContact": {
      "firstName": "Askhat", "lastName": "Adkhamov",
      "email": "founder@example.com", "phone": "+15551234567"
    }
  }'

curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/submit \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

All fields are required except `ein` (required in practice for every entity type except sole proprietors) and `country` (defaults to `US`). Phones are E.164. `legalName` must match the IRS record for the EIN.

Re-POSTing `/brand/submit` is the **status refresh**: it re-syncs your existing brand with the carriers and returns the current `status` / `identityStatus`. Brand is ready when `status` is `"verified"` (carrier status `OK` with identity `VERIFIED` or `VETTED_VERIFIED`).

Optional enhanced vetting after the brand is submitted:

```bash
curl -X POST https://api.speko.dev/v1/sms/10dlc/brand/vetting \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vettingClass": "STANDARD" }'
```

## Campaign [#campaign]

Save the campaign profile, then submit — **once**:

```bash
curl -X PUT https://api.speko.dev/v1/sms/10dlc/campaign \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useCase": "ACCOUNT_NOTIFICATION",
    "description": "Appointment confirmations and reminders sent by our AI receptionist.",
    "messageFlow": "Customers book an appointment by phone and verbally agree to receive a confirmation text and reminder texts for their visit.",
    "optInKeywords": "START",
    "optInMessage": "MoonAI: you are subscribed to appointment updates. Reply HELP for help, STOP to opt out.",
    "helpKeywords": "HELP",
    "helpMessage": "MoonAI: for help contact support@example.com. Reply STOP to opt out.",
    "optOutKeywords": "STOP",
    "optOutMessage": "MoonAI: you are unsubscribed and will receive no more messages.",
    "sampleMessages": [
      "MoonAI: your visit is confirmed for Jul 3 at 5:00 PM at 123 Main St. Reply STOP to opt out."
    ],
    "embeddedLink": false,
    "embeddedPhone": false
  }'

curl -X POST https://api.speko.dev/v1/sms/10dlc/campaign/submit \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

`sampleMessages` accepts 1-5 entries. Campaign submit requires a verified brand (`400` code `BRAND_NOT_READY` otherwise). Carrier review takes 1-7 business days; the campaign is ready when `status` is `"active"`.

<Warning>
  Do not re-POST `/campaign/submit` to poll status — unlike the brand endpoint, each campaign submission registers a **new** campaign with the carriers, with its own recurring carrier fees. Read status from `GET /v1/sms/10dlc` instead, and only resubmit after fixing an actual rejection.
</Warning>

## Numbers [#numbers]

```bash
curl -X POST https://api.speko.dev/v1/sms/10dlc/numbers/{phoneNumberId}/assign \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

Assigns the number to your approved campaign (pass `{ "target": "shared" }` to use Speko's shared campaign where available; with no body it prefers your own campaign, then shared). Phone number IDs come from `GET /v1/phone-numbers` or the `numbers` array in the overview. SIP-trunk imported numbers return `400` with code `SMS_ASSIGNMENT_UNSUPPORTED_NUMBER`.

`smsAssignmentStatus` values: `PENDING_ASSIGNMENT`, `ASSIGNED`, `FAILED_ASSIGNMENT`, `PENDING_UNASSIGNMENT`, `FAILED_UNASSIGNMENT`.

## Error codes [#error-codes]

| Code                                                                                                                         | Meaning                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `SMS_10DLC_DISABLED_FOR_ORG`                                                                                                 | SMS is not enabled for the workspace — [ask the Speko team](/sms#prerequisites) |
| `PROFILE_REQUIRED`                                                                                                           | Save the brand/campaign draft before submitting                                 |
| `BRAND_REQUIRED`                                                                                                             | Vetting requested before the brand was submitted                                |
| `BRAND_NOT_READY`                                                                                                            | Campaign submitted before the brand is verified                                 |
| `PHONE_NUMBER_NOT_FOUND`                                                                                                     | The phone number id doesn't belong to this workspace                            |
| `OWN_CAMPAIGN_NOT_READY` / `SHARED_CAMPAIGN_UNAVAILABLE` / `NO_ELIGIBLE_CAMPAIGN`                                            | No approved campaign to assign the number to                                    |
| `SMS_ASSIGNMENT_UNSUPPORTED_NUMBER`                                                                                          | SIP-trunk numbers can't join a Speko 10DLC campaign                             |
| `TELNYX_BRAND_SUBMIT_FAILED` / `TELNYX_CAMPAIGN_SUBMIT_FAILED` / `TELNYX_NUMBER_ASSIGNMENT_FAILED` / `TELNYX_VETTING_FAILED` | Carrier-side rejection or outage — check the details and retry                  |
| `VALIDATION_ERROR`                                                                                                           | Field validation failed — see the `issues` array                                |


# SMS billing and errors (/sms/billing-errors)

Understand segment reservations, final charges, and stable SMS error codes.



Speko estimates GSM-7 or UCS-2 segments and atomically reserves `sms.outbound_segment` credits when a message is created. Available balance is ledger balance minus active reservations.

The reservation is captured when Telnyx accepts the message and adjusted idempotently if the final segment count differs. Cancellation, revoked consent, local rejection, and definitive pre-provider failures release it. Accepted messages are not refunded when a carrier later reports delivery failure.

Ambiguous timeouts and provider `5xx` responses become `submission_unknown`; Speko retains the reservation and waits for a correlated webhook rather than risking a duplicate send. A reconciler resolves provider state or releases an unrecoverable hold after 72 hours. Late acceptance still creates one idempotent debit.

Inbound segments are debited idempotently but inbound storage is never rejected for insufficient credits. Final Telnyx cost is stored separately from retail credits for reporting.

## Stable errors [#stable-errors]

| Code                          | Meaning                                                        |
| ----------------------------- | -------------------------------------------------------------- |
| `PHONE_NOT_SMS_READY`         | Feature, number, profile, or current campaign readiness failed |
| `CONSENT_REQUIRED`            | No active campaign-scoped consent or conversation exception    |
| `RECIPIENT_SUPPRESSED`        | Organization-wide STOP suppression is active                   |
| `RECIPIENT_TIMEZONE_REQUIRED` | Proactive send has no resolvable IANA timezone                 |
| `INSUFFICIENT_CREDITS`        | Atomic segment reservation could not be made                   |
| `MESSAGE_NOT_CANCELABLE`      | Submission began or the message is terminal                    |
| `IDEMPOTENCY_CONFLICT`        | Key was reused with a different normalized request             |

Treat `submission_unknown` as a status, not a signal to retry. Recover by reading the existing message with its original ID or waiting for a webhook.


# Consent, suppression, and quiet hours (/sms/consent)

Record proof, enforce campaign-scoped consent, and honor organization-wide opt-outs.



Proactive SMS requires an active consent record for the workspace, recipient, and the sender's current 10DLC campaign. A direct reply may use the 24-hour recipient-initiated conversation exception, but suppression always wins.

Create one record with `POST /v1/sms/consents` or import up to 1,000 JSON records with `POST /v1/sms/consents/import`:

```json
{
  "recipient": "+12025550123",
  "campaign_id": "campaign_...",
  "source": "webform",
  "proof_reference": "signup/form-submission-982",
  "proof": "Consent checkbox text and captured form payload",
  "timezone": "America/New_York",
  "captured_at": "2026-09-01T13:00:00Z"
}
```

Speko stores a SHA-256 proof hash rather than returning raw proof. Sources are `inbound`, `api`, `keyword`, `webform`, `paper`, `verbal`, and `import`. Revoke with `POST /v1/sms/consents/{id}/revoke`.

## Keywords [#keywords]

Exact normalized STOP-family keywords create an organization-wide suppression, revoke applicable active consents, pause automation, and emit `sms.opted_out`. START/UNSTOP lifts suppression and creates consent for the receiving number's current campaign. HELP does not alter consent.

Telnyx Advanced Opt-Out sends the carrier acknowledgement. Speko does not send a duplicate STOP/START/HELP response.

Read the current state through `GET /v1/sms/consents` and `GET /v1/sms/suppressions`. Consent and opt-out audit facts are retained for seven years. Message text follows the configurable 30–3,650 day retention policy (730 days by default).

## Precedence [#precedence]

1. Active organization-wide suppression blocks every sender.
2. Proactive traffic requires campaign-scoped active consent and a timezone.
3. A normal inbound message opens the 24-hour conversational reply window.
4. Quiet hours shift proactive traffic to the next 08:00–21:00 recipient-local window, including daylight-saving transitions.


# Shared SMS inbox (/sms/inbox)

Work inbound and outbound conversations with humans and agents without duplicate replies.



Open **Messages** in the dashboard to search organization-scoped conversations by remote number, inspect delivery state and segment charges, assign work, add internal notes, and reply. The API mirrors the same model under `/v1/sms/conversations`.

One conversation exists per workspace, local number, and remote number. It snapshots the active campaign while retaining the selected sender. Inbound messages remain visible even if the campaign later drifts or is unassigned; outbound sending stays blocked until readiness is restored.

## Human workflow [#human-workflow]

* `PATCH /v1/sms/conversations/{id}` changes `status` (`open`, `closed`, or `spam`), `assigned_user_id`, `assigned_agent_id`, `recipient_timezone`, or `automation_status`.
* `POST /v1/sms/conversations/{id}/read` clears unread state.
* `POST /v1/sms/conversations/{id}/notes` adds an internal note that is never sent to the recipient.
* `POST /v1/sms/conversations/{id}/messages` queues a reply using the conversation's sender and recipient.
* `DELETE /v1/sms/conversations/{id}` immediately redacts message and note content. It is owner/admin-only and retains minimal billing/compliance facts.

A dashboard human reply pauses automation. New inbound messages do not resume it. Use an explicit `automation_status: "enabled"` update when handing the thread back to the agent.

## Agent automation [#agent-automation]

Automation is off by default and must be enabled for the organization defaults, the receiving number, and the conversation. Initial routing uses the number's assigned agent; `assigned_agent_id` can override it for one conversation.

Speko coalesces short inbound bursts, serializes turns with a conversation lease, supplies recent SMS history, and instructs the agent to answer in concise plain text. Failed model turns are not retried automatically, preventing duplicate replies and duplicate LLM charges.

STOP/START/HELP processing always runs before customer webhooks or agent execution. Suppression pauses automation and cannot be bypassed by assigning another sender.


# SMS on Speko (/sms)

Send text messages from your Speko phone numbers: prerequisites, carrier registration, timelines, and APIs.



Speko provides durable, compliant SMS messaging over Telnyx-managed US 10DLC numbers. Getting a number ready has two halves:

1. **Carrier registration (10DLC)** — a one-time compliance step required by US/Canadian carriers for every business that sends application-driven SMS from a local number. Live today, self-serve from the dashboard or [the API](/sms/api).
2. **Messaging enablement** — Speko provisions an organization-isolated Telnyx messaging profile, attaches each sender, and enables the `sms-messaging` workspace feature. Once the Numbers tab shows both campaign assignment and profile readiness, you can [send immediately or schedule messages](/sms/sending).

<Info>
  Do registration first—carrier review is the slow part. The Messages dashboard and 

  `/v1/sms`

   API reject outbound traffic until the selected number is attached to the organization profile and an approved campaign.
</Info>

## Prerequisites [#prerequisites]

Before you can register:

1. **SMS enabled for your workspace.** SMS Compliance is enabled per workspace by the Speko team. If you don't see **SMS Compliance** under [Settings](https://platform.speko.ai/settings), ask us — in your shared Slack channel or through your Speko contact — and we'll switch it on.
2. **A Speko-managed phone number.** Buy one under [Phone Numbers](https://platform.speko.ai/agents/phone-numbers) (requires business verification). Numbers imported over a SIP trunk keep messaging through your own carrier and can't be registered here.
3. **Your business details.** Legal name exactly as registered with the IRS, EIN (US tax ID), business address, website, and an authorized contact. Sole proprietors register without an EIN.

<Warning>
  The carriers verify your **legal name against the IRS record for your EIN** — they must match exactly. A recent rename or a DBA in the legal-name field is the most common reason verification fails.
</Warning>

## How long it takes [#how-long-it-takes]

| Step                          | Typical time              |
| ----------------------------- | ------------------------- |
| Brand identity verification   | Minutes to a few hours    |
| Campaign carrier review (TCR) | 1-7 business days         |
| Number assignment             | Minutes                   |
| **End to end**                | **Plan for about a week** |

If a step sits unusually long or gets rejected, contact the Speko team — we work with the carrier's compliance queue directly and can escalate a submitted campaign.

## The three registration steps [#the-three-registration-steps]

Registration lives at [Settings → SMS Compliance](https://platform.speko.ai/settings/sms-compliance):

| Step        | Where                                                                          | What it is                                      |
| ----------- | ------------------------------------------------------------------------------ | ----------------------------------------------- |
| 1. Brand    | [Brand tab](https://platform.speko.ai/settings/sms-compliance?tab=brand)       | Your verified business identity, submitted once |
| 2. Campaign | [Campaign tab](https://platform.speko.ai/settings/sms-compliance?tab=campaign) | What you send and how recipients consent        |
| 3. Numbers  | [Numbers tab](https://platform.speko.ai/settings/sms-compliance?tab=numbers)   | Attach your numbers to the approved campaign    |

<CardGroup cols="2">
  <Card title="Register (10DLC)" icon="shield-check" href="/sms/registration">
    Step-by-step walkthrough of brand, campaign, and number assignment.
  </Card>

  <Card title="Registration API" icon="code" href="/sms/api">
    Automate registration with the /v1/sms/10dlc endpoints.
  </Card>

  <Card title="Send messages" icon="messages-square" href="/sms/sending">
    Single, batch, scheduled, status, and cancellation APIs.
  </Card>

  <Card title="Shared inbox" icon="inbox" href="/sms/inbox">
    Human assignment, notes, agent takeover, and live updates.
  </Card>

  <Card title="Consent" icon="shield-check" href="/sms/consent">
    Consent records, quiet hours, STOP/START, and suppression.
  </Card>

  <Card title="Events" icon="webhook" href="/sms/webhooks">
    Signed customer webhooks and the dashboard event stream.
  </Card>

  <Card title="Build a phone agent" icon="phone" href="/guides/phone-agents">
    Buy a number, assign an agent, and handle calls end to end.
  </Card>
</CardGroup>


# Register for SMS (10DLC) (/sms/registration)

Register your brand and messaging campaign with US carriers so your Speko numbers are cleared to send SMS.



US carriers require every business that sends application-driven SMS from a local number to register under **10DLC** (10-digit long code): a verified **brand** (your business identity) plus an approved **campaign** (what you send and how people consent). You fill in two forms once, then assign your numbers.

Make sure you meet the [prerequisites](/sms#prerequisites) first — SMS enabled for your workspace, a Speko-managed number, and your business details.

## 1. Register your brand [#1-register-your-brand]

Open [Settings → SMS Compliance → Brand](https://platform.speko.ai/settings/sms-compliance?tab=brand) and complete the three sections:

| Section            | Fields                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| Business identity  | Legal name, Display name, Entity type, Industry, Tax ID / EIN, Website, Support email, Support phone |
| Business address   | Street, City, Country (US or Canada), State (Province for Canada), Postal code                       |
| Authorized contact | First name, Last name, Email, Phone                                                                  |

Notes:

* **Legal name** must match the IRS record for your EIN exactly — this is what the carriers verify. If you recently renamed your company, register under the name the IRS still has on file.
* **Entity type** options: Private company (for-profit), Public company (for-profit), Non-profit organization, Government entity, Sole proprietor. The Tax ID / EIN field is hidden for sole proprietors.
* Phone numbers must be in E.164 format (for example `+15551234567`).
* **Submit brand** saves and submits in one click. Identity verification usually completes in minutes to a few hours.

The status badge moves through **Draft → Under review → Verified**. If the carriers reject the brand, the badge shows **Action needed** with the rejection reasons — fix the details and resubmit.

<Tip>
  Statuses don't refresh on their own. Click **Resubmit brand** to pull the latest verification status from the carriers — it re-syncs your existing brand and is always safe to click.
</Tip>

### If verification fails [#if-verification-fails]

The usual cause is an identity mismatch: the legal name, EIN, or address doesn't match IRS records. Check the rejection reasons shown on the Brand tab, correct the details, and resubmit. If you believe the details are right (for example, a recent legal rename that hasn't propagated), contact the Speko team with your IRS EIN letter (CP 575 / SS-4) — we can appeal through the carrier compliance queue.

### Enhanced vetting (optional) [#enhanced-vetting-optional]

After the brand is submitted, an **Enhanced vetting** section appears. A third-party vetting score can raise your messaging throughput and unlock more use cases; the review takes 1-7 business days. It is never required — skip it unless you need higher volume.

## 2. Submit your messaging campaign [#2-submit-your-messaging-campaign]

The [Campaign tab](https://platform.speko.ai/settings/sms-compliance?tab=campaign) unlocks once your brand shows **Verified**. Describe what you send and how recipients consent:

* **Use case** — pick the closest match: Agents & franchises, Customer care, Account notifications, Two-factor authentication, Delivery notifications, Security alerts, Marketing, Polling & voting, Public service announcement, or Mixed. Appointment confirmations and reminders fit **Account notifications**.
* **Description** — what the messages are and who receives them.
* **Opt-in flow** — how a recipient consents. Example: "Customers book an appointment by phone and verbally agree to receive a confirmation text and reminder texts for their visit."
* **Keywords & auto-replies** — the START / HELP / STOP keywords are prefilled; write the three auto-reply messages. Include your brand name in each reply, and make the STOP reply confirm the opt-out.
* **Sample messages** — at least one, matching what you will actually send. Include your brand name and opt-out language:

```text
MoonAI: your visit is confirmed for Jul 3 at 5:00 PM at 123 Main St. Reply STOP to opt out.
```

* **Content & links** — flip the switches if your messages contain links or phone numbers. Links require an example URL. Privacy policy and terms URLs are optional but speed up review.

Click **Submit campaign**. The badge moves through **Draft → Under review → Active**. Carrier (TCR) review takes **1-7 business days** — if it's urgent, tell the Speko team after submitting and we can ask the carrier compliance team to expedite.

<Warning>
  Submit the campaign **once**. Unlike the brand button, resubmitting a campaign registers a brand-new campaign with the carriers — each one carries recurring carrier fees. Only resubmit after an actual rejection (**Action needed**), and after fixing the flagged details.
</Warning>

## 3. Assign your numbers [#3-assign-your-numbers]

Once the campaign is **Active**, open the [Numbers tab](https://platform.speko.ai/settings/sms-compliance?tab=numbers) and click **Assign** next to each number that should send. The badge moves from **Not assigned** through **Pending** to **On your campaign**, and the Overview tab confirms the workspace is cleared to send.

On the [Phone Numbers](https://platform.speko.ai/agents/phone-numbers) page, the SMS column tracks the same state: **Not configured → Pending → Assigned**.

### Shared brand [#shared-brand]

If Speko has enabled the shared 10DLC campaign for your workspace, the Overview tab offers **Assign a number** directly — your numbers ride Speko's registered brand while your own registration is optional or still in review. You can move numbers from the shared brand to your own campaign later with one click.

## What happens after registration [#what-happens-after-registration]

Your numbers are now legally cleared to send SMS in the US and Canada. Head to [Send messages](/sms/sending) for the current sending options, or [automate all of the above with the API](/sms/api).

<CardGroup cols="2">
  <Card title="Send messages" icon="messages-square" href="/sms/sending">
    Current sending status and the supported interim pattern.
  </Card>

  <Card title="Registration API" icon="code" href="/sms/api">
    The /v1/sms/10dlc endpoints behind every step on this page.
  </Card>
</CardGroup>


# Send SMS messages (/sms/sending)

Queue single, batch, and scheduled 10DLC messages and track delivery safely.



Every send is durable and asynchronous. Speko stores the message, compliance decision, campaign snapshot, and credit reservation before enqueueing it, then returns `202`. A response of `queued` or `accepted` never means carrier delivery.

## Send one message [#send-one-message]

```bash
curl -X POST https://api.speko.dev/v1/sms/messages \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: order-982-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number_id": "8f0e9a96-...",
    "to": "+12025550123",
    "text": "Acme: your order 982 is confirmed. Reply STOP to opt out.",
    "recipient_timezone": "America/New_York",
    "metadata": { "order_id": "982" }
  }'
```

The sender must belong to your workspace, be active and outbound-capable, show a ready messaging profile, and have an `ASSIGNED` approved campaign. You never provide a campaign or brand ID; Speko derives and snapshots both from the sender.

`Idempotency-Key` is required. Reusing the key with the same JSON returns the original message. Reusing it with different JSON returns `409 IDEMPOTENCY_CONFLICT`. Persist the key before calling Speko and reuse it after client timeouts.

## Schedule and quiet hours [#schedule-and-quiet-hours]

Add an RFC 3339 `send_at` up to 90 days ahead. Proactive traffic is allowed from 08:00 through 21:00 recipient local time. Speko resolves timezone from the active consent, conversation, request, or organization default and shifts work to the next valid boundary when needed.

The response exposes both `requested_send_at` and `effective_send_at`. A proactive send with no resolvable IANA timezone fails with `RECIPIENT_TIMEZONE_REQUIRED`. Consent, suppression, readiness, credits, and quiet hours are rechecked when scheduled work becomes due.

## Send a batch [#send-a-batch]

`POST /v1/sms/batches` accepts one sender and 1–1,000 recipient rows:

```json
{
  "from_phone_number_id": "8f0e9a96-...",
  "send_at": "2026-09-03T14:00:00Z",
  "recipients": [
    {
      "to": "+12025550123",
      "text": "Acme: your appointment is tomorrow at 10 AM.",
      "recipient_timezone": "America/New_York",
      "metadata": { "appointment_id": "apt_1" }
    }
  ]
}
```

Use a batch-level `Idempotency-Key`. Sender or envelope errors reject the whole request. Recipient-specific issues create `rejected` message rows while valid rows continue. Batch traffic is always proactive and cannot use the 24-hour conversational reply exception.

Read progress at `GET /v1/sms/batches/{batch_id}` and row results at `GET /v1/sms/batches/{batch_id}/messages`. Cancel remaining queued/scheduled rows with `POST /v1/sms/batches/{batch_id}/cancel`.

## Status lifecycle [#status-lifecycle]

| Status                 | Meaning                                                           |
| ---------------------- | ----------------------------------------------------------------- |
| `queued` / `scheduled` | Durable and waiting for processing or its effective time          |
| `submitting`           | Provider submission has begun; no longer cancelable               |
| `accepted` / `sent`    | Accepted by Telnyx or handed to the carrier                       |
| `delivered`            | Authoritative delivery receipt received                           |
| `delivery_failed`      | Carrier reported a terminal delivery failure                      |
| `rejected`             | Rejected locally before submission                                |
| `submission_unknown`   | The request may have reached Telnyx; Speko will not blindly retry |
| `canceled`             | Canceled before provider submission                               |
| `received`             | Inbound message                                                   |

Poll `GET /v1/sms/messages/{message_id}`, subscribe to [signed webhooks](/sms/webhooks), or use `GET /v1/sms/stream` for a live dashboard. Delivery events are idempotent and later authoritative receipts can repair out-of-order state.

## Limits [#limits]

* SMS only; MMS is not accepted.
* Recipients must be E.164.
* Text is limited to 1,600 characters.
* Metadata allows 50 keys and 8 KB serialized.
* Only `queued` and `scheduled` messages can be canceled.


# SMS events and live stream (/sms/webhooks)

Receive signed lifecycle webhooks and resume live dashboard updates safely.



Workspace webhook endpoints can subscribe to `sms.received`, `sms.accepted`, `sms.sent`, `sms.delivered`, `sms.delivery_failed`, `sms.submission_unknown`, `sms.opted_out`, and `sms.opted_in`.

Organization-wide endpoints receive every SMS event. Agent-filtered endpoints receive only events for conversations associated with one of their configured agents. SMS events do not require a voice agent or session ID.

Payloads include message text by default. Set `contentMode: "metadata_only"` on the webhook endpoint to omit it. Webhook requests are signed with the endpoint/workspace Standard Webhooks secret; deduplicate on `webhook-id` and return `2xx` quickly.

Message bodies, consent proof, and raw webhook bodies are excluded from logs, traces, analytics, and error reporting.

## Live event stream [#live-event-stream]

`GET /v1/sms/stream` is a server-sent event stream for dashboard clients. Event data includes `message_id`, `conversation_id`, `status`, and `occurred_at`. On reconnect, send the last SSE ID in `Last-Event-ID`; Speko catches up from PostgreSQL before subscribing to live Redis events.

The stream is a UI synchronization channel, not a replacement for signed customer webhooks or message reads. Re-read the message or conversation after each event.


# Telnyx Call Control handoff (/telnyx-handoff)

Keep running inbound calls on your own Telnyx Call Control app and hand a live call to a Speko agent with a single SIP transfer.



If you already run your inbound calls on **Telnyx Call Control** — your own webhook app answering calls, doing IVR, routing, and business logic — you don't have to move that to Speko. Instead, at the moment you want a Speko voice agent to take over, your app **transfers the live call to a per-agent SIP address**. The Speko agent answers and handles the rest of the conversation with its full prompt, tools, and knowledge base.

<Warning>
  **Early access.** Speko enables Call Control handoff per workspace. Ask us in your shared Slack channel or through your Speko contact to turn it on, then each agent gets a **Telnyx handoff** tab in the dashboard.
</Warning>

## How it works [#how-it-works]

Your Call Control app keeps the call until you decide to hand it off. When it does, it issues a standard Telnyx `transfer` (full handoff — your leg drops) or `dial`+`bridge` (you stay on the leg) to the agent's SIP URI.

1. Your Call Control app handles the inbound call as it does today.
2. When you want the Speko agent, you call the Telnyx **transfer** action with `to` set to the agent's handoff SIP URI and an `X-Speko-Handoff` custom header carrying the agent's token.
3. Telnyx sends the INVITE to Speko's LiveKit SIP endpoint from Telnyx's SIP signaling IPs — the same ones Speko already allowlists for its inbound trunk, so no SIP auth is required. Speko reads the per-agent handoff token off the header and dispatches that agent into the call.
4. From there the pipeline — speech-to-text, your model, text-to-speech, tools, recording, transcripts, and the post-call report — is identical to a phone call. The caller's number and any `Diversion` (forwarded-from) header carry through.

Because it's the same agent runtime, an agent you already built for the phone works over a handoff with no changes.

## Enable it on an agent [#enable-it-on-an-agent]

1. Open the agent, go to the **Telnyx handoff** tab, and click **Enable handoff**.
2. Copy the **SIP URI** (`sip:<token>@<your-sip-host>`) — that's everything you need.

The token is both the routing key and a bearer secret — treat it like an API key. Only calls arriving from Telnyx's signaling IPs can reach the endpoint, and the token identifies the agent, so keep it private. If it leaks, click **Rotate token**; the old URI stops routing immediately.

## Transfer a call [#transfer-a-call]

From your Call Control app, on the leg you want to hand off:

```bash
POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/transfer
Authorization: Bearer <YOUR_TELNYX_API_KEY>
Content-Type: application/json

{
  "to": "sip:<agent-handoff-token>@<your-sip-host>",
  "custom_headers": [
    { "name": "X-Speko-Handoff", "value": "<agent-handoff-token>" },
    { "name": "X-Speko-Dialed-Number", "value": "+15551230100" }
  ]
}
```

Notes:

* **No SIP auth is needed.** The INVITE reaches Speko over your Telnyx SIP connection, and Telnyx's signaling IPs are already allowlisted on Speko's inbound trunk — the same path your Speko phone numbers use.
* **`X-Speko-Handoff` is required.** Its value is the agent's handoff token; it's how Speko selects the agent (the token also appears in the URI user-part for readability).
* **`X-Speko-Dialed-Number` is optional but recommended.** Set it to the E.164 number the caller originally dialed on your side. A transferred INVITE doesn't carry your original DID, so without this header the Speko session records no dialed number — with it, the number is recorded on the session (visible in session metadata and your `call.report` payloads), which makes multi-number auditing on your side much easier. It is informational only: it never selects the agent (the handoff token does) and never sets the call's caller ID. Values that aren't valid E.164 are ignored.
* To **stay on the call** (e.g. to listen or take it back) instead of fully handing off, `dial` a new leg to the same SIP URI and `bridge` it rather than using `transfer`.

## Getting the analysis back [#getting-the-analysis-back]

After the handoff call ends, Speko delivers the transcript, summary, and any extracted fields to matching workspace endpoints subscribed to `call.report`, exactly as it does for phone calls — so your system can pick up where the agent left off. See [Workspace webhooks](/docs/guides/webhooks) for setup.

## Choosing handoff vs. porting your number [#choosing-handoff-vs-porting-your-number]

Use Call Control handoff when you want to **keep your existing Telnyx call flow** and only delegate part of a call to a Speko agent. If instead you want Speko to own the whole inbound number, point the number at Speko directly — talk to us about number setup.


# WhatsApp Calling on Speko (/whatsapp)

Let people call your Speko voice agent over WhatsApp: how it works, what is supported today, and how to get on the beta.



Speko can run the same voice agent that answers PSTN phone calls over **WhatsApp voice calls**. A caller taps the call button in your business WhatsApp chat, and your Speko agent answers with the same prompt, voice, tools, and post-call reporting it uses on the phone.

<Warning>
  **Beta.** WhatsApp Calling is in early access. Speko enables it per workspace and pairs it with a WhatsApp-calling number mapped to your agent. Ask us in your shared Slack channel or through your Speko contact to join the beta.
</Warning>

## Why WhatsApp [#why-whatsapp]

WhatsApp calls are free for the caller and ride the app they already live in, so there is no international long-distance cost and no number to dial. For teams whose customers reach them on WhatsApp first, it removes the friction of "call this number" entirely.

## How it works [#how-it-works]

WhatsApp calling reuses Speko's existing agent runtime end to end. Only the call transport is new.

1. A WhatsApp user places a call to your business number.
2. Meta's WhatsApp Cloud API sends a `calls` **connect** webhook, carrying the caller's audio offer, to Speko.
3. Speko resolves the number to your agent (the same `agentId` mapping used for phone numbers), then accepts the call through LiveKit's WhatsApp Connector.
4. LiveKit bridges the WhatsApp audio into a room and dispatches your agent worker. From there the pipeline (speech-to-text, your model, text-to-speech, tools, recording, transcripts, and the post-call report) is identical to a phone call.

Because the agent is the same, an agent you have already built for the phone answers WhatsApp calls with no prompt or tool changes.

## What works today [#what-works-today]

| Capability                                                                 | Status                                                                |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Inbound (a user calls your agent on WhatsApp)                              | Supported in beta                                                     |
| Same agent, prompt, voice, tools, transcripts, recording, post-call report | Yes                                                                   |
| Outbound (your agent calls a WhatsApp user)                                | In development; requires the recipient to grant call permission first |
| Transfer a WhatsApp call to a phone number (PSTN)                          | Not supported (see limits)                                            |

## Prerequisites [#prerequisites]

1. **WhatsApp calling enabled for your workspace.** This is a beta flag Speko turns on per workspace, the same way SMS is enabled. Contact us to get added.
2. **A WhatsApp-calling number mapped to an agent.** Speko provisions the WhatsApp-enabled number and maps it to your persisted agent (`agentId`), exactly like an inbound phone number. If you already run a WhatsApp Business number, tell us and we will coordinate the connection.
3. **A persisted agent.** Build one first — see [Build a phone agent](/guides/phone-agents). The same agent answers WhatsApp calls.

## Limits [#limits]

* **On-net only.** WhatsApp calls stay inside WhatsApp. A WhatsApp call cannot be bridged or transferred to a regular phone number, and a phone call cannot be forwarded into WhatsApp. This is a WhatsApp platform rule, not a Speko limit.
* **No DTMF or SIP-style transfer.** Escalation to a human happens inside the same conversation, not via a phone transfer.
* **Outbound needs consent.** WhatsApp requires a user to grant call permission before a business can call them, so outbound is a follow-up channel, not a cold-call channel.
* **Beta availability.** The underlying connector is in beta and enabled per project; availability and regions can change.

<CardGroup cols="2">
  <Card title="Build a phone agent" icon="phone" href="/guides/phone-agents">
    Create the agent that also answers WhatsApp calls, and wire up webhooks and reports.
  </Card>

  <Card title="SMS on Speko" icon="messages-square" href="/sms">
    The other messaging channel: register a number for 10DLC and send texts.
  </Card>
</CardGroup>


# Generate responses (/relay/llm/responses)

POST /v1/llm/responses — one request shape for every language model in the catalog.



## Request [#request]

`POST https://router.speko.dev/v1/llm/responses`

```json
{
  "routing": { "mode": "auto", "objective": "quality" },
  "input": [
    { "type": "message", "role": "system", "content": [{ "type": "text", "text": "You are a concise assistant." }] },
    { "type": "message", "role": "user", "content": [{ "type": "text", "text": "Summarize our return policy." }] }
  ],
  "tools": [
    { "name": "lookup_policy", "description": "Fetch a policy document", "parameters": { "type": "object", "properties": { "topic": { "type": "string" } } } }
  ],
  "reasoning_effort": "medium",
  "max_output_tokens": 500,
  "stream": false
}
```

<ParamField name="routing" type="object">
  The [routing object](/relay/routing). LLM entries differ in capabilities — auto mode only considers providers that support what your request uses (tools, structured output).
</ParamField>

<ParamField name="input" type="Item[]">
  The conversation so far. &#x2A;*There is no server-side conversation state and no `previous_response_id`** — resend the full history on every request.
</ParamField>

<ParamField name="tools" type="FunctionTool[]">
  Optional function tools: `name` (required, unique), `description`, `parameters` (JSON Schema, passed through).
</ParamField>

<ParamField name="response_format" type="object">
  Optional structured output: `{"type": "json_schema", "name": "...", "schema": {...}, "strict": true}`.
</ParamField>

<ParamField name="max_output_tokens" type="number">
  Must be positive. Required because an unbounded generation cannot be priced at admission. This is the hard limit for hidden reasoning tokens plus visible output tokens.
</ParamField>

<ParamField name="reasoning_effort" type="string">
  Optional. One of `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. When supplied, auto routing considers only models that can honor that control, including models that can explicitly disable reasoning for `none`. Omit it to place no reasoning constraint on routing.
</ParamField>

<ParamField name="temperature" type="number">
  0–2. Cannot be combined with an enabled `reasoning_effort`.
</ParamField>

<ParamField name="top_p" type="number">
  Greater than 0, at most 1. Cannot be combined with an enabled `reasoning_effort`.
</ParamField>

<ParamField name="stream" type="boolean">
  `true` switches the response to [server-sent events](/relay/llm/streaming).
</ParamField>

## Input items [#input-items]

`input` is a list of items — a **closed union** on `type`. Fields belonging to a different item type are rejected, never ignored.

| Type              | Fields                                                                                               | Direction                  |
| ----------------- | ---------------------------------------------------------------------------------------------------- | -------------------------- |
| `message`         | `role` (`system` \| `user` \| `assistant`), `content` (list of `{"type":"text","text":"..."}` parts) | input and output           |
| `function_call`   | `call_id`, `name`, `arguments` (JSON encoded as a string)                                            | input (history) and output |
| `function_result` | `call_id`, `result` (opaque text, may be empty)                                                      | **input only**             |
| `structured_json` | `json` (raw JSON value)                                                                              | **output only**            |

There is no `tool` role — tool results are `function_result` items. Output messages are always `assistant`-authored.

## Response [#response]

```json
{
  "id": "resp_rreq_...",
  "route": { "provider": "openai", "model": "gpt-5.2", "region": "us-east-1", "attempt_id": "ratt_..." },
  "output": [
    { "type": "message", "role": "assistant", "content": [{ "type": "text", "text": "Returns are accepted within 30 days..." }] }
  ],
  "stop_reason": "stop",
  "usage": { "input_tokens": 180, "cached_input_tokens": 96, "output_tokens": 64, "reasoning_tokens": 12 }
}
```

<ResponseField name="id" type="string">
  Speko-minted: `resp_` + the request ID. Provider response and conversation IDs never appear.
</ResponseField>

<ResponseField name="stop_reason" type="string">
  `stop`, `max_output_tokens`, or `tool_call`.
</ResponseField>

<ResponseField name="usage" type="object">
  When the provider reports a reasoning split, token counts are **mutually exclusive lines**: `cached_input_tokens` are not repeated inside `input_tokens`, and `reasoning_tokens` are not repeated inside `output_tokens`. If a provider does not report a reasoning split, its inclusive output count remains in `output_tokens`. See [Usage](/relay/usage).
</ResponseField>

## Tool calling flow [#tool-calling-flow]

1. Send your messages plus `tools`. If the model decides to call one, the response has `stop_reason: "tool_call"` and a `function_call` item in `output`.
2. Run the function yourself.
3. Resend the full history — including the `function_call` item — plus a `function_result` item with the same `call_id`.
4. The model continues from there.


# Streaming responses (/relay/llm/streaming)

Server-sent events from /v1/llm/responses with stream true.



## Enabling [#enabling]

Set `"stream": true` on a [response request](/relay/llm/responses). The response becomes `Content-Type: text/event-stream`.

```bash
curl -N https://router.speko.dev/v1/llm/responses \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": { "mode": "explicit", "provider": "cerebras", "model": "llama-4-maverick-17b-128e-instruct" },
    "input": [{ "type": "message", "role": "user", "content": [{ "type": "text", "text": "Stream me a haiku." }] }],
    "max_output_tokens": 60,
    "stream": true
  }'
```

## Event set [#event-set]

The event names form a closed set:

| Event                                    | Payload                                                   |
| ---------------------------------------- | --------------------------------------------------------- |
| `response.created`                       | `{"id": "resp_...", "route": {...}}` — the admitted route |
| `response.item.added`                    | A new output item has started                             |
| `response.text.delta`                    | Incremental message text                                  |
| `response.function_call_arguments.delta` | Incremental JSON for a tool call's arguments              |
| `response.item.completed`                | The current output item is complete                       |
| `response.completed`                     | Terminal: final `stop_reason` and `usage`                 |
| `error`                                  | Terminal: the standard [error envelope](/relay/errors)    |

**Exactly one terminal event** — `response.completed` or `error` — ends every stream, never both and never neither. If the connection closes without one, the stream was truncated; discard partial output or retry with the same idempotency key.

## Heartbeats [#heartbeats]

While a provider is thinking, the Router emits SSE comment lines as keepalives:

```
: heartbeat
```

Ignore them; they exist to keep intermediaries from idling out the connection.

## Failover on streams [#failover-on-streams]

`response.created` is deliberately **not** counted as the start of output: in auto mode, a provider failure after `response.created` but before the first content event still fails over transparently to the next provider. Once a `response.text.delta` (or any output item) has arrived, failures terminate the stream with an `error` event instead.


# Transcribe audio (/relay/stt/batch)

POST /v1/stt/transcriptions — transcribe an audio file in one request.



## Request [#request]

`POST https://router.speko.dev/v1/stt/transcriptions`

The body is `multipart/form-data` with **exactly two parts, in this order**:

1. `request` — a JSON document (at most 1 MiB)
2. `audio` — WAV containing PCM s16le, or raw PCM s16le with an `audio` object in the `request` part

Part order is load-bearing: the [idempotency content hash](/relay/idempotency) is defined over the parts in this order, and extra or reordered parts are rejected.

```bash
curl -s https://router.speko.dev/v1/stt/transcriptions \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request={"routing":{"mode":"auto","objective":"quality"},"language":"en"};type=application/json' \
  -F 'audio=@interview.wav;type=audio/wav'
```

The request is held open until the transcript is ready. For recordings longer
than a few minutes, or larger than the selected model's [limit](#limits), use
[transcription jobs](/relay/stt/jobs) instead — they take audio of any length
and deliver to a webhook.

### The `request` part [#the-request-part]

<ParamField name="routing" type="object">
  The [routing object](/relay/routing). Omit for `auto`/`balanced`.
</ParamField>

<ParamField name="language" type="string">
  Optional language hint, for example `en` or `es-MX`. Without it the provider
  detects the language where it can.
</ParamField>

<ParamField name="options" type="object">
  Optional [transcription options](#the-options-object).
</ParamField>

<ParamField name="audio" type="object">
  Required only for raw PCM uploads. Set `encoding` to `pcm_s16le` and provide
  `sample_rate_hz` and `channels`. For WAV uploads, the Router derives these
  values from the container.
</ParamField>

### The `options` object [#the-options-object]

Options are provider-neutral asks. They **fail closed**: a request routed to a
model that cannot honor an option is refused with `400 capability_unsupported`
naming the option, never answered `200` with the feature silently missing —
a diarization request served by a model that cannot diarize is
indistinguishable from a one-speaker recording, so nobody would ever notice.
`GET /v1/models` advertises each STT model's `capabilities`; in automatic
routing, models lacking a requested capability are skipped.

<ParamField name="diarization" type="boolean">
  Label each segment with the speaker who said it. Segments gain a `speaker`
  field carrying the provider's own label verbatim (`"0"`, `"A"`,
  `"speaker_1"`).
</ParamField>

<ParamField name="keywords" type="string[]">
  Up to 100 terms of at most 64 characters to bias recognition toward — names,
  products, jargon. Translated to each vendor's own mechanism (Deepgram
  `keyterm`, AssemblyAI `keyterms_prompt`, ElevenLabs `keyterms`, Soniox
  context terms, OpenAI prompt text).
</ParamField>

<ParamField name="noise_reduction" type="boolean">
  Ask the provider to clean the audio before transcribing. No currently routed
  STT model advertises it, so setting it is refused today.
</ParamField>

<ParamField name="word_timestamps" type="boolean">
  Return per-word timings. The response gains a `words` array of
  `{ text, start_ms, end_ms }`, in reading order, measured from the start of
  the audio — what a subtitle builder needs. Served by `gemini-3.5-transcribe`
  today (pin it with explicit routing; `GET /v1/models?path=batch` shows
  `word_timestamps` per model). Gemini cannot combine it with `keywords`, so
  that pair is refused `capability_unsupported` naming `keywords`.
</ParamField>

<ParamField name="provider_options" type="object">
  A vendor's own settings, namespaced by provider name and allow-listed per
  provider — for example `{"deepgram": {"numerals": true}}`. Settings for a
  provider the request does not reach are ignored, so you can tune several
  providers and let routing decide. Scalars only; at most 8 providers and 16
  keys each. Settings the Router owns (`model`, `language`, `encoding`,
  `diarize`, credentials, …) are rejected by name.
</ParamField>

```json
{
  "routing": {"mode": "explicit", "provider": "deepgram", "model": "nova-3"},
  "language": "en",
  "options": {
    "diarization": true,
    "keywords": ["Speko", "Router"],
    "provider_options": {"deepgram": {"numerals": true, "smart_format": true}}
  }
}
```

## Response [#response]

```json
{
  "text": "Good morning everyone, let's get started.",
  "segments": [
    { "text": "Good morning everyone, let's get started.", "start_ms": 0, "end_ms": 2900, "speaker": "0" }
  ],
  "route": { "provider": "deepgram", "model": "nova-3", "region": "us-east-1", "attempt_id": "ratt_..." },
  "usage": { "duration_ms": 3000 }
}
```

With `"options": {"word_timestamps": true}` on `gemini-3.5-transcribe`:

```json
{
  "text": "Salom dunyo",
  "segments": [{ "text": "Salom dunyo", "start_ms": 120, "end_ms": 1000 }],
  "words": [
    { "text": "Salom", "start_ms": 120, "end_ms": 480 },
    { "text": "dunyo", "start_ms": 510, "end_ms": 1000 }
  ],
  "route": { "provider": "gemini", "model": "gemini-3.5-transcribe", "region": "us-east-1", "attempt_id": "ratt_..." },
  "usage": { "duration_ms": 1000 }
}
```

<ResponseField name="text" type="string">
  The full transcript. May legitimately be empty for silent audio.
</ResponseField>

<ResponseField name="segments" type="object[]">
  Time-aligned utterances. `start_ms`/`end_ms` are non-negative, ordered
  ranges. `speaker` is present only when `diarization` was requested. Some
  models return whole-text only, in which case `segments` is omitted.
</ResponseField>

<ResponseField name="words" type="object[]">
  Per-word timings, present only when you asked for `word_timestamps`.
  `start_ms`/`end_ms` are non-negative, ordered, and measured from the start
  of the audio. `speaker` appears on each word only when `diarization` was
  also requested and the provider labels speakers.
</ResponseField>

<ResponseField name="route" type="object">
  Which provider, model, and Speko region served the request, and the attempt
  ID. `model` is the catalog id you can pin; when the provider's pre-recorded
  API uses a different model name internally (Soniox `stt-async-v5` behind
  `stt-rt-v5`, ElevenLabs `scribe_v2` behind `scribe_v2_realtime`), you still
  see the catalog id.
</ResponseField>

<ResponseField name="usage" type="object">
  `duration_ms` — the audio duration metered: the duration the provider reports
  processing, capped at the duration of the audio you sent as parsed from the
  container, never a caller-declared value.
</ResponseField>

The same route facts are echoed in the `Speko-Request-ID`, `Speko-Provider`,
`Speko-Model` and `Speko-Region` response headers.

## How your audio is transcribed [#how-your-audio-is-transcribed]

Every STT model in the catalog is served one of two ways, and
`GET /v1/models?path=batch` tells you which:

* **Pre-recorded route.** The upload is sent as one file to the provider's
  batch/asynchronous transcription API — Deepgram `/v1/listen`, AssemblyAI's
  Transcripts API, Soniox async, ElevenLabs Scribe, OpenAI
  `/v1/audio/transcriptions`, and so on. The whole recording is transcribed in
  one call, bounded by that API's documented limits. These are the models
  listed under `path=batch`, and the only models
  [transcription jobs](/relay/stt/jobs) will use.
* **Realtime-only.** A few models exist only as live sockets (Deepgram Flux,
  Cartesia `ink-2`, OpenAI `gpt-live-transcribe`, Palabra). The Router still
  transcribes short uploads on them by replaying the audio into the socket,
  bounded to **60 seconds** — the most a realtime socket reliably keeps up
  with when fed faster than real time. They are omitted from `path=batch` and
  refused for jobs.

Either way the Router checks that the transcript actually covers the audio:
a response whose last timed segment stops well short of the recording while
speech continues is refused as a retryable `provider_error` rather than
returned — and, in automatic mode, triggers [failover](/relay/routing#automatic-failover).

## Limits [#limits]

There is no universal 25 MiB transcription cap. Each model's limit is the bound
of its provider's pre-recorded API on one upload — decoded PCM bytes, duration,
or both. Query `GET /v1/models?path=batch` and read `batch_audio_limits` for the
authoritative values in your region. Current limits:

| Provider / model                                                                                  | One upload accepts                         | Notes                                                                                                   |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Deepgram `nova-3`, `nova-3-medical`, `nova-2`, `base-phonecall`                                   | 2 GiB and 2 hours                          | Deepgram bounds processing time, not duration; 2 h keeps well inside it                                 |
| AssemblyAI `universal-3-5-pro`, `universal-streaming-english`, `universal-streaming-multilingual` | 2.2 GB and 10 hours                        | Mono only                                                                                               |
| Soniox `stt-rt-v5`                                                                                | 5 hours                                    | Served by `stt-async-v5`; no byte limit published                                                       |
| ElevenLabs `scribe_v2_realtime`                                                                   | 2 GiB and 10 hours                         | Served by `scribe_v2`; mono only                                                                        |
| OpenAI `gpt-transcribe`, `gpt-realtime-whisper`                                                   | **25 MB** and 30 minutes                   | 24 kHz mono only — about 8 minutes of audio per upload; `gpt-realtime-whisper` is served by `whisper-1` |
| Cartesia `ink-whisper`                                                                            | 1 GiB and 2 hours                          | Mono only; `ink-2` has no batch API                                                                     |
| xAI `grok-stt`                                                                                    | 500 MB and 2 hours                         | Mono only                                                                                               |
| Modulate `velma-2-stt-streaming`, `velma-2-stt-streaming-english-v2`                              | **100 MB** and 100 minutes                 | About 52 minutes of 16 kHz mono                                                                         |
| Smallest `pulse`                                                                                  | 250 MB and **10 minutes**                  | Mono only                                                                                               |
| Hamsa `s3`, `s2`                                                                                  | 500 MB and 60 minutes                      | Mono 16 kHz; jobs only (the provider fetches audio by URL)                                              |
| Alibaba `qwen3-asr-flash-realtime`                                                                | 2 GiB and 12 hours                         | Mono 8/16 kHz; jobs only (the provider fetches audio by URL)                                            |
| Google `chirp_3`                                                                                  | 60 seconds and 7,847,936 decoded PCM bytes | Google's 10 MB synchronous request limit, allowing for base64 expansion                                 |
| Deepgram `flux-*`, Cartesia `ink-2`, OpenAI `gpt-live-transcribe`, Palabra `default`              | 60 seconds                                 | Realtime-only; not listed under `path=batch`                                                            |

On this endpoint a recording over the limit is refused, not split:

* With automatic routing, models that cannot accept the recording are skipped. If no compatible model remains, the Router returns `413 payload_too_large` before admission or provider contact.
* With explicit routing, a recording over the selected model's limit returns `413 payload_too_large` before admission or provider contact — the hint names the limit and suggests `GET /v1/models?path=batch`.
* Recordings that exceed every model's limit belong on [transcription jobs](/relay/stt/jobs), which chunk them.

Other bounds:

* A deployment may apply an additional safety ceiling. This is an operational override, not a provider capability, so it is not included in `batch_audio_limits`.
* Batch audio is staged on temporary disk. If the Router task has no staging capacity, it returns retryable `429 concurrency_exhausted`; this is capacity pressure, not a file-size limit.
* The canonical WAV transport has a format boundary of 4,294,967,258 decoded PCM bytes (about 4 GiB) for every provider.
* An unparseable or unsupported audio container returns `415 unsupported_media`; so does a rate or channel layout the pinned model does not accept — the hint lists what it does.
* The whole request body must complete within the 2-minute read deadline.
* Metering is by audio duration, rounded up to whole seconds. There is deliberately no usage header on STT responses — the usage object in the body is authoritative.
* In auto mode a provider failure before results triggers transparent [failover](/relay/routing#automatic-failover).


# Transcription jobs (/relay/stt/jobs)

POST /v1/stt/transcriptions/jobs — transcribe recordings of any length asynchronously, delivered to a signed webhook.



Transcription jobs are the asynchronous counterpart of
[`POST /v1/stt/transcriptions`](/relay/stt/batch). You upload a recording,
get a `job_id` back immediately, and receive the finished transcript at a
webhook you control — or fetch it with `GET`. Use jobs when any of these is
true:

* the recording is longer than a few minutes, or larger than the selected
  model's [batch limit](/relay/stt/batch#limits) — jobs split the audio into
  provider-sized chunks and stitch the results into one transcript;
* you do not want to hold an HTTP request open for the duration of the
  transcription;
* you want delivery to be retried durably if your receiver is briefly down.

Every job is transcribed through the provider's **pre-recorded (batch) API**,
never through a realtime socket, and every chunk is admitted, metered, and
billed like an ordinary request. There is no separate pricing for jobs.

## Submit a job [#submit-a-job]

`POST https://router.speko.dev/v1/stt/transcriptions/jobs`

The body is `multipart/form-data` with **exactly two parts, in this order** —
the same shape as the synchronous endpoint plus a `webhook` object in the
`request` part:

1. `request` — a JSON document (at most 1 MiB)
2. `audio` — WAV containing PCM s16le, or raw PCM s16le with an `audio` object
   in the `request` part

```bash
curl -s https://router.speko.dev/v1/stt/transcriptions/jobs \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request={
        "routing": {"mode": "auto", "objective": "quality"},
        "language": "en",
        "options": {"diarization": true},
        "webhook": {"url": "https://example.com/hooks/speko"}
      };type=application/json' \
  -F 'audio=@board-meeting.wav;type=audio/wav'
```

An `Idempotency-Key` header is required. Resubmitting the same key with the
same parts returns the original job rather than creating a second one, so a
client that loses the 202 can safely retry the upload. See
[Idempotency](/relay/idempotency).

### The `request` part [#the-request-part]

<ParamField name="routing" type="object">
  The [routing object](/relay/routing). Omit for `auto`/`balanced`. Only
  models with a pre-recorded route are candidates for jobs; an explicit pin to
  a realtime-only model (for example `deepgram/flux-general-en`) is refused
  with `400 capability_unsupported`. `GET /v1/models?path=batch` lists the
  eligible models.
</ParamField>

<ParamField name="language" type="string">
  Optional language hint, for example `en` or `es-MX`. Without it the
  provider detects the language.
</ParamField>

<ParamField name="options" type="object">
  Optional [transcription options](/relay/stt/batch#the-options-object):
  `diarization`, `keywords`, `noise_reduction`, `word_timestamps`, and
  `provider_options`. The same capability rules apply as on the synchronous
  endpoint.
</ParamField>

<ParamField name="audio" type="object">
  Required only for raw PCM uploads. Set `encoding` to `pcm_s16le` and provide
  `sample_rate_hz` and `channels`. For WAV uploads the Router derives these
  values from the container.
</ParamField>

<ParamField name="webhook" type="object">
  Where to deliver the finished job. `url` is required and must be `https://`
  on port 443 with no credentials in the URL, resolving to a public address.
  Redirects are not followed. The same URL is validated again at delivery
  time.
</ParamField>

### Response — `202 Accepted` [#response--202-accepted]

```json
{
  "job_id": "sttjob_rPg1RaFE0wNC368zk3hYcc3u",
  "status": "queued",
  "created_at": "2026-08-26T15:34:35.967331Z",
  "audio": {
    "duration_ms": 1823170,
    "pcm_bytes": 58341464,
    "sample_rate_hz": 8000,
    "channels": 2
  },
  "webhook": {
    "url": "https://example.com/hooks/speko",
    "secret": "whsec_2sZ63U4vkNwJP0dj7IVEr3wM57KyUFlv8tRAtsoDuZk",
    "delivered": false,
    "attempts": 0
  }
}
```

<ResponseField name="job_id" type="string">
  The job identifier, `sttjob_`-prefixed. Use it to poll and as the
  idempotency key for your own processing of deliveries.
</ResponseField>

<ResponseField name="audio" type="object">
  The trusted media facts the Router parsed from your upload — duration,
  decoded PCM bytes, rate, channels. These, not any caller-declared values,
  drive chunk planning and metering.
</ResponseField>

<ResponseField name="webhook.secret" type="string">
  The per-job signing secret, `whsec_`-prefixed. **It is returned exactly
  once, in this response**, and never stored by Speko — later documents omit
  it. Store it with the job id; you need it to
  [verify deliveries](#verifying-a-delivery).
</ResponseField>

The upload is stored in a regional bucket only for as long as the job runs;
it is deleted as soon as the transcript is stored or the job fails.

### Submit errors [#submit-errors]

| Status | `error.code`             | Meaning                                                                                                                                                                             |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`        | Malformed parts, missing `Idempotency-Key`, missing or invalid `webhook.url` (non-HTTPS, private address, credentials in URL).                                                      |
| 400    | `capability_unsupported` | The pinned model has no pre-recorded route, or cannot honor a requested option such as `diarization`. The hint names the alternative.                                               |
| 413    | `payload_too_large`      | Upload over the deployment ceiling (2 GiB by default), or no eligible model can accept any chunking of the audio.                                                                   |
| 415    | `unsupported_media`      | Not a WAV/PCM s16le container, or the pinned model does not accept this rate/channel layout.                                                                                        |
| 429    | `concurrency_exhausted`  | Your organization already has the maximum number of jobs in flight (64) or in-flight audio (32 GiB). Wait for jobs to finish; this is a per-organization ceiling, not a rate limit. |

Credit is **not** checked at submit. It is priced and spent where every other
request spends it — at admission, per chunk — so an organization out of credit
receives a job that fails at its first chunk with `insufficient_credit`,
delivered to the webhook, rather than a rejection at submit.

## Fetch a job [#fetch-a-job]

`GET https://router.speko.dev/v1/stt/transcriptions/jobs/{job_id}`

```bash
curl -s https://router.speko.dev/v1/stt/transcriptions/jobs/sttjob_rPg1RaFE0wNC368zk3hYcc3u \
  -H "Authorization: Bearer $SPEKO_API_KEY"
```

Returns the **job document** — the same JSON that is POSTed to your webhook,
so one decoder serves both. `result` is present once the job has completed;
`error` once it has failed. A job id that does not belong to your
organization answers `404 invalid_request`.

### Job lifecycle [#job-lifecycle]

```
queued → transcribing → delivering → completed
                     ↘             ↘ failed
```

| `status`       | Meaning                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `queued`       | Accepted; waiting for a regional worker.                                                                                   |
| `transcribing` | Chunks are being planned, admitted and transcribed.                                                                        |
| `delivering`   | Transcript stored; webhook delivery in progress.                                                                           |
| `completed`    | Terminal. `result` is populated. `webhook.delivered` says whether your receiver accepted it.                               |
| `failed`       | Terminal. `error` carries the normalized code and message. Chunks that had already finished were billed; nothing else was. |

A transient provider failure re-queues the whole job up to three times;
chunks that already finished are reused, not re-billed. A non-retryable
failure (`payload_too_large`, `capability_unsupported`, `insufficient_credit`)
fails the job immediately.

## The job document [#the-job-document]

```json
{
  "job_id": "sttjob_rPg1RaFE0wNC368zk3hYcc3u",
  "status": "completed",
  "created_at": "2026-08-26T15:34:35.967331Z",
  "completed_at": "2026-08-26T15:35:44.210881Z",
  "audio": { "duration_ms": 1823170, "pcm_bytes": 58341464, "sample_rate_hz": 8000, "channels": 2 },
  "webhook": { "url": "https://example.com/hooks/speko", "delivered": true, "attempts": 1 },
  "result": {
    "text": "Your call has been forwarded. Hello? ...",
    "segments": [
      { "text": "Your call has been forwarded.", "start_ms": 60, "end_ms": 1080, "speaker": "0" },
      { "text": "Hello?", "start_ms": 3120, "end_ms": 3480, "speaker": "1" }
    ],
    "provider": "soniox",
    "model": "stt-rt-v5",
    "region": "us-east-1",
    "speaker_scope": "recording",
    "chunks": [
      { "index": 0, "start_ms": 0, "end_ms": 1823170, "provider": "soniox", "model": "stt-rt-v5",
        "request_id": "rreq_ngIsy31scnsj3UPtaEXO9PxG", "attempt_id": "ratt_KJWDter8J5ceMJAGr9V3OrdR" }
    ],
    "usage": { "duration_ms": 1823170 }
  }
}
```

<ResponseField name="result.text" type="string">
  The full transcript in reading order. May legitimately be empty for silent
  audio.
</ResponseField>

<ResponseField name="result.segments" type="object[]">
  Time-aligned spans with `start_ms`/`end_ms` measured from the start of the
  **whole recording** — chunk boundaries are invisible here. `speaker` is
  present only when you asked for `diarization` and the provider labels
  speakers; it is the provider's own label carried verbatim. Some models return
  whole-text only, in which case `segments` is omitted.
</ResponseField>

<ResponseField name="result.words" type="object[]">
  Per-word timings, present only when the job asked for `word_timestamps`.
  Recording-relative like `segments`, stitched across chunks in order; a
  word's `speaker` follows the same per-chunk labeling rule as its segment.
</ResponseField>

<ResponseField name="result.speaker_scope" type="string">
  How far a `speaker` label reaches. `recording`: one provider call labeled the
  whole recording, so a label means the same speaker everywhere. `chunk`: the
  audio was split; labels are renumbered so no two chunks share a label, but
  one person may carry different labels in different chunks. Speko never
  fabricates cross-chunk speaker identity — use `chunks` to decide what to
  merge. Omitted when diarization was not requested.
</ResponseField>

<ResponseField name="result.chunks" type="object[]">
  One entry per provider call: the span of the recording it covered, the
  provider and model that served it, and the request and attempt ids — the
  same ids that appear in your [usage records](/relay/usage), so every
  charge is traceable to a chunk.
</ResponseField>

<ResponseField name="result.provider / result.model" type="string">
  Present when every chunk was served by the same provider and model. Omitted
  when failover moved a chunk to another provider; consult `chunks`.
</ResponseField>

<ResponseField name="result.usage" type="object">
  `duration_ms` — the total audio duration metered, summed over chunks. Each
  chunk bills the duration the provider reports processing, capped at the
  audio sent.
</ResponseField>

<ResponseField name="error" type="object">
  On `failed`: `code` from the [error vocabulary](/relay/errors) and a
  customer-actionable `message`. Provider internals are never exposed.
</ResponseField>

The result stays fetchable for **7 days** after completion. After that the
document still answers with its status but `result` is omitted.

## Chunking [#chunking]

Jobs exist for audio longer than one provider call can take. The Router plans
chunks against the selected model's `batch_audio_limits` (from
`GET /v1/models?path=batch`), after parsing your upload — never against
declared values:

* Boundaries are frame-aligned and prefer the quietest instant near the
  limit, so words are not cut mid-syllable. Uniform audio cuts at the limit.
* Every chunk, including the last, is at least one second long.
* When the whole recording fits the model's limits, the job is one chunk.
  `text`, `segments` and `usage` then match what the synchronous endpoint
  would have returned, but the document shape is still the job result above —
  route facts live in `provider`/`model`/`region` and `chunks[0]`, not in a
  `route` object, so use one decoder for jobs and another for
  `POST /v1/stt/transcriptions`.
* With `diarization`, automatic routing prefers a model whose limits accept the
  whole recording over a marginally better-ranked one that would force a split,
  because provider speaker labels are only meaningful within one call.
* Failover for a chunk is restricted to models whose limits accept every
  planned chunk, so a mid-job fallback can never strand an oversized chunk.

Chunk sizes vary widely by provider: a 30-minute recording is one chunk on
Deepgram, AssemblyAI, Soniox or ElevenLabs, four chunks on OpenAI (25 MB per
upload) or Smallest (10 minutes), and 35 on Google Chirp 3 (60 seconds).

## Webhook delivery [#webhook-delivery]

When a job reaches a terminal state the Router POSTs the job document to
`webhook.url`:

```http
POST /hooks/speko HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Speko-Job-Id: sttjob_rPg1RaFE0wNC368zk3hYcc3u
Speko-Signature: t=1787758525,v1=6af330d581f26bafecec1924b5a5d8fd2a18544878a0e860fcfaa4b17fce2f89

{ "job_id": "sttjob_...", "status": "completed", ... }
```

Answer any `2xx` to accept. Any other status — including a `401` you write
because verification failed — is a delivery failure indistinguishable from a
timeout, and spends one attempt.

**Retries.** Delivery is retried with exponential backoff starting at 30
seconds and capped at 15 minutes, for up to 8 attempts (about 45 minutes in
total). After the last failure the job is still `completed` or `failed` with
`webhook.delivered: false`, and the result remains fetchable with `GET`.

**Delivery is at-least-once.** A worker can POST successfully and then fail to
record that it did, in which case the same terminal document is delivered
again. Every redelivery carries the same `Speko-Job-Id` and the same status, so
treating the job id as the idempotency key of your own processing is
sufficient.

**Failed jobs are delivered too**, with `status: failed` and `error` set, so a
receiver learns about every outcome without polling.

### Verifying a delivery [#verifying-a-delivery]

The signature is `HMAC-SHA256` over `<t>.<raw request body>` — the decimal
`t=` value, one ASCII period, then the body bytes exactly as received — keyed
with the **whole `whsec_…` secret string as ASCII bytes**. Do not strip the
prefix or base64-decode it: some generic webhook libraries do, and one of those
will never verify a Speko signature.

Follow four rules:

1. **Compare in constant time.** `crypto.timingSafeEqual`, `hmac.compare_digest`, `hmac.Equal` — never `==` on the hex.
2. **Bound the timestamp.** Reject a `t=` more than five minutes from your clock in either direction. A retried delivery is re-signed with a fresh `t=`, so this bounds replay without rejecting an honest retry.
3. **Deduplicate on `Speko-Job-Id`.**
4. **Verify against the raw bytes.** Re-serializing the JSON changes them.

```ts title="Node.js"
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: Buffer, signature: string, secret: string): boolean {
  // Parse "t=<unix>,v1=<hex>"; fields without "=" are ignored. A malformed
  // header is a rejection, never an exception.
  const parts: Record<string, string> = {};
  for (const field of signature.split(",")) {
    const eq = field.indexOf("=");
    if (eq > 0) parts[field.slice(0, eq).trim()] = field.slice(eq + 1).trim();
  }
  const t = Number(parts.t);
  if (!parts.v1 || !/^[0-9a-f]{64}$/.test(parts.v1) || !Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret) // the whole "whsec_..." string
    .update(`${parts.t}.`)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}
```

```python title="Python"
import hmac, hashlib, time

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in signature.split(","))
        t = int(parts["t"])
    except (KeyError, TypeError, ValueError):
        return False  # malformed header: reject, never raise
    v1 = parts.get("v1", "")
    # compare_digest requires ASCII strings; a non-hex v1 is a rejection, not an exception.
    if len(v1) != 64 or any(c not in "0123456789abcdef" for c in v1) or abs(time.time() - t) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)
```

Speko rotates its signing keys without breaking jobs in flight: a job's secret
is minted once, at submit, and remains the secret that signs its deliveries.

## Limits [#limits]

| Limit                                    | Value                                                                  | Exceeded →                                         |
| ---------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- |
| Upload size                              | 2 GiB (deployment default)                                             | `413 payload_too_large`                            |
| In-flight jobs per organization          | 64                                                                     | `429 concurrency_exhausted`                        |
| In-flight decoded audio per organization | 32 GiB                                                                 | `429 concurrency_exhausted`                        |
| Transcription attempts per job           | 3                                                                      | job `failed`                                       |
| Webhook delivery attempts                | 8 (≈45 min)                                                            | `webhook.delivered: false`; result still fetchable |
| Result retention                         | 7 days                                                                 | `result` omitted from the document                 |
| Audio retention                          | Deleted when the transcript is stored or the job fails; 1-day backstop | —                                                  |

Per-model chunk limits are advertised on `GET /v1/models?path=batch`; see the
[batch limits table](/relay/stt/batch#limits).

## Regions [#regions]

A job is transcribed in the region that accepted it — the `Speko-Region` of
the `202`. `router.speko.dev` is anycast, so that is normally the region
nearest you. Audio and transcript are stored in that region only, and the
webhook is delivered from it. `GET` from any region resolves the job.

## What jobs do not do [#what-jobs-do-not-do]

* No caller-supplied webhook secrets, and no non-443 webhook ports.
* No audio formats beyond the synchronous endpoint's (WAV / raw PCM s16le).
* No cross-chunk speaker merging — see `speaker_scope`.
* No job listing or cancellation endpoint; keep the `job_id`.
* No cross-chunk speaker merging on `words` either — they carry the same
  per-chunk labels as `segments`.


# Streaming transcription (/relay/stt/streaming)

GET /v1/stt/stream — live transcription over WebSocket.



## Connecting [#connecting]

Open a WebSocket to `wss://router.speko.dev/v1/stt/stream` with both required headers on the upgrade:

```
Authorization: Bearer sk_speko_...
Idempotency-Key: <unique key>
```

<Note>
  Browsers cannot set these headers on a WebSocket upgrade — connect from your backend.
</Note>

## Session lifecycle [#session-lifecycle]

The **first frame** you send must be `session.configure`, within 10 seconds of connecting. Its exact bytes are the [idempotency content hash](/relay/idempotency) for the session.

```json
{
  "type": "session.configure",
  "routing": { "mode": "auto", "objective": "latency" },
  "audio": { "encoding": "pcm_s16le", "sample_rate_hz": 16000, "channels": 1 },
  "language": "en"
}
```

<ParamField name="audio.encoding" type="string">
  `pcm_s16le` or `opus`.
</ParamField>

<ParamField name="audio.sample_rate_hz" type="number">
  8000–192000.
</ParamField>

<ParamField name="audio.channels" type="number">
  1–8.
</ParamField>

Then:

* Send audio as **binary frames** in the configured format.
* Send `{"type":"input.commit"}` to signal end of input and ask for final results.
* Send `{"type":"session.close"}` to end the session.

## Server frames [#server-frames]

The first server frame is always `session.ready`:

```json
{ "type": "session.ready", "request_id": "rreq_...", "route": { "provider": "cartesia", "model": "ink-2", "region": "eu-west-1", "attempt_id": "ratt_..." } }
```

| Frame              | Meaning                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------- |
| `session.ready`    | Session admitted and routed; always first                                                   |
| `transcript.delta` | Interim hypothesis: `{"type":"transcript.delta","text":"..."}` (`text` is always non-empty) |
| `transcript.final` | Finalized text: `{"type":"transcript.final","text":"...","segments":[...]}`                 |
| `usage.updated`    | Running usage snapshot                                                                      |
| `session.closed`   | Clean end: `{"type":"session.closed","usage":{...}}`                                        |
| `error`            | Terminal failure — the standard [error envelope](/relay/errors)                             |

**Exactly one terminal frame** ends every session: `session.closed` or `error`. A socket that drops without either was truncated — treat results as incomplete.

## Liveness and limits [#liveness-and-limits]

* The Router pings every 20 seconds; frames are capped at 1 MiB.
* Streaming sessions meter audio duration against a lease that the Router renews internally. If the session's budget or lease cannot be extended, the stream terminates with `budget_exhausted` or `lease_expired` — these two codes only ever appear on established streams, never as HTTP statuses.


# Synthesize speech (/relay/tts/speech)

POST /v1/tts/speech — synthesize audio from text in one request.



## Request [#request]

`POST https://router.speko.dev/v1/tts/speech`

```bash
curl -s https://router.speko.dev/v1/tts/speech \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": { "mode": "explicit", "provider": "cartesia", "model": "sonic-3" },
    "input": "Your order has shipped and will arrive on Thursday.",
    "audio": { "encoding": "pcm_s16le", "sample_rate_hz": 24000, "channels": 1 }
  }' \
  --output speech.pcm
```

<ParamField name="routing" type="object">
  The [routing object](/relay/routing). Omit for `auto`/`balanced`.
</ParamField>

<ParamField name="input" type="string">
  The text to synthesize. Must be non-empty.
</ParamField>

<ParamField name="voice" type="string">
  Optional provider voice ID. When omitted, the route's default voice is used — useful in auto mode, where you cannot know which provider's voice ID space applies.
</ParamField>

<ParamField name="audio" type="object">
  Output format: `encoding` (`pcm_s16le` or `opus`), `sample_rate_hz` (8000–192000), `channels` (1–8).
</ParamField>

## Response [#response]

The response body is the **raw audio stream** (`Content-Type: application/octet-stream`). Route and usage information travel in headers:

| Header                                          | Meaning                               |
| ----------------------------------------------- | ------------------------------------- |
| `Speko-Usage-Characters`                        | Characters metered for this synthesis |
| `Speko-Provider`, `Speko-Model`, `Speko-Region` | The route that served you             |
| `Speko-Request-ID`, `Speko-Attempt-ID`          | Correlation IDs                       |

<Note>
  One-shot synthesis returns audio only. [Word timings](/relay/tts/streaming#word-timings) are emitted on the streaming endpoint and are not available here.
</Note>

## Metering [#metering]

TTS bills **characters accepted for synthesis**. A one-shot request accepts its entire `input`, so the metered quantity is the character count of `input` — reported back in `Speko-Usage-Characters`.


# Streaming synthesis (/relay/tts/streaming)

GET /v1/tts/stream — incremental text in, audio out, over WebSocket.



## Connecting [#connecting]

Open a WebSocket to `wss://router.speko.dev/v1/tts/stream` with `Authorization` and `Idempotency-Key` headers on the upgrade, then send `session.configure` as the first frame (within 10 seconds):

```json
{
  "type": "session.configure",
  "routing": { "mode": "auto", "objective": "latency" },
  "audio": { "encoding": "pcm_s16le", "sample_rate_hz": 24000, "channels": 1 }
}
```

Optionally include `"voice"` to pin a provider voice ID. As with one-shot synthesis, streaming TTS is currently **English-only** — see the note on the [speech endpoint](/relay/tts/speech#language).

## Client frames [#client-frames]

| Frame               | Meaning                                                                            |
| ------------------- | ---------------------------------------------------------------------------------- |
| `session.configure` | First frame; fixes routing, audio format, and the idempotency hash                 |
| `input.append`      | `{"type":"input.append","text":"..."}` — add text to synthesize (`text` non-empty) |
| `input.commit`      | Flush: synthesize everything appended so far                                       |
| `input.cancel`      | Stop synthesizing the current utterance                                            |
| `session.close`     | End the session                                                                    |

Binary frames from the client are rejected — TTS input is text.

## Server frames [#server-frames]

Audio arrives as **binary frames** between `utterance.started` and `utterance.done` markers:

| Frame               | Meaning                                                                               |
| ------------------- | ------------------------------------------------------------------------------------- |
| `session.ready`     | Always first: `{"type":"session.ready","request_id":"...","route":{...}}`             |
| `utterance.started` | `{"type":"utterance.started","sequence":1}` — sequence is the 1-based utterance index |
| *(binary frames)*   | Audio for the current utterance, in the configured format                             |
| `utterance.timings` | Word-level time alignment for the current utterance, on routes that measure it        |
| `utterance.done`    | `{"type":"utterance.done","sequence":1}`                                              |
| `usage.updated`     | Running character usage                                                               |
| `session.closed`    | Clean end, with final `usage`                                                         |
| `error`             | Terminal failure — standard [error envelope](/relay/errors)                           |

Exactly one terminal frame (`session.closed` or `error`) ends every session.

## Word timings [#word-timings]

Routes that measure synthesis timing emit `utterance.timings` for each utterance, after its audio and immediately before `utterance.done`:

```json
{
  "type": "utterance.timings",
  "sequence": 1,
  "granularity": "word",
  "spans": [
    { "text": "Welcome", "start_ms": 111, "end_ms": 440 },
    { "text": "to", "start_ms": 520, "end_ms": 520 },
    { "text": "today.", "start_ms": 920, "end_ms": 1240 }
  ]
}
```

<ResponseField name="sequence" type="number">
  The utterance these spans belong to, matching the index `utterance.started` carried.
</ResponseField>

<ResponseField name="granularity" type="string">
  `word` on every route that emits timings today. Readings from an engine that measures per character are grouped into words by the Router, so one shape covers every provider.
</ResponseField>

<ResponseField name="spans" type="object[]">
  Time-aligned spans with `start_ms`/`end_ms` measured in milliseconds from the start of **this utterance**. `end_ms` is an end time, not a duration.

  Spans cover the text you sent rather than a provider's own rewrite of it, so they line up with the string you already hold. Match them to your text word by word: joining the spans back together will not reproduce your input exactly.
</ResponseField>

The frame follows the audio it describes, so it cannot drive a highlight that tracks playback as the audio arrives. A very long utterance may be split across several frames, all carrying the same `sequence`; concatenate them in arrival order.

Each span is well-formed on its own, but spans are never checked against each other. Identical start and end times turn up in ordinary output, and engines may return adjacent spans that overlap, so a consumer assuming a strictly increasing timeline will break on real responses.

An utterance stopped with `input.cancel` produces no timings. Its spans describe audio you never received, so the Router discards them rather than attribute them to the utterance that follows.

Timings are not something you request: there is no field or header that turns them on. What decides whether you get them is the provider behind the route.

| Provider   | Engine measures | You receive |
| ---------- | --------------- | ----------- |
| Cartesia   | words           | word spans  |
| ElevenLabs | characters      | word spans  |
| Soniox     | characters      | word spans  |

Every other TTS provider in the catalog sends nothing today. The catalog moves, so read `capabilities.word_timings` from [`GET /v1/models`](/relay/models) rather than pinning that list: a route without the flag sends no `utterance.timings` frame at all, rather than an empty one.

## Metering and budgets [#metering-and-budgets]

Characters are counted **when an `input.append` is accepted** — before synthesis, and regardless of whether you later cancel. `input.cancel` stops audio, not billing, for text already accepted.

Streaming sessions admit against an initial character budget and extend it transparently as you append more text. If your organization's credit cannot cover an extension, the next append terminates the stream with `budget_exhausted`; if the session's lease cannot be renewed, it terminates with `lease_expired`. Both codes appear only on established streams.

## Liveness [#liveness]

The Router pings every 20 seconds. Frames are capped at 1 MiB.