How a bot works
Read this once and the Bots API reference will make sense.
A bot has two sides
The draft is what you are editing. Published versions are what your visitors talk to.
They are separate. Writing the draft changes nothing for a visitor. Publishing copies the draft over and files the result as a version, and the history of versions is append-only.
edit the draft ──▶ PUT /bots/{id}/test ──▶ try it yourself
└─▶ POST /bots/{id}/versions ──▶ visitors get it
Publishing is creating a version. There is no separate publish call.
A diagram is yours
The draft holds a diagram: blocks and the connections between them. It travels through the API
all but unchanged — keys we do not model, like notes, come back as you wrote them, and so do your
bricks. The one thing we add is isTarget: true, on any node other than the start point, a note or a
global_keywords block that does not already say whether a connection may end at it.
{
"nodes": {
"hidden": {"id": "hidden", "path": "hidden", "template": "hidden", "params": {}},
"welcome": {"id": "welcome", "path": "welcome", "template": "var_text",
"params": {"version": 3, "text": "Hi! What is your name?", "destination": "name"}}
},
"connections": {
"hidden.success--welcome": {"id": "hidden.success--welcome", "type": "success",
"sourcePath": "hidden", "targetPath": "welcome"}
}
}
A node names its block by template, the storage name. The semantic name GET /blocks lists —
ask_question for the one above — is what the block-level operations address a block by.
Two ids matter. hidden is the start point, and welcome is the greeting slot — the first thing a
visitor is answered with. On every channel family but landbot the greeting slot is called
bot_start.
A connection's type is the output it leaves from. Outputs are not uniform: some carry a $ prefix
and some do not. GET /blocks tells you which, per block.
A brick is a diagram inside a block
A brick block runs a diagram of its own, which the document keeps in bricks under the block's id.
It starts at its block with the id brick_start, and its outputs node lists the ways out: a
connection inside it that points at outputs.$0 leaves the brick by its output $0. A brick is also
left by default, when the output it ends at has no connection of its own.
"bricks": {
"B0": {
"id": "B0", "path": "B0", "name": "Ask for the email",
"nodes": {
"brick_start": {"id": "brick_start", "path": "brick_start", "template": "var_email",
"params": {"text": "Your email?", "destination": "email"}},
"outputs": {"id": "outputs", "path": "outputs", "type": "chain", "template": "brick_outputs",
"params": {"outputs": [{"id": "$0", "alias": "Done"}]}}
},
"connections": {
"brick_start.$success--outputs.$0": {"id": "brick_start.$success--outputs.$0", "type": "$success",
"sourcePath": "brick_start", "targetPath": "outputs.$0"}
}
}
}
The blocks inside a brick are held to the same rules as the rest, and one breaking them is named by
its trail: B0->brick_start. The block-level operations write a brick whole, with what it holds under
brick: its blocks, named as GET /blocks names them, the outputs it declares and the connections
between them. They never address a block inside a brick on its own.
Saving never loses work
A write to the draft stores what you sent even when it breaks the rules. You get back save_state
and a list of violations, and you can keep editing.
The rules are only enforced when the bot has to run: PUT /bots/{id}/test and
POST /bots/{id}/versions both refuse while any violation stands.
A handful of problems are refused on the spot instead, because there would be nothing sensible to store — a block of a type we do not know, an id already taken. When a call fails lists which.
What answers look like
- One thing comes back under
data. - A list comes back under
data, withmetacarryingtotal,pageandpage_size. -
A field with no value is left out rather than sent as
null. Two answers are the exception and keep their nulls: the draft, and a single version — both carry a stored diagram, and dropping empty values would reach inside it.
Identifiers: a bot, a version and a channel are uuids. A workspace and a person are integers. A block is identified by its id inside the diagram, which is any string the diagram gave it.
Timestamps are UTC, written 2026-09-16T09:18:19. No offset and no fractions of a second — if
you parse them as local time you will be out by your own offset.
Bots built by an older builder
Some bots were made by a builder that came before this API. You can read them, and you can move them
in and out of the trash. Every other write answers 422. They have to be migrated first.
What this API does not do
It does not run conversations. There is no endpoint that accepts or returns what a visitor sees mid chat. You describe a bot here; the runtime is elsewhere.
Where a bot is reached — its web page, its design, its CSS — belongs to the Channels API.