Update Built-in Tools
curl --request PATCH \
--url https://app.thinnest.ai/api/v1/agents/{id}/tools \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tools": {
"capture_lead": true,
"escalate_to_human": true,
"call_them_now": true,
"send_whatsapp": false
},
"recall": "two_tier",
"handOver": {
"mode": "call",
"phone": "+91 98765 43210",
"line": "Connecting you to our front desk now."
}
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
tools: {
capture_lead: true,
escalate_to_human: true,
call_them_now: true,
send_whatsapp: false
},
recall: 'two_tier',
handOver: {
mode: 'call',
phone: '+91 98765 43210',
line: 'Connecting you to our front desk now.'
}
})
};
fetch('https://app.thinnest.ai/api/v1/agents/{id}/tools', 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/{id}/tools"
payload = {
"tools": {
"capture_lead": True,
"escalate_to_human": True,
"call_them_now": True,
"send_whatsapp": False
},
"recall": "two_tier",
"handOver": {
"mode": "call",
"phone": "+91 98765 43210",
"line": "Connecting you to our front desk now."
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"agent": "ag_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34",
"tools": [
{
"id": "search_knowledge",
"title": "Search your knowledge base",
"summary": "Looks through your knowledge base before answering, and quotes from it rather than guessing.",
"switchable": false,
"enabled": true,
"reachesOtherChannels": false
},
{
"id": "capture_lead",
"title": "Capture leads",
"summary": "Asks how to reach someone who shows real interest, and records their details with a note on what they wanted.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": false
},
{
"id": "escalate_to_human",
"title": "Hand over to a person",
"summary": "Flags the conversation for your team and tells the customer someone will follow up.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": false
},
{
"id": "schedule_callback",
"title": "Book a call back",
"summary": "When somebody asks to be called later — in half an hour, after five — the agent books it and your number rings them at that time.",
"switchable": true,
"enabled": false,
"reachesOtherChannels": false
},
{
"id": "call_them_now",
"title": "Ring the customer now",
"summary": "While the agent is talking to a customer on your website or WhatsApp, it can have your number ring that customer straight away.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": true,
"ready": true,
"needs": "a number that can dial out, and the customer inside your calling hours"
},
{
"id": "send_whatsapp",
"title": "Send the customer a WhatsApp",
"summary": "While the agent is on a call with a customer, or chatting on your website, it can send that customer one of your approved templates on WhatsApp.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": true,
"ready": false,
"needs": "an approved utility template — the agent cannot write its own words on WhatsApp"
},
{
"id": "reply_by_email",
"title": "Reply to the customer by email",
"summary": "The agent can answer on that customer's existing email thread in your helpdesk, as you.",
"switchable": true,
"enabled": false,
"reachesOtherChannels": true,
"ready": false,
"needs": "a connected helpdesk that can send — Zendesk today, not Salesforce"
}
],
"webSearch": {
"enabled": false,
"switchable": false
},
"recall": "two_tier",
"verifyByCode": false,
"handOver": {
"mode": "call",
"phone": "+919876543210",
"line": "Connecting you to our front desk now."
},
"messages": []
}Tools
Update Built-in Tools
Switch built-in tools on or off and set recall, code verification and the hand-over. search_knowledge is not a switch and web search cannot be switched on; both are refused. Changes apply in order and stop at the first refusal, keeping what came before. Needs a full key. — it can arm tools that call or message customers.
PATCH
/
agents
/
{id}
/
tools
Update Built-in Tools
curl --request PATCH \
--url https://app.thinnest.ai/api/v1/agents/{id}/tools \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tools": {
"capture_lead": true,
"escalate_to_human": true,
"call_them_now": true,
"send_whatsapp": false
},
"recall": "two_tier",
"handOver": {
"mode": "call",
"phone": "+91 98765 43210",
"line": "Connecting you to our front desk now."
}
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
tools: {
capture_lead: true,
escalate_to_human: true,
call_them_now: true,
send_whatsapp: false
},
recall: 'two_tier',
handOver: {
mode: 'call',
phone: '+91 98765 43210',
line: 'Connecting you to our front desk now.'
}
})
};
fetch('https://app.thinnest.ai/api/v1/agents/{id}/tools', 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/{id}/tools"
payload = {
"tools": {
"capture_lead": True,
"escalate_to_human": True,
"call_them_now": True,
"send_whatsapp": False
},
"recall": "two_tier",
"handOver": {
"mode": "call",
"phone": "+91 98765 43210",
"line": "Connecting you to our front desk now."
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"agent": "ag_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34",
"tools": [
{
"id": "search_knowledge",
"title": "Search your knowledge base",
"summary": "Looks through your knowledge base before answering, and quotes from it rather than guessing.",
"switchable": false,
"enabled": true,
"reachesOtherChannels": false
},
{
"id": "capture_lead",
"title": "Capture leads",
"summary": "Asks how to reach someone who shows real interest, and records their details with a note on what they wanted.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": false
},
{
"id": "escalate_to_human",
"title": "Hand over to a person",
"summary": "Flags the conversation for your team and tells the customer someone will follow up.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": false
},
{
"id": "schedule_callback",
"title": "Book a call back",
"summary": "When somebody asks to be called later — in half an hour, after five — the agent books it and your number rings them at that time.",
"switchable": true,
"enabled": false,
"reachesOtherChannels": false
},
{
"id": "call_them_now",
"title": "Ring the customer now",
"summary": "While the agent is talking to a customer on your website or WhatsApp, it can have your number ring that customer straight away.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": true,
"ready": true,
"needs": "a number that can dial out, and the customer inside your calling hours"
},
{
"id": "send_whatsapp",
"title": "Send the customer a WhatsApp",
"summary": "While the agent is on a call with a customer, or chatting on your website, it can send that customer one of your approved templates on WhatsApp.",
"switchable": true,
"enabled": true,
"reachesOtherChannels": true,
"ready": false,
"needs": "an approved utility template — the agent cannot write its own words on WhatsApp"
},
{
"id": "reply_by_email",
"title": "Reply to the customer by email",
"summary": "The agent can answer on that customer's existing email thread in your helpdesk, as you.",
"switchable": true,
"enabled": false,
"reachesOtherChannels": true,
"ready": false,
"needs": "a connected helpdesk that can send — Zendesk today, not Salesforce"
}
],
"webSearch": {
"enabled": false,
"switchable": false
},
"recall": "two_tier",
"verifyByCode": false,
"handOver": {
"mode": "call",
"phone": "+919876543210",
"line": "Connecting you to our front desk now."
},
"messages": []
}Authorizations
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
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"
Path Parameters
The agent's id (ag_…).
Body
application/json
Send at least one field. Changes apply in order (tools, recall, verifyByCode, handOver) and stop at the first refusal; what came before it is kept, and the refusal says so.
Tool id to true or false. Switchable: capture_lead, escalate_to_human, schedule_callback, call_them_now, send_whatsapp, reply_by_email.
Show child attributes
Show child attributes
How much of a recognised customer's history the agent may use: trusted (all of it), two_tier (the default) or verified (only once they are confirmed).
Available options:
trusted, two_tier, verified Confirm a customer with a one-time WhatsApp code instead of their email.
Fields you leave out keep their saved value.
Show child attributes
Show child attributes
Response
The tools as saved, with any notes.
The agent (ag_…).
Show child attributes
Show child attributes
Searching the web. Shown, never switchable here.
Show child attributes
Show child attributes
How much of a recognised customer's history from other channels the agent may use.
Available options:
trusted, two_tier, verified Whether a customer is confirmed with a one-time WhatsApp code rather than their email.
How a hand-over to a person happens.
Show child attributes
Show child attributes
Notes from the changes applied, in order; often empty.