Skip to main content
POST
Create Action

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

Body

application/json
name
string
required

The tool name the agent sees: 3 to 40 characters, lower case letters, numbers and underscores, starting with a letter. It cannot be one of the agent's built-in tools, and must be unique on this agent.

Required string length: 3 - 40
Pattern: ^[a-z][a-z0-9_]{2,39}$
description
string
required

When the agent should call it, in a sentence (at least 10 characters). The model decides from this alone.

Minimum string length: 10
url
string<uri>
required

An https:// address, with {{placeholders}} for parameters. Every placeholder needs a parameter of that name. Addresses inside private networks are refused when called.

Maximum string length: 2048
method
enum<string>
default:GET

The HTTP method; any case is accepted.

Available options:
GET,
POST,
PUT,
PATCH,
DELETE
parameters
object[]

Up to 20 values the agent fills from the conversation. Names must be unique.

Maximum array length: 20
bodyTemplate
string | null

A JSON body with quoted placeholders, e.g. {"id": "{{order_id}}"}. It must still be valid JSON once the blanks are filled.

Maximum string length: 8000
headers
object

Up to 10 headers, name to value — typically Authorization. Write-only: sealed on arrival; only their names come back, as headerNames. Blank values are dropped.

speakBefore
string | null

On calls, what the agent says while your API is being called.

Maximum string length: 200
speakAfter
string | null

On calls, what the agent says while it turns your answer into a reply.

Maximum string length: 200

Response

The action, switched off.

id
string
required

The action's id (act_…).

agent
string
required

The agent it belongs to (ag_…).

name
string
required

The tool name the agent sees.

description
string
required

When the agent should call it.

method
enum<string>
required

The HTTP method used.

Available options:
GET,
POST,
PUT,
PATCH,
DELETE
url
string
required

The https:// address, with {{placeholders}} — declared parameters, or the platform's dotted ones such as {{call.id}}. The host must be written out: no placeholder before the path.

parameters
object[]
required

What the agent fills in.

bodyTemplate
string | null
required

The JSON body sent, with quoted placeholders; null for none.

headerNames
string[]
required

The names of the headers sent. Their values are write-only and never returned.

speakBefore
string | null
required

On calls, what the agent says while your API is being called.

speakAfter
string | null
required

On calls, what the agent says while it turns your answer into a reply.

enabled
boolean
required

Whether the agent may call it. A new action is always false.

createdAt
string<date-time>
required

When it was made.

updatedAt
string<date-time>
required

When it last changed.