automations
List Automations
List this organization's automations, oldest first: each one's trigger, the flow it runs, whether it is enabled or paused after repeated failures (and why), and when it last fired, ran and succeeded.
List Automations › Responses
Successful Response
consecutive_failuresenabledflow_idhas_webhook_secretidmin_interval_secondsnameorg_idThe small typed shape a trigger is configured by. Every field is optional
here and required by service for the kind that needs it, so one column
stores four vocabularies without four columns of nulls.
trigger_kindWhat sets an automation off. Closed, and each member names exactly one
place in this deployment where it is detected — see tasks.py and the
webhook route.
Four, and four is all the spec asks for. automations.md used to list a
fifth, "when a message or call arrives — including on channels we do not
answer conversationally", and withdrew it on 2026-09-13 when channels.md
was specified: "a channel nobody answers conversationally is simply a flow
with no branch that hands to an agent", so an arriving message runs the
channel's own flow and there is nothing left for a trigger to do. What an
automation does with a channel is send on one — channels'
send_on_channel built-in inside a scheduled flow, which is SCHEDULE.
#395 closed.
Create Automation
Declare an automation: a trigger plus the flow it runs, for work that happens
with no conversation. Use when a job should start on a schedule, a record
change, an interaction ending, or a webhook, rather than when a person
talks to the agent. The trigger is a schedule (trigger_config.cron), a record
written in a collection (trigger_config.collection_id), an interaction ended, or
a webhook the client's system calls. The flow decides what happens; the
automation only decides when. A message arriving on a channel is not a trigger
here: the channel's own flow already runs on it.
It is created switched off and runs nothing until it is enabled. A webhook automation's secret is in the answer, once — it is stored as a hash and cannot be shown again.
Create Automation › Request Body
flow_idnametrigger_kindWhat sets an automation off. Closed, and each member names exactly one
place in this deployment where it is detected — see tasks.py and the
webhook route.
Four, and four is all the spec asks for. automations.md used to list a
fifth, "when a message or call arrives — including on channels we do not
answer conversationally", and withdrew it on 2026-09-13 when channels.md
was specified: "a channel nobody answers conversationally is simply a flow
with no branch that hands to an agent", so an arriving message runs the
channel's own flow and there is nothing left for a trigger to do. What an
automation does with a channel is send on one — channels'
send_on_channel built-in inside a scheduled flow, which is SCHEDULE.
#395 closed.
min_interval_secondsThe small typed shape a trigger is configured by. Every field is optional
here and required by service for the kind that needs it, so one column
stores four vocabularies without four columns of nulls.
Create Automation › Responses
Successful Response
consecutive_failuresenabledflow_idhas_webhook_secretidmin_interval_secondsnameorg_idThe small typed shape a trigger is configured by. Every field is optional
here and required by service for the kind that needs it, so one column
stores four vocabularies without four columns of nulls.
trigger_kindWhat sets an automation off. Closed, and each member names exactly one
place in this deployment where it is detected — see tasks.py and the
webhook route.
Four, and four is all the spec asks for. automations.md used to list a
fifth, "when a message or call arrives — including on channels we do not
answer conversationally", and withdrew it on 2026-09-13 when channels.md
was specified: "a channel nobody answers conversationally is simply a flow
with no branch that hands to an agent", so an arriving message runs the
channel's own flow and there is nothing left for a trigger to do. What an
automation does with a channel is send on one — channels'
send_on_channel built-in inside a scheduled flow, which is SCHEDULE.
#395 closed.
Get Automation
Read one automation: its trigger, the flow it runs, whether it is enabled or paused after repeated failures (and why), and when it last fired, ran and succeeded. The webhook secret is never shown again after creation.
path Parameters
automation_idGet Automation › Responses
Successful Response
consecutive_failuresenabledflow_idhas_webhook_secretidmin_interval_secondsnameorg_idThe small typed shape a trigger is configured by. Every field is optional
here and required by service for the kind that needs it, so one column
stores four vocabularies without four columns of nulls.
trigger_kindWhat sets an automation off. Closed, and each member names exactly one
place in this deployment where it is detected — see tasks.py and the
webhook route.
Four, and four is all the spec asks for. automations.md used to list a
fifth, "when a message or call arrives — including on channels we do not
answer conversationally", and withdrew it on 2026-09-13 when channels.md
was specified: "a channel nobody answers conversationally is simply a flow
with no branch that hands to an agent", so an arriving message runs the
channel's own flow and there is nothing left for a trigger to do. What an
automation does with a channel is send on one — channels'
send_on_channel built-in inside a scheduled flow, which is SCHEDULE.
#395 closed.
Update Automation
Change what an automation watches or what it runs. Use when the trigger or the flow should change, not to switch it on or off — that is a separate operation.
path Parameters
automation_idUpdate Automation › Request Body
Update Automation › Responses
Successful Response
consecutive_failuresenabledflow_idhas_webhook_secretidmin_interval_secondsnameorg_idThe small typed shape a trigger is configured by. Every field is optional
here and required by service for the kind that needs it, so one column
stores four vocabularies without four columns of nulls.
trigger_kindWhat sets an automation off. Closed, and each member names exactly one
place in this deployment where it is detected — see tasks.py and the
webhook route.
Four, and four is all the spec asks for. automations.md used to list a
fifth, "when a message or call arrives — including on channels we do not
answer conversationally", and withdrew it on 2026-09-13 when channels.md
was specified: "a channel nobody answers conversationally is simply a flow
with no branch that hands to an agent", so an arriving message runs the
channel's own flow and there is nothing left for a trigger to do. What an
automation does with a channel is send on one — channels'
send_on_channel built-in inside a scheduled flow, which is SCHEDULE.
#395 closed.
Set Automation Enabled
Switch an automation on or off. Use when turning unattended work on or off for this automation's trigger.
Switching one on starts unattended work against the client's real systems,
and clears a pause a run of failures had set. Reach for it once the flow's
steps have each been tested (test_tool) and the flow reads what the trigger
hands it ("$ref:trigger.<key>"): nothing fires, run_automation included,
while it is off. Turning it off is the way to stop it without losing it; to
change what it watches or runs, use update_automation.
path Parameters
automation_idSet Automation Enabled › Responses
Successful Response
consecutive_failuresenabledflow_idhas_webhook_secretidmin_interval_secondsnameorg_idThe small typed shape a trigger is configured by. Every field is optional
here and required by service for the kind that needs it, so one column
stores four vocabularies without four columns of nulls.
trigger_kindWhat sets an automation off. Closed, and each member names exactly one
place in this deployment where it is detected — see tasks.py and the
webhook route.
Four, and four is all the spec asks for. automations.md used to list a
fifth, "when a message or call arrives — including on channels we do not
answer conversationally", and withdrew it on 2026-09-13 when channels.md
was specified: "a channel nobody answers conversationally is simply a flow
with no branch that hands to an agent", so an arriving message runs the
channel's own flow and there is nothing left for a trigger to do. What an
automation does with a channel is send on one — channels'
send_on_channel built-in inside a scheduled flow, which is SCHEDULE.
#395 closed.
Get Automation Map
Read one automation's frame of the map: the automation's card, what sets it
off, the flow it runs, the tools that flow's steps run, the collections it reads
and writes, and the connections it uses -- each with its owner and whether it is
working. An automation set off by a conversation ending that an agent's frame
holds has no frame of its own (it sits in each agent's): not found. Parts you
may not see are counted in hidden, never named. Give owner to see one
recipe's parts, or only the organization's own. Changes nothing.
path Parameters
automation_idquery Parameters
ownerNarrow the map to one owner: organization for the organization's own parts, or an installed recipe's id for that recipe's.
Narrow the map to one owner: organization for the organization's own parts, or an installed recipe's id for that recipe's.
Get Automation Map › Responses
Successful Response
automation_idOne card. key is the map's own handle for it (<kind>:<id>), what every
line and lane names; id is the part's own id, for opening its screen (rule 23)
-- for a documents or capability card, the agent's.
state is None for a card that carries no dot (rule 35): a collection,
documents, a capability, a number. failure -- why it failed -- is filled only
for a reader who may read where the failure was recorded (rule 30). missing
marks a part something points at that no longer exists, or a part an incomplete
recipe lacks; name is then the last name known, or None (rule 37).
One opened card's inside (rule 11). parts are the cards inside it, each with
frame set to key; lines every line drawn inside it, including those from a
part inside to an outer card it reads or writes. reads and writes name the
outer cards drawn above and below it; one both read and written is in writes
alone (rule 17).
hiddennameread_atRun Automation
Run this automation now, as if its trigger had fired. Use to see a newly enabled automation's flow run end to end, or for work wanted once, right now, rather than waiting on the schedule or trigger.
It really runs, against whatever the flow's steps reach. The runs are
recorded immediately and executed by a worker; the answer is the records,
not the results (get_automation_run has those). An automation that fans out
over a query answers with one record per row, and with none when the query
matches nothing. Reach for it to see a newly enabled automation's flow run
end to end, or for work wanted once, now; a switched-off or paused automation
is refused, so enable it first. A flow step reading "$ref:trigger.<key>"
sees a manual run's payload, {"manual": true}, not a schedule's or a
record's. Refused with 402, opening nothing, while the organization's
balance is spent.
path Parameters
automation_idRun Automation › Responses
Successful Response
attemptsautomation_ididorg_idoutcomeWhere one run got to.
trigger_keyList Automation Runs
This automation's history, newest first: when each run fired, what set it off, and how it ended. Use when reviewing past runs instead of starting a new one.
path Parameters
automation_idquery Parameters
limitoffsetList Automation Runs › Responses
Successful Response
attemptsautomation_ididorg_idoutcomeWhere one run got to.
trigger_keyGet Automation Run
Read one run of an automation: what set it off, the inputs the flow received, its outcome and attempts, the last step's result or the error, and each tool call it made (name, outcome, duration).
path Parameters
automation_idrun_idGet Automation Run › Responses
Successful Response
attemptsautomation_ididorg_idoutcomeWhere one run got to.
trigger_key