curl --request PATCH \
--url https://app.thinnest.ai/api/v1/agents/{id}/connections/{kind} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tools": {
"calcom_check_availability": true,
"calcom_book_meeting": true
},
"phrases": {
"calcom_check_availability": {
"before": "Let me look at the calendar.",
"after": null
}
}
}
'{
"kind": "grist",
"name": "Grist",
"signIn": "key",
"available": true,
"connected": true,
"account": {
"email": "ops@greenleafrealty.in",
"name": null
},
"lastError": null,
"mode": "tool",
"runAsync": false,
"target": {
"doc": "8xQm2KvTzR4pLw",
"table": "Site_Visits",
"columns": [
"Name",
"Phone",
"Budget",
"Locality",
"Visit_Date"
]
},
"match": {
"column": "Phone",
"type": "phone"
},
"variableColumns": {
"Locality": "locality"
},
"tools": [
{
"id": "grist_save_row",
"title": "Fill in a row",
"summary": "Adds or fills the lead's row in your table as the conversation goes.",
"writes": true,
"enabled": true,
"phrases": {
"before": null,
"after": null
}
},
{
"id": "grist_find_rows",
"title": "Look something up",
"summary": "Reads rows from your table to answer a question.",
"writes": false,
"enabled": false,
"phrases": {
"before": null,
"after": null
}
}
],
"toolsInUse": 5,
"maxTools": 500,
"messages": [
"Every conversation now fills the row that matches Phone."
]
}Configure Connection
Pin a connection to its target, say how a lead’s row is found, choose when it saves, and switch its tools. The account must be connected first (records excepted). Changes apply in a fixed order and stop at the first refusal, keeping what came before it. Helpdesks have nothing to configure. A build key may do this.
curl --request PATCH \
--url https://app.thinnest.ai/api/v1/agents/{id}/connections/{kind} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tools": {
"calcom_check_availability": true,
"calcom_book_meeting": true
},
"phrases": {
"calcom_check_availability": {
"before": "Let me look at the calendar.",
"after": null
}
}
}
'{
"kind": "grist",
"name": "Grist",
"signIn": "key",
"available": true,
"connected": true,
"account": {
"email": "ops@greenleafrealty.in",
"name": null
},
"lastError": null,
"mode": "tool",
"runAsync": false,
"target": {
"doc": "8xQm2KvTzR4pLw",
"table": "Site_Visits",
"columns": [
"Name",
"Phone",
"Budget",
"Locality",
"Visit_Date"
]
},
"match": {
"column": "Phone",
"type": "phone"
},
"variableColumns": {
"Locality": "locality"
},
"tools": [
{
"id": "grist_save_row",
"title": "Fill in a row",
"summary": "Adds or fills the lead's row in your table as the conversation goes.",
"writes": true,
"enabled": true,
"phrases": {
"before": null,
"after": null
}
},
{
"id": "grist_find_rows",
"title": "Look something up",
"summary": "Reads rows from your table to answer a question.",
"writes": false,
"enabled": false,
"phrases": {
"before": null,
"after": null
}
}
],
"toolsInUse": 5,
"maxTools": 500,
"messages": [
"Every conversation now fills the row that matches Phone."
]
}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.
"org_3fKq9TzQ1mN8vB2xR7cLpA"
Path Parameters
The agent's id (ag_…).
The connection: calcom (calendar), grist or googlesheets (spreadsheets), zoho or zoho_bigin (CRMs), records (kept here), zendesk or salesforce (helpdesks).
calcom, grist, googlesheets, zoho, zoho_bigin, records, zendesk, salesforce Body
Any of these, as the kind allows. Applied in this order — fields, target, match, variableColumns, mode, runAsync, tools, phrases — stopping at the first refusal; what came before it is kept, and the refusal says so. Helpdesks (zendesk, salesforce) have nothing to configure.
Records only: what to collect, Label or Label | what it means.
Spreadsheets and CRMs: pins it and reads the target's real columns. Grist needs doc and table; Google Sheets spreadsheet and sheet; Zoho CRM and Bigin module. Use GET …/options to see the choices.
Show child attributes
Show child attributes
Spreadsheets and CRMs: fill the lead's existing row found by this column instead of adding one. Null (or column: null) adds a row per conversation.
Show child attributes
Show child attributes
Spreadsheets and CRMs: column to campaign variable, e.g. { "Locality": "locality" }. Neither may contain = or a line break. Replaces the saved map.
Show child attributes
Show child attributes
All but the calendar: tool saves during the conversation; parser reads the conversation afterwards (and switches the save tool off).
tool, parser Grist only: answer before the save finishes.
Tool id to true or false. Every id must be one of this connection's tools. Switching on counts against the shared maxTools budget.
Show child attributes
Show child attributes
Tool id to { before, after }: what the agent says on a call while the tool runs. Up to 8 lines, each under 60 characters.
Show child attributes
Show child attributes
Response
The connection as saved, with what each change said.
One account an agent can work in. Fields beyond the first few depend on the kind: a calendar has timezone; spreadsheets and CRMs have target, match and variableColumns; records has fields, recordCount and link; a helpdesk has only account and enabled. Credentials never appear.
The connection.
calcom, grist, googlesheets, zoho, zoho_bigin, records, zendesk, salesforce Its display name.
How it is connected: key by POST with a key; browser through a consent screen in the console (the API cannot); none for records, which need no account.
key, browser, none Whether this deployment offers it at all.
Whether it is connected.
Who it is connected as: { email, name }, or { host, email } for a helpdesk.
Show child attributes
Show child attributes
Why the last attempt to use it failed.
Connection tools switched on, across every connection.
The shared budget.
What each applied change said, in order.
Browser sign-ins only: a sign-in was started in the console and not finished.
Calendar only: the account's timezone.
All but the calendar and helpdesks: tool saves during the conversation; parser reads the conversation afterwards.
tool, parser Grist only: answer before the save finishes.
Spreadsheets and CRMs: what it is pinned to, and that target's real columns. Grist { doc, table, columns }; Google Sheets { spreadsheet, sheet, columns }; Zoho { module, columns }.
Spreadsheets and CRMs: the column that finds a lead's existing row, or null to add a row per conversation.
Show child attributes
Show child attributes
Spreadsheets and CRMs: column to campaign variable.
Show child attributes
Show child attributes
Its tools. Helpdesks have none here.
Show child attributes
Show child attributes
Records only: what is collected.
Show child attributes
Show child attributes
Records only: how many records have been collected.
Records only: the link to read them. The passcode is shown only by the call that makes a link.
Show child attributes
Show child attributes
Helpdesks only: whether it is in use.