Skip to main content
POST
Create Agent

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json
name
string
required

The agent's name, 2 to 60 characters, without hidden characters or markup.

Required string length: 2 - 60
instructions
string

What the agent is and how it behaves. Left out, it gets the starter persona the console gives a blank agent. Re-sent on every reply, so every character costs on every turn.

Maximum string length: 20000
greeting
string

The first thing it says on a call or in a chat.

Maximum string length: 200
businessDescription
string

One line about what the business is. Facts belong in Knowledge.

Maximum string length: 200
model
string
default:prana-voice

A model id from List Models — the same list the console's one model picker offers, for chat and calls alike: it must be on your plan, quick enough to answer a call (voice: true), within the per-minute budget a call can carry, and not one of our voice-only models (they answer calls on their own and are never an agent's model). A chat-only agent is held to the same list, as in the console.

temperature
number
default:0.3

How adventurous the wording is. Clamped to 0–2.

Required range: 0 <= x <= 2
maxReplyTokens
number
default:300

The longest a reply may be, in tokens, for chat and calls alike. Rounded and clamped to 100–800.

Required range: 100 <= x <= 800
language
string
default:auto

auto to reply in the customer's language, or a language the console offers by its English name: English, Hindi, Assamese, Bengali, Bodo, Dogri, French, German, Gujarati, Indonesian, Italian, Japanese, Kannada, Kashmiri, Konkani, Korean, Maithili, Malayalam, Manipuri, Marathi, Nepali, Odia, Polish, Portuguese, Punjabi, Russian, Sanskrit, Santali, Sindhi, Spanish, Swahili, Tamil, Telugu, Thai, Turkish, Urdu or Vietnamese.

secondLanguage
string | null

A second language from the same list that it may switch to, or null for none. Not auto: that is refused with a 400.

escalation
object

When the agent hands over to a person. Send either or both.

Example:
captureLeads
boolean
default:true

Take a name, email or phone number from an interested customer.

scheduleCallbacks
boolean
default:false

Allow it to book a call back when asked.

welcomeScreen
boolean
default:true

Open the website widget on a welcome screen.

welcomeCollectLeads
boolean
default:true

Ask for the visitor's details on the welcome screen.

steps
object[]

A conversation script, in order, replacing any there was. Blank steps are dropped.

Maximum array length: 12
widget
object

The website widget's look. Send any subset.

Example:
voice
object

How the agent handles calls. Send any subset. Where an agent has no voice channel yet, sending any of these creates one.

Example:
collectFields
object[] | null

The details to fill in from the transcript after every call; they arrive as fields in each call's results. A call that sends its own extract uses that instead.

Maximum array length: 30

Response

The agent, as Get Agent returns it.

An agent as the console shows it.

id
string
required

The agent's id.

Example:

"ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71"

name
string
required

The agent's name, 2 to 60 characters.

instructions
string
required

What the agent is and how it behaves — its standing prompt.

greeting
string
required

The first thing it says, or an empty string.

businessDescription
string
required

One line about the business, or an empty string.

model
string | null
required

A model id from List Models. null when the agent is on a model that has since been retired.

temperature
number
required

How adventurous the wording is.

Required range: 0 <= x <= 2
maxReplyTokens
integer
required

The longest a reply may be, in tokens — one ceiling for chat and calls.

Required range: 100 <= x <= 800
language
string
required

auto (reply in the customer's language) or the language it always replies in, e.g. Hindi.

secondLanguage
string | null
required

A second language it may switch to, or null.

escalation
object
required

When the agent hands the conversation to a person on your team.

captureLeads
boolean
required

Whether it takes a name, email or phone number from an interested customer.

scheduleCallbacks
boolean
required

Whether it may book a call back when asked.

steps
object[]
required

Its conversation script, in order.

widget
object
required

The website chat widget's look.

voice
object | null
required

How it handles calls. null when the agent has no voice channel (a deployment without voice).

collectFields
object[]
required

The details it fills in after every call, in the shape a call's extract takes. Empty when it collects nothing.

webKey
string | null
required

The public key the website widget embeds (pk_…). It is published on your site, so it is not a secret.

createdAt
string<date-time>
required

When the agent was made.