Custom actions

An action lets an assistant call an address the owner controls: your own service, or a catch hook on Zapier, Make or n8n. The assistant decides when to use it from the description the owner gave, passes the details it collected, and phrases whatever comes back.

Actions are created in the product — the owner tells the builder what the action does and gives it the address. This page is about the other end of the call.

What an action is made of

Part	Set by	Notes
Label	Owner	What they call it: “Check an order”
Description	Owner	When to use it and what comes back — this is what the assistant reads
Method	Derived	GET if it only looks something up, POST if it sends or changes something
URL	Owner	Must be https://
Fields	Owner	The details to pass, each with a description and whether it is required

An assistant can have up to 12 actions, each with up to 12 fields.

What you receive

Field values are always strings. Empty values are dropped rather than sent as "".

GET

Fields arrive as query parameters, appended to your URL. Any query string already in the URL is kept.

GET /orders/lookup?order_number=A-1183&email=priya%40example.com HTTP/1.1
Accept: application/json, text/plain
X-Api-Key: «your secret, if the owner set one»

POST

Fields arrive as a flat JSON object, plus one extra key.

POST /bookings HTTP/1.1
Content-Type: application/json
Accept: application/json, text/plain
Authorization: «your secret, if the owner set one»

{
  "name": "Priya",
  "people": "4",
  "preferred_date": "Saturday evening",
  "_source": { "assistant": "Bakery helper", "channel": "web" }
}

_source is added by Toldo, never by the assistant. channel is one of web, slack, telegram, teams, api or test — test means the owner is trying the assistant in the preview, which is your cue not to create anything real.

The auth header

The owner sets a header name and value for each action, and Toldo stores the value sealed — it is never part of the assistant’s own definition and never reaches the assistant. On every call the header is added as given:

Authorization: Bearer sk_live_…

X-Api-Key: …

Any header name of letters, digits and hyphens works. There is no signature and no shared-secret handshake beyond this, so use a real secret and check it on every request.

What to return

Return small, flat JSON. It is read as data for the assistant to phrase, so field names that read like English come back as better sentences.

{ "status": "Out for delivery", "expected": "Tuesday before 6pm", "tracking": "BLU-11832" }

Rules on the reading end:

• A 2xx response body is parsed as JSON and handed to the assistant. If it is not valid JSON, it is handed over as plain text instead — that works, it is just harder to phrase.
• Only the first 4,000 characters of your response are read. A large document is truncated.
• A non-2xx response does not end the conversation. The assistant is told the request failed, with your status code and the first 300 characters of the body, and carries on — usually by apologising or handing over to the owner.
• The call times out after 15 seconds. Do the slow part after you answer.

Addresses that are refused

The URL must be https:// and must be a public address. Anything resolving to a private or local name is refused before the request is made:

localhost, *.localhost, *.local, *.internal, 127.*, 10.*, 192.168.*, 169.254.*, 172.16–31.*, 0.*, and bracketed IPv6 literals.

Failure is soft, on purpose

An action that throws would end the turn with the assistant saying nothing at all. So every failure — a refused address, a timeout, a bad status, an unreachable host — comes back to the assistant as an error it can talk about. Your outage becomes “I couldn’t check that just now”, not silence.

That is the end of the API reference. If you have not built an assistant yet, start with Build your first assistant.