Create Agent
Create a voice agent.
The agent lands in the project named by project_id, or in the
implicit Default project when none is given. Each project holds at
most a fixed number of live agents; a create past that answers
409 agent_limit_reached naming the ceiling, and deleting an agent
in that project - or creating this one in another - frees a slot.
Authentication
Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.
Headers
Request
Optional workspace project to place this resource in (prefixed
proj_... id). Omit for the implicit Default project. An
unknown id returns 404 project_not_found.
Optional. Server derives slug from name with a random suffix when omitted; if you supply your own, a collision returns 400 ‘slug already taken’.
The delivery channels the agent serves. Defaults to [voice] when
omitted. Pass an explicit [] for an agent with no front door,
reached by its triggers only. Serving voice requires a
tts.voice_id.
A short steer for how the agent uses its knowledge bases: what to look up first, what never to quote, how to answer when nothing matches. It reaches the model as guidance under the prompt and shapes the per-turn retrieval query on every channel: live calls, text conversations and agent tests. Empty means none.
ISO 639-1 code. Defaults to ‘en’ when omitted. The agent’s default language.
Extra languages this agent serves in the same session.
Each entry’s language must be supported, unique, and
different from the default language.
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.
Text-to-speech voice and delivery configuration.
Turn-handling and silence-timeout configuration.
Per-caller long-term memory configuration.
Runtime safety controls that are opt-in per agent rather than platform defaults, because each one bills work an ordinary call does not do.
Optional ambient background-noise bed mixed into the call.
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.
Optional per-agent hostname allowlist (see Agent schema).
Customer-facing post-call webhook URL.
HMAC-SHA256 secret seed. Write-only — never echoed back on
reads; clients see webhook_secret_set: true instead.
AMD routing config. Optional on create; omitted means AMD off. See AMDConfig schema.
How many files a person may hand one conversation on this agent. Omit or null for the platform default of 10; 0 accepts no files. See the field on Agent.
Hard cap on the wall-clock length of a single call on this agent, in seconds. When a call reaches it the agent ends the call automatically. Voice agents only. Null means no per-agent cap: the call is bounded only by your plan’s call ceiling, which is also the hard upper bound for this field - a value above it is rejected.
When set, opts the agent into per-conversation audio recording. Defaults to false when omitted.
Opt-in AI-disclosure opening line. Optional on create; omitted means off. See AIDisclosure schema.
Response headers
Response
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.
The delivery channels this agent serves. Empty means no front door: the agent is reached by its triggers only. Mutable via PATCH.
ISO 639-1 code, e.g. ‘en’. The agent’s default language.
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.
Text-to-speech voice and delivery configuration.
Turn-handling and silence-timeout configuration.
Per-caller long-term memory configuration.
Runtime safety controls that are opt-in per agent rather than platform defaults, because each one bills work an ordinary call does not do.
Optional ambient background-noise bed mixed into the call.
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.
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.
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.
When true, every conversation produces a room-composite OGG egress uploaded to the recordings bucket. Defaults FALSE for new agents (privacy by default).
Opt-in AI-disclosure opening line. When enabled is true, line is
spoken at the very start of the call, before the greeting - ahead of
jurisdictions that require callers to be told they are speaking with an
automated system. Off by default; existing agents and numbers are
unaffected until they turn it on.
A short steer for how the agent uses its knowledge bases: what to look up first, what never to quote, how to answer when nothing matches. It reaches the model as guidance under the prompt and shapes the per-turn retrieval query on every channel: live calls, text conversations and agent tests. Empty means none.
Extra languages this agent serves in the same session beyond
its default language. When non-empty the agent can switch
language mid-call (triggered when the caller speaks one of
these languages or asks for it). Always present on reads;
empty array for single-language agents.
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.
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).
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.
True when an HMAC-SHA256 webhook secret is configured. The secret itself is write-only — supplied on PATCH and never echoed back on reads.
How many files a person may hand ONE conversation on this agent - a picture pasted into a Slack thread, a document dropped in a direct message. It bounds the THREAD rather than any single message: files live in your workspace file drop for a fortnight, and a long-running conversation is where they accumulate. Null means the platform default of 10. 0 means this agent accepts no files at all. When a conversation is full the file is not stored and the agent is told so, naming the cap, so it can say what would work.
Hard cap on the wall-clock length of a single call on this agent, in seconds. When a call reaches it the agent ends the call automatically. Voice agents only. Null means no per-agent cap: the call is bounded only by your plan’s call ceiling, which is also the hard upper bound for this field - a value above it is rejected.
Workspace project this resource lives in (prefixed external id). Null means the implicit Default project.