Create Agent

curl --request POST \
  --url https://app.thinnest.ai/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "Skyline Sales",
  "instructions": "You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.",
  "greeting": "Namaste, I'm calling from Skyline Homes about your enquiry for Sky Towers.",
  "businessDescription": "Skyline Homes builds 2 and 3 BHK apartments in Pune.",
  "model": "prana-voice",
  "language": "Hindi",
  "escalation": {
    "onRequest": true
  },
  "voice": {
    "voice": "priya",
    "summariseCalls": true,
    "recordCalls": true,
    "maxCallSeconds": 300
  },
  "collectFields": [
    {
      "name": "budget",
      "type": "number",
      "description": "Budget in rupees"
    },
    {
      "name": "interest",
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    }
  ]
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Skyline Sales',
    instructions: 'You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.',
    greeting: 'Namaste, I\'m calling from Skyline Homes about your enquiry for Sky Towers.',
    businessDescription: 'Skyline Homes builds 2 and 3 BHK apartments in Pune.',
    model: 'prana-voice',
    language: 'Hindi',
    escalation: {onRequest: true},
    voice: {voice: 'priya', summariseCalls: true, recordCalls: true, maxCallSeconds: 300},
    collectFields: [
      {name: 'budget', type: 'number', description: 'Budget in rupees'},
      {name: 'interest', choices: ['Hot', 'Warm', 'Cold']}
    ]
  })
};

fetch('https://app.thinnest.ai/api/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.thinnest.ai/api/v1/agents"

payload = {
    "name": "Skyline Sales",
    "instructions": "You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.",
    "greeting": "Namaste, I'm calling from Skyline Homes about your enquiry for Sky Towers.",
    "businessDescription": "Skyline Homes builds 2 and 3 BHK apartments in Pune.",
    "model": "prana-voice",
    "language": "Hindi",
    "escalation": { "onRequest": True },
    "voice": {
        "voice": "priya",
        "summariseCalls": True,
        "recordCalls": True,
        "maxCallSeconds": 300
    },
    "collectFields": [
        {
            "name": "budget",
            "type": "number",
            "description": "Budget in rupees"
        },
        {
            "name": "interest",
            "choices": ["Hot", "Warm", "Cold"]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71",
  "name": "Skyline Sales",
  "instructions": "You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.",
  "greeting": "Namaste, I'm calling from Skyline Homes about your enquiry for Sky Towers.",
  "businessDescription": "Skyline Homes builds 2 and 3 BHK apartments in Pune.",
  "model": "prana-voice",
  "temperature": 0.3,
  "maxReplyTokens": 300,
  "language": "Hindi",
  "secondLanguage": null,
  "escalation": {
    "onNoAnswer": false,
    "onRequest": true
  },
  "captureLeads": true,
  "scheduleCallbacks": false,
  "steps": [],
  "widget": {
    "theme": "classic",
    "accent": null,
    "height": 806,
    "welcomeScreen": true,
    "welcomeCollectLeads": true
  },
  "voice": {
    "answersCalls": true,
    "surfaces": [
      "web",
      "whatsapp"
    ],
    "voice": "priya",
    "phoneNumber": null,
    "language": null,
    "summariseCalls": true,
    "detectMachines": false,
    "recordCalls": true,
    "maxCallSeconds": 300,
    "ringSeconds": 30,
    "pastConversations": "quiet",
    "unavailableMessage": null,
    "unavailableMessageNote": null,
    "callStartUrl": null,
    "thinking": true,
    "thinkingLines": [],
    "thinkingDelayMs": 900,
    "thinkingRepeatMs": 2500,
    "thinkingAtTurnEnd": false,
    "turnSilenceSeconds": null,
    "turnDetection": null,
    "reaskAfterSeconds": null,
    "recordDoNotCall": true,
    "interruptWords": 3,
    "neverInterrupt": false,
    "holdShortSpeech": true,
    "greetingUninterruptible": false,
    "ambience": null,
    "ambienceVolume": 0.15,
    "endCallOnFinish": false,
    "nudgeAfterSeconds": null,
    "nudges": 1,
    "nudgePhrase": null,
    "endAfterSilenceSeconds": null,
    "endPhrases": [],
    "callInstructions": null
  },
  "byok": "workspace",
  "collectFields": [
    {
      "name": "budget",
      "type": "number",
      "description": "Budget in rupees",
      "choices": null
    },
    {
      "name": "interest",
      "type": "text",
      "description": null,
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    }
  ],
  "webKey": "pk_9fQ2xLm7Rt4vWb8KcN3hYd6sJ1pZ",
  "createdAt": "2026-10-06T08:12:44.118Z"
}

POST

agents

Create Agent

curl --request POST \
  --url https://app.thinnest.ai/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "Skyline Sales",
  "instructions": "You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.",
  "greeting": "Namaste, I'm calling from Skyline Homes about your enquiry for Sky Towers.",
  "businessDescription": "Skyline Homes builds 2 and 3 BHK apartments in Pune.",
  "model": "prana-voice",
  "language": "Hindi",
  "escalation": {
    "onRequest": true
  },
  "voice": {
    "voice": "priya",
    "summariseCalls": true,
    "recordCalls": true,
    "maxCallSeconds": 300
  },
  "collectFields": [
    {
      "name": "budget",
      "type": "number",
      "description": "Budget in rupees"
    },
    {
      "name": "interest",
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    }
  ]
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Skyline Sales',
    instructions: 'You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.',
    greeting: 'Namaste, I\'m calling from Skyline Homes about your enquiry for Sky Towers.',
    businessDescription: 'Skyline Homes builds 2 and 3 BHK apartments in Pune.',
    model: 'prana-voice',
    language: 'Hindi',
    escalation: {onRequest: true},
    voice: {voice: 'priya', summariseCalls: true, recordCalls: true, maxCallSeconds: 300},
    collectFields: [
      {name: 'budget', type: 'number', description: 'Budget in rupees'},
      {name: 'interest', choices: ['Hot', 'Warm', 'Cold']}
    ]
  })
};

fetch('https://app.thinnest.ai/api/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.thinnest.ai/api/v1/agents"

payload = {
    "name": "Skyline Sales",
    "instructions": "You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.",
    "greeting": "Namaste, I'm calling from Skyline Homes about your enquiry for Sky Towers.",
    "businessDescription": "Skyline Homes builds 2 and 3 BHK apartments in Pune.",
    "model": "prana-voice",
    "language": "Hindi",
    "escalation": { "onRequest": True },
    "voice": {
        "voice": "priya",
        "summariseCalls": True,
        "recordCalls": True,
        "maxCallSeconds": 300
    },
    "collectFields": [
        {
            "name": "budget",
            "type": "number",
            "description": "Budget in rupees"
        },
        {
            "name": "interest",
            "choices": ["Hot", "Warm", "Cold"]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71",
  "name": "Skyline Sales",
  "instructions": "You call people who enquired about a flat at Sky Towers, Baner. Find out their budget, preferred size and when they can visit the site.",
  "greeting": "Namaste, I'm calling from Skyline Homes about your enquiry for Sky Towers.",
  "businessDescription": "Skyline Homes builds 2 and 3 BHK apartments in Pune.",
  "model": "prana-voice",
  "temperature": 0.3,
  "maxReplyTokens": 300,
  "language": "Hindi",
  "secondLanguage": null,
  "escalation": {
    "onNoAnswer": false,
    "onRequest": true
  },
  "captureLeads": true,
  "scheduleCallbacks": false,
  "steps": [],
  "widget": {
    "theme": "classic",
    "accent": null,
    "height": 806,
    "welcomeScreen": true,
    "welcomeCollectLeads": true
  },
  "voice": {
    "answersCalls": true,
    "surfaces": [
      "web",
      "whatsapp"
    ],
    "voice": "priya",
    "phoneNumber": null,
    "language": null,
    "summariseCalls": true,
    "detectMachines": false,
    "recordCalls": true,
    "maxCallSeconds": 300,
    "ringSeconds": 30,
    "pastConversations": "quiet",
    "unavailableMessage": null,
    "unavailableMessageNote": null,
    "callStartUrl": null,
    "thinking": true,
    "thinkingLines": [],
    "thinkingDelayMs": 900,
    "thinkingRepeatMs": 2500,
    "thinkingAtTurnEnd": false,
    "turnSilenceSeconds": null,
    "turnDetection": null,
    "reaskAfterSeconds": null,
    "recordDoNotCall": true,
    "interruptWords": 3,
    "neverInterrupt": false,
    "holdShortSpeech": true,
    "greetingUninterruptible": false,
    "ambience": null,
    "ambienceVolume": 0.15,
    "endCallOnFinish": false,
    "nudgeAfterSeconds": null,
    "nudges": 1,
    "nudgePhrase": null,
    "endAfterSilenceSeconds": null,
    "endPhrases": [],
    "callInstructions": null
  },
  "byok": "workspace",
  "collectFields": [
    {
      "name": "budget",
      "type": "number",
      "description": "Budget in rupees",
      "choices": null
    },
    {
      "name": "interest",
      "type": "text",
      "description": null,
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    }
  ],
  "webKey": "pk_9fQ2xLm7Rt4vWb8KcN3hYd6sJ1pZ",
  "createdAt": "2026-10-06T08:12:44.118Z"
}

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"

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 | null

default:prana-voice

A model id from List Models, or null for the default (Prana [Voice]) — the same as leaving it out. An empty string is a 400. If given, it is 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

languages

string[]

The languages the agent speaks, by their English names: [] is auto (reply in the customer's language), one name is that language alone, and two to four make the agent expect those languages, the first being the one it falls back to when it cannot tell. On a phone call the recogniser works out the language among them. Send languages or language, not both: language sets one language and clears this list. A name the console does not offer, a repeat, or more than four is refused with a 400.

Maximum array length: 4

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

deprecated

Retired. Accepted so an older integration keeps working, but ignored: the agent answers in language alone.

escalation

object

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

Show child attributes

Example:

{ "onNoAnswer": false, "onRequest": true }

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

Show child attributes

byok

enum<string> | null

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,

null

The website widget's look. Send any subset.

Show child attributes

Example:

{
  "theme": "modern",
  "accent": "#0f766e",
  "height": 720
}

voice

object

How the agent handles calls. Send any subset. Where an agent has no voice channel yet, sending any of these creates one — switched OFF, so setting only a voice or a message never starts it taking calls; send answersCalls: true to switch it on.

Show child attributes

Example:

{
  "voice": "priya",
  "summariseCalls": true,
  "maxCallSeconds": 300,
  "pastConversations": "quiet",
  "thinkingLines": ["One moment, let me check."],
  "interruptWords": 2,
  "nudgeAfterSeconds": 10,
  "nudges": 2,
  "endPhrases": ["bye"]
}

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

Show child attributes

Response

The agent, as Get Agent returns it.

An agent as the console shows it.

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.

Show child attributes

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.

Show child attributes

The website chat widget's look.

Show child attributes

voice

object | null

required

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

Show child attributes

byok

enum<string>

required

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.

Show child attributes

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.