Register Call | Smallest AI Docs

Mint a short-lived, single-use access token for opening a realtime Agent WebSocket connection. This is the recommended way to start a session from a browser or other client-side app: your API key stays server-side, and the browser only ever sees the short-lived token. (Server-side or trusted clients may instead connect to the WebSocket with a raw API key directly.)

Flow:

Call this endpoint with your API key and the agent_id (plus optional mode and per-call variables). All session configuration is fixed here — it is baked into the returned token.
Open a WebSocket to wss://api.smallest.ai/atoms/v1/agent/connect?token=<access_token>. No agent_id, mode, or variables query params are needed on the WebSocket — they come from the token.

The token is valid for expires_in seconds (30) and can be used for a single connection. Request a fresh token for each connection.

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Request

This endpoint expects an object.

agent_idstringRequired

The Atoms agent to connect to.

modeenumOptionalDefaults to webcall

Session mode. webcall = full voice pipeline (audio in + audio out). chat = text-only pipeline. Defaults to webcall.

Allowed values:

input_audio_formatenumOptional

The format you will send, as one <encoding>_<rate> token naming both the encoding and the rate. Defaults to PCM at the output rate, so a client sending only sample_rate needs nothing else.

The recogniser is configured at this rate and your audio is not resampled, so the token must match the bytes you send: a mismatch produces wrong transcripts and no error. G.711 exists only at 8000. Opus is raw packets, one per WebSocket message; Ogg-framed Opus is a different format and is refused.

A browser client can also declare this later, on the connect URL, once its AudioContext reports the rate it actually got.

output_audio_formatenumOptionalDefaults to pcm_24000

The format the agent sends back. Same token shape as input_audio_format. Sending this together with sample_rate is allowed only if they agree; disagreeing values are refused rather than resolved by a precedence rule.

Allowed values:

variablesmap from strings to strings or doubles or booleansOptional

Per-call prompt variables that override the agent's defaultVariables for this session only. Values must be string, number, or boolean. Reserved system-variable keys (call_id, conversation_type, agent_number, user_number, current_date, current_time, current_day, agent_gender, default_language, supported_languages, timezone) are populated by the server and stripped if supplied.

sample_rateenumOptionalDefaults to 24000Deprecated

Deprecated. Use output_audio_format instead. Still accepted, and will keep being accepted - existing integrations do not need to change.

A bare rate meaning PCM at that rate, so sample_rate: 24000 and output_audio_format: "pcm_24000" are the same request. It predates the one-token-per-direction contract and is the reason two fields exist for one thing. 44100 is only rendered by the lightning-v3.1 and lightning-v3.1-pro voices; asking for a rate the agent's voice cannot render is refused here rather than failing mid-call. This does not set the rate of the audio you send - use input_audio_format.

Allowed values:

Response

Access token created.

statusbooleanOptional

dataobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

500

Internal Server Error