Automations
An automation is a rule that runs one of your agent definitions when something happens in your workspace, on a schedule, or only by hand, where automations are available to your organization. List and create automations, which start disabled, then enable, update or delete them, check whether one would fire on a given item, and run one now to test it. List, filter and delete runs, and read the model and tool steps of each run. See Automations.
List a workspace's automations
Every stored rule in this workspace, each with a summary of its most recent run. Requires the automation feature flag.
path Parameters
workspaceIdWorkspace UUID
List a workspace's automations › Responses
List of automations
Create an automation
Creates a rule, always DISABLED. Enabling is a separate transition (PUT with enabled: true) that re-runs this validation, re-checks that runAsUserId still has workspace access, and computes the first nextRunAt for a schedule. The agent slug must resolve, be enabled and be async-eligible; a condition must name a field that exists for the trigger's event.
path Parameters
workspaceIdWorkspace UUID
Create an automation › Request Body
namerunAsUserId^([0-9a-fA-F]{8}-[0-…Defaults to the calling user.
Create an automation › Responses
Created automation
Get an automation
path Parameters
workspaceIdWorkspace UUID
idAutomation UUID
Get an automation › Responses
Automation
Update an automation
All fields optional. enabled: true is a TRANSITION, not a field write: it re-validates the rule, re-checks runAsUserId membership, clears disabledReason and the circuit breaker's counter, and arms the schedule. Note that enabling reaches every API container within one cache TTL (~45 s), so the first minute can fire unevenly; the per-automation rate limit is uncached and bounds it.
path Parameters
workspaceIdWorkspace UUID
idAutomation UUID
Update an automation › Request Body
nameenabledrunAsUserId^([0-9a-fA-F]{8}-[0-…Update an automation › Responses
Updated automation
Run an automation once, now
The manual trigger and the Test button. Goes through the same guardrails, writes the same run row and publishes the same queue message as an event trigger. Given an entityId, the run impersonates the rule's own event — the agent receives the same ## Trigger block a real firing would produce — and the conditions are checked first: a miss answers status: "unmatched" with the per-leaf verdict and queues nothing, unless force is set. With no entity nothing is pre-checked, since none of the conditions could be answered anyway. Answers 200 even when a guardrail refused the run — the row carries the reason.
path Parameters
workspaceIdWorkspace UUID
idAutomation UUID
Run an automation once, now › Request Body
entityId^([0-9a-fA-F]{8}-[0-…entityTypechangedFieldsinputforceRun an automation once, now › Responses
Run recorded, or refused with a verdict
Check whether a rule would fire on one entity
A dry run of the conditions: no run row, no queue message, no model call. conditions overrides the stored tree when present, so a builder can check unsaved edits. Two things a test cannot know are reported as unevaluable rather than as a miss — changedTo/changedFrom, since an entity at rest carries no before-state, and any field the event delivers only in its extra payload. Un-checkable conditions count as a pass in matched and are counted separately in unevaluable.
path Parameters
workspaceIdWorkspace UUID
idAutomation UUID
Check whether a rule would fire on one entity › Request Body
entityId^([0-9a-fA-F]{8}-[0-…entityTypechangedFieldsCheck whether a rule would fire on one entity › Responses
The per-condition verdict
List entities this automation can be tested against
Recent rows of the entity type the rule's trigger event fires on, most recently updated first, optionally filtered by a substring of the title. The type is derived from the rule, never taken from the caller, so the picker cannot offer something the automation could not fire on. Empty for a schedule trigger.
path Parameters
workspaceIdWorkspace UUID
idAutomation UUID
query Parameters
querySubstring of the entity title
limitMaximum rows, capped server-side
List entities this automation can be tested against › Responses
Candidate entities
List automation runs
Every run in this workspace: event, schedule, manual, and the agent-definition page's Run now, which has no automation behind it. Filterable by automationId, status (one status, or a comma-separated list such as queued,running), agentSlug, triggerType, entityType, a from/to window over the creation time and finishedFrom over the finish time, searchable over the entity key and title, the agent slug, the rendered input, the error and the automation name. A skipped row is a run a guardrail refused, with the reason in error.
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFree text over the entity key and title, the agent slug, the rendered input, the error and the automation name.
automationIdOnly runs produced by this automation
statusFilter by run status: a single status, or a comma-separated list of them (runs in ANY listed status); queued,running lists the runs still in flight. Unknown values are ignored, and a filter with none left applies no status filter.
agentSlugtriggerTypeentityTypeOnly runs that acted on this entity type
fromISO timestamp — only runs created at or after this moment
toISO timestamp — only runs created at or before this moment
finishedFrom^(?:(?:\d\d[2468][04…ISO 8601 instant (for example 2026-10-26T09:00:00Z): only runs that finished at or after this moment. A run still in flight has no finish time and never matches. Independent of from/to, which bound the creation time. A value that is not an ISO 8601 instant is refused with 400.
List automation runs › Responses
List of automation runs
Delete automation runs
Removes run rows permanently — a run is a log, not an entity with a lifecycle, so there is no soft delete to undo. Note the per-hour rate limit COUNTS these rows, so deleting recent history lets an automation fire again sooner than its ceiling otherwise allows. Ids outside this workspace are ignored rather than refused; the response reports how many were actually removed.
path Parameters
workspaceIdWorkspace UUID
Delete automation runs › Responses
Number of runs deleted
Get one automation run
path Parameters
workspaceIdWorkspace UUID
idAutomation run UUID
Get one automation run › Responses
Automation run
Get one automation run's steps
The ordered steps of the run — model calls and the tool calls each one requested, with timings, per-step tokens and truncated input/output previews. Served apart from the run itself because that payload also feeds the paginated list and a workspace-room broadcast. Null for a run that never reported one: a skipped row, or one settled by the stuck-run reaper.
path Parameters
workspaceIdWorkspace UUID
idAutomation run UUID
Get one automation run's steps › Responses
Run telemetry