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.

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

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.