API ReferenceAgents

Create Agent

Beta
Create a voice agent.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Headers

Speechify-VersionstringOptional

Request

This endpoint expects an object.
namestringRequired1-100 characters
promptstringRequired
first_messagestringRequired
Greeting spoken verbatim at session start when included in the agent's flow graph.
ttsobjectRequired

Text-to-speech voice and delivery configuration.

slugstringOptional<=64 characters

Optional. Server derives slug from name with a random suffix when omitted; if you supply your own, a collision returns 400 ‘slug already taken’.

languagestringOptional

ISO 639-1 code. Defaults to ‘en’ when omitted.

llmobjectOptional

Language-model configuration. Omit the whole block on create to run on the platform default model. On update (merge-patch) send only the sub-fields you want to change: an explicit null clears a nullable field to its default, a value sets it, and anything omitted is left unchanged. provider/model are validated as a pair, inheriting the omitted half from the stored value.

sttobjectOptional

Speech-to-text configuration.

turn_handlingobjectOptional

Turn-handling and silence-timeout configuration.

memoryobjectOptional

Per-caller long-term memory configuration.

navigatorobjectOptional

Autonomous IVR-navigation configuration for outbound calls.

background_noiseobjectOptional

Optional ambient background-noise bed mixed into the call.

widget_configobjectOptional

Customer-editable appearance + behaviour payload for the embedded <speechify-agent> pill: button text, avatar style, orb colours, terms-and-conditions markdown, transcript display. Every field is optional - empty fields fall back to the widget’s compile-time defaults.

is_publicbooleanOptional
Defaults to false when omitted.
allowed_originslist of stringsOptional
hostname_allowlistlist of stringsOptional

Optional per-agent hostname allowlist (see Agent schema).

webhook_urlstringOptional

Customer-facing post-call webhook URL.

webhook_secretstringOptional

HMAC-SHA256 secret seed. Write-only — never echoed back on reads; clients see webhook_secret_set: true instead.

amdobjectOptional

AMD routing config. Optional on create; omitted means AMD off. See AMDConfig schema.

save_audio_recordingbooleanOptional

When set, opts the agent into per-conversation audio recording. Defaults to false when omitted.

Response headers

X-Request-IDstring
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The created agent.
idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (agent_<26 char Crockford base32>). This is the sole customer-facing identifier. URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

namestring
slugstring
promptstring
first_messagestring
Spoken verbatim at session start when present in the customer's flow graph.
languagestring

ISO 639-1 code, e.g. ‘en’.

llmobject

Language-model configuration. Omit the whole block on create to run on the platform default model. On update (merge-patch) send only the sub-fields you want to change: an explicit null clears a nullable field to its default, a value sets it, and anything omitted is left unchanged. provider/model are validated as a pair, inheriting the omitted half from the stored value.

ttsobject

Text-to-speech voice and delivery configuration.

sttobject

Speech-to-text configuration.

turn_handlingobject

Turn-handling and silence-timeout configuration.

memoryobject

Per-caller long-term memory configuration.

navigatorobject

Autonomous IVR-navigation configuration for outbound calls.

background_noiseobject

Optional ambient background-noise bed mixed into the call.

is_publicboolean

When true, the <speechify-agent> web component can start a session against this agent without an API key, subject to the allowed_origins allowlist. When false (default), only authenticated callers can start sessions.

allowed_originslist of strings

Exact Origin header values (e.g. https://example.com) that are allowed to start public sessions. Empty array with is_public = true means any origin is accepted — intended for open demos. No subdomain wildcards.

amdobject

Answering Machine Detection routing config for outbound voice agents. AMD classifies the called party’s first ~3-15 seconds of audio into one of LiveKit’s categories (human, uncertain, machine-vm, machine-ivr, machine-unavailable) and dispatches per category to the configured action. Stored on the agent row; flowed onto outbound dispatch metadata under the amd key.

save_audio_recordingboolean

When true, every conversation produces a room-composite OGG egress uploaded to the recordings bucket. Defaults FALSE for new agents (privacy by default).

created_atdatetime
updated_atdatetime
widget_configobject

Customer-editable appearance + behaviour payload for the embedded <speechify-agent> pill: button text, avatar style, orb colours, terms-and-conditions markdown, transcript display. Every field is optional - empty fields fall back to the widget’s compile-time defaults.

hostname_allowlistlist of strings or null

Optional per-agent hostname allowlist enforced at session-creation time. When set and non-empty, the Origin header’s hostname must be an exact member. Bare hostnames only — no scheme, port, or path. Up to 10 entries. Omit (null) or leave empty for no enforcement (public agents accept any hostname).

webhook_urlstring

Per-agent override of the workspace webhook endpoints for this agent’s post-call event. When non-empty, the control plane POSTs the standard signed WebhookEvent envelope here once the conversation completes. This is the same shape workspace endpoints receive: data.object is the completed Conversation (equal to a direct GET), with the full transcript under data.messages and evaluations + data extractors under data.evaluations. The workspace endpoints’ conversation.completed is suppressed for this agent (the override wins, so the two planes no longer both fire). Empty routes conversation.completed to your workspace webhook endpoints instead. conversation.started / conversation.failed always ride the workspace endpoints regardless of this field.

webhook_secret_setboolean

True when an HMAC-SHA256 webhook secret is configured. The secret itself is write-only — supplied on PATCH and never echoed back on reads.

Errors

400
Bad Request Error
401
Unauthorized Error