Skip to main content
GET
Get 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. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Path Parameters

id
string
required

The agent's id (ag_…), as List Agents returns it. Another workspace's agent is the same 404 as one that never existed.

Response

The agent.

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. When the agent is set to speak several languages this is auto: read languages.

languages
string[]
required

The languages the agent speaks, as the console shows them: [] is auto, one name is that language alone, and two to four are the languages it expects, the first being the one it falls back to.

secondLanguage
string | null
required
deprecated

Retired — always null. An agent answers in one language, language. Still returned so a client that reads it keeps working.

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.

ownRules
boolean
required

true leaves out the platform's own lead, hand-over and call-back sentences, for a business that writes those rules in its instructions. Left out: the sentence about asking for details (or that the business does not collect them), the hand-over rule (or that nobody can be handed to, and that nobody should promise a follow-up) and the "cannot book a call back" sentence. Kept whatever you send: the boundary, the AI disclosure, the reply language, the date, your own instructions, and how a call is put through to a person.

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).

byok
enum<string>
required

How this agent uses the workspace's own provider keys (Bring your own keys). null (or workspace) follows the workspace: its default scope applies when it brings its own keys. off never does: our voices and models at our normal pricing, whatever the workspace does, and the model is not held to the voice-only-BYOK model list. all, voice, llm or llm_voice runs this agent on that scope's keys whatever the workspace default is; refused with 409 naming the missing key unless the workspace holds verified keys for every kind that scope needs. If a key goes later, the agent falls back to the workspace's scope at the next call. Omit the field to leave it unchanged; saved BYOK model and voice choices are kept but not used while it is off. Read back as workspace when it follows the workspace.

Available options:
workspace,
off,
all,
voice,
llm,
llm_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.