HTTP API¶

The server's OpenAPI document (version 1.13.0) is served at GET /api/openapi.json; this page is rendered from the checked-in snapshot that the UI client and the test suite are generated from. Every /api/* route except /api/health requires Authorization: Bearer <token> when a token is set (see Secure the server); requests over the Unix socket skip the check. Responses are JSON; errors carry an ErrorBody. Times are microseconds since the Unix epoch in UTC. List endpoints page by keyset cursor.

The MCP endpoint (POST /mcp) is not part of the OpenAPI document; see MCP tools, resources and prompts.

Health and server¶

`GET /api/counts`¶

Parameter	In	Type	Required	Description
`project`	query	string or null	no

Status	Body
200	`Counts` (application/json)

`GET /api/health`¶

Note

Exempt from the API token.

Status	Body
200	Server is up

`GET /api/server`¶

Status	Body
200	`ServerInfo` (application/json)

`GET /api/settings`¶

Status	Body
200	`Settings` (application/json)

`PATCH /api/settings`¶

Request body (application/json): SettingsPatch

Status	Body
200	`Settings` (application/json)

`GET /api/stream`¶

Parameter	In	Type	Required	Description
`since`	query	integer or null (int64)	no	Last sequence number the client has seen.

Status	Body
200	text/event-stream of hello, run.updated, task_run.updated, log.appended, event.created, flow.registered, rule.updated, variable.updated, artifact.updated, schedule.updated, backfill.created, backfill.updated, expectation.armed, expectation.met, expectation.lapsed, and resync

`GET /api/vocabulary`¶

Status	Body
200	`Vocabulary` (application/json)

Flows¶

`GET /api/flows`¶

Parameter	In	Type	Required	Description
`project`	query	string or null	no

Status	Body
200	`FlowSummary`[] (application/json)

`GET /api/flows/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`FlowSummary` (application/json)
404	no body

`DELETE /api/flows/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
204	no body
404	no body
409	Flow is live

`POST /api/flows/{id}/backfill`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): BackfillBody

Status	Body
201	`BackfillStatus` (application/json)
422	no body

`GET /api/flows/{id}/backfills`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`BackfillStatus`[] (application/json)

`POST /api/flows/{id}/pause`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	All schedules paused

`POST /api/flows/{id}/resume`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	All schedules resumed

`POST /api/flows/{id}/runs`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): CreateRunForFlowBody

Status	Body
201	`Run` (application/json)
422	Invalid parameters

`GET /api/flows/{id}/schedules`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`ScheduleRow`[] (application/json)

`POST /api/flows/{id}/schedules`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): ScheduleBody

Status	Body
201	`ScheduleRow` (application/json)
422	no body

`GET /api/flows/{id}/upcoming`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes
`projected`	query	integer or null	no	Also list this many fires of each active schedule past its materialized runs, computed without creating runs (at most 100).

Status	Body
200	`UpcomingItem`[] (application/json)

Runs¶

`GET /api/runs`¶

Parameter	In	Type	Required	Description
`project`	query	string or null	no
`flow`	query	string or null	no
`flow_id`	query	integer or null (int64)	no
`state_type`	query	string or null	no
`state_name`	query	string or null	no
`name`	query	string or null	no
`tags`	query	string or null	no	Tags the run must carry; a query string may pass them comma-separated.
`start_after`	query	integer or null (int64)	no	Inclusive lower bound on the run's start time (or creation when never started), microseconds.
`start_before`	query	integer or null (int64)	no
`sort`	query	string or null	no	`created_desc` (default), `created_asc`, `start_desc`, `start_asc`, `duration_desc`, `duration_asc`, `name_asc`.
`limit`	query	integer or null	no
`cursor`	query	integer or null (int64)	no	Keyset cursor: the id of the last run of the previous page (id-ordered sorts only).
`schedule_id`	query	integer or null (int64)	no
`backfill_id`	query	integer or null (int64)	no
`scheduled_after`	query	integer or null (int64)	no	Only runs with a scheduled time after this (upcoming lists).

Status	Body
200	`RunsPage` (application/json)

`POST /api/runs`¶

Request body (application/json): CreateRunBody

Status	Body
201	`Run` (application/json)
404	Unknown flow and no module given
422	no body

`GET /api/runs/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`Run` (application/json)
404	no body

`DELETE /api/runs/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
204	no body
404	no body

`GET /api/runs/{id}/artifacts`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`ArtifactRow`[] (application/json)

`POST /api/runs/{id}/cancel`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`Run` (application/json)
404	no body

`GET /api/runs/{id}/graph`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`RunGraph` (application/json)

`GET /api/runs/{id}/input`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	{input: } or {input: null} when nothing was stored
404	no body

`GET /api/runs/{id}/logs`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes
`after`	query	integer or null (int64)	no	Return rows with id greater than this (keyset cursor).
`level`	query	string or null	no	Minimum level: a Python numeric level or DEBUG, INFO, WARNING, ERROR, CRITICAL.
`search`	query	string or null	no
`limit`	query	integer or null	no

Status	Body
200	`LogsPage` (application/json)

`POST /api/runs/{id}/resume`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): ResumeBody

Status	Body
200	`Run` (application/json)
404	no body
409	no body

`GET /api/runs/{id}/tasks`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`TaskRun`[] (application/json)

`POST /api/runs/{id}/transition`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): TransitionBody

Status	Body
200	`Run` (application/json)
404	no body
409	`TransitionRejected` (application/json)

Task runs¶

`GET /api/task-runs`¶

Parameter	In	Type	Required
`run_id`	query	integer or null (int64)	no
`project`	query	string or null	no
`flow`	query	string or null	no
`state_type`	query	string or null	no
`state_name`	query	string or null	no
`name`	query	string or null	no
`start_after`	query	integer or null (int64)	no
`start_before`	query	integer or null (int64)	no
`limit`	query	integer or null	no
`cursor`	query	integer or null (int64)	no

Status	Body
200	`TaskRunsPage` (application/json)

`GET /api/task-runs/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`TaskRun` (application/json)
404	no body

`GET /api/task-runs/{id}/artifacts`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`ArtifactRow`[] (application/json)

`GET /api/task-runs/{id}/logs`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes
`after`	query	integer or null (int64)	no	Return rows with id greater than this (keyset cursor).
`level`	query	string or null	no	Minimum level: a Python numeric level or DEBUG, INFO, WARNING, ERROR, CRITICAL.
`search`	query	string or null	no
`limit`	query	integer or null	no

Status	Body
200	`LogsPage` (application/json)

Schedules¶

`POST /api/schedules/preview`¶

Request body (application/json): PreviewBody

Status	Body
200	`PreviewResponse` (application/json)
422	no body

`PATCH /api/schedules/{sid}`¶

Parameter	In	Type	Required	Description
`sid`	path	integer (int64)	yes

Request body (application/json): SchedulePatchBody

Status	Body
200	`ScheduleRow` (application/json)
422	no body

`DELETE /api/schedules/{sid}`¶

Parameter	In	Type	Required	Description
`sid`	path	integer (int64)	yes

Status	Body
204	no body
404	no body

`POST /api/schedules/{sid}/pause`¶

Parameter	In	Type	Required	Description
`sid`	path	integer (int64)	yes

Status	Body
200	`ScheduleRow` (application/json)

`POST /api/schedules/{sid}/resume`¶

Parameter	In	Type	Required	Description
`sid`	path	integer (int64)	yes

Status	Body
200	`ScheduleRow` (application/json)

`POST /api/schedules/{sid}/skips`¶

Parameter	In	Type	Required	Description
`sid`	path	integer (int64)	yes

Request body (application/json): SkipBody

Status	Body
200	`SkipResponse` (application/json)
404	no body
422	no body

`DELETE /api/schedules/{sid}/skips/{fire}`¶

Parameter	In	Type	Required	Description
`sid`	path	integer (int64)	yes
`fire`	path	integer (int64)	yes	The skipped fire time, in microseconds

Status	Body
200	`ScheduleRow` (application/json)
404	no body
422	no body

Backfills¶

`GET /api/backfills/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`BackfillStatus` (application/json)
404	no body

`POST /api/backfills/{id}/cancel`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`BackfillStatus` (application/json)

`POST /api/backfills/{id}/prefilter`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): PrefilterBody

Status	Body
200	no body

Events¶

`GET /api/events`¶

Parameter	In	Type	Required	Description
`name`	query	string or null	no	Exact name, or a prefix ending in `` (e.g. `run.`).
`resource_kind`	query	string or null	no
`resource_id`	query	string or null	no
`run_id`	query	integer or null (int64)	no
`flow_id`	query	integer or null (int64)	no
`after`	query	integer or null (int64)	no
`before`	query	integer or null (int64)	no
`limit`	query	integer or null	no
`cursor`	query	integer or null (int64)	no	Keyset cursor: the id of the last event of the previous page.
`ascending`	query	boolean	no	Ascending order when true (defaults to newest first).

Status	Body
200	`EventsPage` (application/json)

`POST /api/events`¶

Request body (application/json): EmitEventBody

Status	Body
201	`Event` (application/json)

`GET /api/events/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`Event` (application/json)
404	no body

Rules¶

`GET /api/rules`¶

Status	Body
200	`RuleRow`[] (application/json)

`POST /api/rules`¶

Request body (application/json): RuleBody

Status	Body
201	`RuleRow` (application/json)
422	no body

`GET /api/rules/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`RuleRow` (application/json)
404	no body

`PATCH /api/rules/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Request body (application/json): RulePatch

Status	Body
200	`RuleRow` (application/json)
404	no body
422	no body

`DELETE /api/rules/{id}`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
204	no body
404	no body
409	no body

`GET /api/rules/{id}/expectations`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes
`open`	query	boolean or null	no	Only open (armed) expectations; default true.
`limit`	query	integer or null	no

Status	Body
200	`Expectation`[] (application/json)
404	no body

`GET /api/rules/{id}/firings`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	`RuleFiring`[] (application/json)

`POST /api/rules/{id}/test`¶

Parameter	In	Type	Required	Description
`id`	path	integer (int64)	yes

Status	Body
200	Rendered actions against the latest matching event

Artifacts¶

`GET /api/artifacts`¶

Parameter	In	Type	Required	Description
`kind`	query	string or null	no
`key`	query	string or null	no
`flow`	query	string or null	no
`project`	query	string or null	no
`run_id`	query	integer or null (int64)	no
`limit`	query	integer or null	no
`after`	query	integer or null (int64)	no	Keyset cursor: the id of the last artifact of the previous page.

Status	Body
200	`ArtifactsPage` (application/json)

`POST /api/artifacts`¶

Request body (application/json): ArtifactBody

Status	Body
201	`ArtifactRow` (application/json)
422	no body

Variables¶

`GET /api/variables`¶

Status	Body
200	`VariableRow`[] (application/json)

`POST /api/variables`¶

Request body (application/json): VariableBody

Status	Body
201	`VariableRow` (application/json)
409	no body
422	no body

`GET /api/variables/{name}`¶

Parameter	In	Type	Required	Description
`name`	path	string	yes
`raw`	query	boolean or null	no	Return the stored ciphertext of a secret so a local client can decrypt it.

Status	Body
200	`VariableWithRaw` (application/json)
404	no body

`PATCH /api/variables/{name}`¶

Parameter	In	Type	Required	Description
`name`	path	string	yes

Request body (application/json): VariablePatch

Status	Body
200	`VariableRow` (application/json)
404	no body

`DELETE /api/variables/{name}`¶

Parameter	In	Type	Required	Description
`name`	path	string	yes

Status	Body
204	no body
404	no body

Resources¶

`POST /api/resources/acquire`¶

Request body (application/json): AcquireRequest

Status	Body
200	{lease: id} or

`POST /api/resources/release`¶

Request body (application/json): ReleaseRequest

Status	Body
200	no body

Engine (internal)¶

`POST /api/engine/failed`¶

Note

Used by engine processes to report to the server; not intended for clients and not covered by compatibility promises.

Request body (application/json): FailedRequest

Status	Body
200	Queued runs of the module failed

`POST /api/engine/heartbeat`¶

Note

Used by engine processes to report to the server; not intended for clients and not covered by compatibility promises.

Request body (application/json): HeartbeatRequest

Status	Body
200	{cancel: bool, active: bool}

`POST /api/engine/report`¶

Note

Used by engine processes to report to the server; not intended for clients and not covered by compatibility promises.

Request body (application/json): ReportRequest

Status	Body
200	`ReportResponse` (application/json)
404	no body

`POST /api/engine/work`¶

Note

Used by engine processes to report to the server; not intended for clients and not covered by compatibility promises.

Request body (application/json): WorkRequest

Status	Body
200	`WorkResponse` (application/json)

Schemas¶

`AcquireRequest`¶

Field	Type	Required
`resources`	object	yes
`run_id`	integer (int64)	yes
`wait_ms`	integer (int64)	no

`AfterSpec`¶

Field	Type	Required	Description
`flow`	string	yes	The first upstream (kept for 1.0 payloads and the run details link).
`flows`	array of string	no	Every upstream; empty for rows written before fan-in existed.
`key`	string or null	no	Parameter that identifies a batch: the downstream runs once per value.
`parameters`	object	no

`ArtifactBody`¶

Field	Type	Required
`data`	object	yes
`key`	string or null	no
`kind`	string	yes
`run_id`	integer (int64)	yes
`task_run_id`	integer or null (int64)	no

`ArtifactListItem`¶

One artifact in the cross-run listing, with its run's identity.

Type: any.

`ArtifactRow`¶

A stored artifact attached to a run and optionally a task run.

Field	Type	Required	Description
`created_at`	`i64`	yes
`data`	object	yes
`external_id`	`Id`	yes
`id`	integer (int64)	yes
`key`	string or null	no
`kind`	string	yes	`markdown`, `table`, `progress`, `link`, or `image`.
`run_id`	integer (int64)	yes
`task_run_id`	integer or null (int64)	no
`updated_at`	`i64`	yes

`ArtifactsPage`¶

Field	Type	Required	Description
`items`	`ArtifactListItem`[]	yes
`next_cursor`	integer or null (int64)	no

`Backfill`¶

Field	Type	Required
`cancelled`	boolean	yes
`concurrency`	integer (int64)	yes
`created_at`	`i64`	yes
`end_value`	string	yes
`external_id`	`Id`	yes
`extra_parameters`	object	no
`flow_id`	integer (int64)	yes
`id`	integer (int64)	yes
`interval_secs`	number (double)	yes
`parameter`	string	yes
`start_value`	string	yes
`total`	integer (int64)	yes

`BackfillBody`¶

Field	Type	Required	Description
`concurrency`	integer or null (int64)	no
`end`	string	yes
`extra_parameters`	object	no
`interval`	any	no	Seconds, or a shorthand like `1d`, `12h`, `30m`. Default one day.
`parameter`	string	yes
`reverse`	boolean	no
`start`	string	yes

`BackfillStatus`¶

Type: any.

`CatchupPolicy`¶

One of: skip, latest, all.

`Counts`¶

Field	Type	Required	Description
`active`	integer (int64)	yes	Number of non-terminal runs held in memory.
`flows`	object	yes	Run counts by flow id and state type.
`runs`	object	yes	Run counts by state type.
`task_runs`	object	yes	Task run counts by state type.

`CreateRunBody`¶

Create a run by flow key, registering the flow when the server does not know it yet (offline handoff from another project).

Field	Type	Required	Description
`created_by`	string or null	no
`description`	string or null	no
`flow`	string	yes
`flow_group`	string or null	no	The flow's declared group; absent leaves the registered group as it is.
`flow_tags`	array of string	no
`module`	string or null	no
`name`	string or null	no
`options`	object	no
`parameter_schema`	object	no
`parameters`	object	no
`project`	string	yes
`source_dir`	string or null	no
`tags`	array of string	no

`CreateRunForFlowBody`¶

Field	Type	Required
`name`	string or null	no
`parameters`	object	no
`tags`	array of string	no

`DownstreamSkip`¶

A flow that runs after the skipped one, directly or further down its chain.

Field	Type	Required	Description
`fires`	array of integer (int64)	yes	The skipped fires whose runs of this flow will be created Skipped.
`flow`	string	yes
`project`	string	yes

`EmitEventBody`¶

Field	Type	Required
`flow_id`	integer or null (int64)	no
`name`	string	yes
`payload`	object	no
`resource`	null or `Resource`	no
`run_id`	integer or null (int64)	no

`ErrorBody`¶

Field	Type	Required	Description
`error`	string	yes

`Event`¶

Field	Type	Required	Description
`external_id`	`Id`	yes
`flow_id`	integer or null (int64)	no
`id`	integer (int64)	yes
`name`	string	yes
`occurred`	`i64`	yes
`payload`	object	no
`related`	`Resource`[]	no
`resource`	`Resource`	yes
`run_id`	integer or null (int64)	no
`seq`	integer (int64)	yes	Sequence number: the writer assigns ids in commit order.

`EventEntry`¶

Field	Type	Required	Description
`name`	string	yes	The name a rule matches on, e.g. `run.failed`.
`payload_fields`	array of string	yes	The payload keys the emit site sets.
`resource`	string	yes	The resource kind the event hangs off.
`when`	string	yes	One sentence on when the engine records it.

`EventsPage`¶

Field	Type	Required	Description
`items`	`Event`[]	yes
`next_cursor`	integer or null (int64)	no

`Expectation`¶

An armed expectation of a proactive rule.

Field	Type	Required	Description
`armed_at`	`i64`	yes
`deadline`	`i64`	yes
`flow_id`	integer or null (int64)	no
`id`	integer (int64)	yes
`key`	string	yes	`run:<id>` or `flow:<id>`.
`rule_id`	integer (int64)	yes
`run_id`	integer or null (int64)	no
`status`	string	yes	`open`, `met`, `lapsed`, or `cancelled`.

`FailedRequest`¶

Field	Type	Required
`engine_id`	string	yes
`isolated`	boolean	no
`module`	string	yes
`nice`	integer (int32)	no
`source_dir`	string	yes
`traceback`	string	yes

`Flow`¶

A registered flow. Identity is (project, name).

Field	Type	Required	Description
`created_at`	`i64`	yes
`description`	string or null	no
`error`	string or null	no
`external_id`	`Id`	yes
`group`	string or null	no	The group the flow is listed under, declared in Python with `group=`. Null means none was declared and the flow is grouped under its project; API responses carry the resolved value, so clients never apply that fallback themselves.
`id`	integer (int64)	yes
`last_seen_at`	`i64`	yes
`live`	boolean	no	Whether the running server has this flow registered from code.
`module`	string	yes
`name`	string	yes
`options`	object	no
`parameter_schema`	object	no
`project`	string	yes
`source_dir`	string	yes
`tags`	array of string	no

`FlowOptions`¶

Flow-level options declared in Python and stored as JSON on the flow row.

Field	Type	Required	Description
`after`	null or `AfterSpec`	no
`crash_retries`	integer or null (int64)	no
`disable_after`	array or null	no	(count, window_seconds, persist_seconds)
`has_bulk_complete`	boolean	no
`has_crash_hooks`	boolean	no
`isolated`	boolean	no
`log_prints`	boolean	no
`max_concurrent`	integer or null (int64)	no
`on_overlap`	string	no	`enqueue`, `skip`, or `cancel_new`.
`priority`	integer (int64)	no
`resources`	object	no
`retries`	integer (int64)	no
`schedules`	`ScheduleDecl`[]	no
`timeout_seconds`	number or null (double)	no

`FlowSummary`¶

Type: any.

`GraphEdge`¶

Field	Type	Required	Description
`from`	integer (int64)	yes
`to`	integer (int64)	yes

`GraphNode`¶

Field	Type	Required
`created_at`	integer (int64)	yes
`dynamic_key`	string	yes
`end_time`	integer or null (int64)	no
`external_id`	string	yes
`id`	integer (int64)	yes
`name`	string	yes
`start_time`	integer or null (int64)	no
`state`	`State`	yes

`HeartbeatRequest`¶

Field	Type	Required	Description
`engine_id`	string	yes
`run_id`	integer (int64)	yes

`Id`¶

Type: string.

`Log`¶

Field	Type	Required
`id`	integer (int64)	yes
`level`	integer (int32)	yes
`logger`	string	yes
`message`	string	yes
`run_id`	integer (int64)	yes
`task_run_id`	integer or null (int64)	no
`timestamp`	`i64`	yes

`LogsPage`¶

Field	Type	Required	Description
`items`	`Log`[]	yes
`next_cursor`	integer or null (int64)	no

`PrefilterBody`¶

Field	Type	Required	Description
`skip`	array of string	yes

`PreviewBody`¶

Type: any.

`PreviewResponse`¶

Field	Type	Required	Description
`next`	array of integer (int64)	yes
`timezone`	string	yes

`ProjectedFire`¶

A fire past the look-ahead, computed from the schedule; no run exists for it yet.

Field	Type	Required	Description
`projected`	boolean	yes	Always true.
`schedule_id`	integer (int64)	yes
`scheduled_time`	integer (int64)	yes
`skipped`	boolean	yes
`skipped_at`	integer or null (int64)	no
`skipped_by`	string or null	no

`ReleaseRequest`¶

Field	Type	Required	Description
`lease`	integer (int64)	yes
`run_id`	integer (int64)	yes

`ReportRequest`¶

Field	Type	Required
`engine_id`	string	yes
`events`	array of object	yes
`run_id`	integer (int64)	yes

`ReportResponse`¶

Field	Type	Required
`applied`	integer	yes
`cancel`	boolean	yes
`last_seq`	integer (int64)	yes
`skipped`	integer	yes

`Resource`¶

What an event is about.

Field	Type	Required	Description
`id`	string	yes
`kind`	string	yes	`run`, `task_run`, `flow`, `schedule`, `rule`, or `custom`.
`name`	string	no

`ResumeBody`¶

Field	Type	Required	Description
`input`	any	yes	The answer handed to `wait_for_input` on the resumed attempt (any JSON).

`RouteSpec`¶

Field	Type	Required	Description
`id`	integer	yes
`method`	string	yes
`path`	string	yes
`source`	string or null	no	Where the handler is defined (module and function), for the settings page.

`RuleAction`¶

One rule action. kind selects the variant; other fields are optional.

Field	Type	Required	Description
`body`	string or null	no
`callable`	string or null	no	Name of the Python callable for `call` actions (code rules).
`flow`	string or null	no
`headers`	object	no
`kind`	string	no	`run_flow`, `cancel_run`, `set_state`, `pause_schedule`, `resume_schedule`, `webhook`, `email`, `call`.
`message`	string or null	no
`method`	string or null	no
`parameters`	object	no
`state_type`	string or null	no
`subject`	string or null	no
`to`	array of string	no
`url`	string or null	no

`RuleBody`¶

Type: any.

`RuleClock`¶

Clock of a clock-armed proactive rule: a cron expression in a timezone.

Field	Type	Required	Description
`cron`	string	no
`tz`	string or null	no

`RuleFiring`¶

Field	Type	Required
`event_id`	integer or null (int64)	no
`id`	integer (int64)	yes
`outcomes`	array of object	yes
`rule_id`	integer (int64)	yes
`run_id`	integer or null (int64)	no
`timestamp`	`i64`	yes

`RuleMatch`¶

Match clause of a rule.

Field	Type	Required	Description
`events`	array of string	no	Event names, or prefixes ending in `*`.
`flows`	array of string	no
`project`	string or null	no
`states`	array of string	no
`tags`	array of string	no

`RulePatch`¶

Field	Type	Required
`allow_self`	boolean or null	no
`at`	object	no
`cooldown_seconds`	number or null (double)	no
`do`	array or null	no
`enabled`	boolean or null	no
`max_per_minute`	integer or null (int64)	no
`name`	string or null	no
`once`	string or null	no
`unless`	object	no
`when`	object	no
`within`	number or null (double)	no

`RuleRow`¶

Type: any.

`RuleSpec`¶

Field	Type	Required	Description
`allow_self`	boolean	no
`at`	null or `RuleClock`	no
`cooldown_seconds`	number (double)	no
`do`	`RuleAction`[]	no
`max_per_minute`	integer (int64)	no
`once`	string	no	`per_run` or `never`.
`unless`	null or `RuleMatch`	no
`when`	`RuleMatch`	no
`within`	number or null (double)	no	Seconds after the arming event (or look-back before a clock tick).

`Run`¶

Field	Type	Required	Description
`attempt`	integer (int64)	no
`backfill_id`	integer or null (int64)	no
`crash_count`	integer (int32)	yes
`created_at`	`i64`	yes
`created_by`	string	no
`end_time`	null or `i64`	no
`engine_id`	string or null	no
`engine_pid`	integer or null (int64)	no
`external_id`	`Id`	yes
`failure_count`	integer (int32)	yes
`flow_id`	integer (int64)	yes
`flow_name`	string	yes
`group`	string	no	The flow's group, read through the flow: never stored on the run.
`id`	integer (int64)	yes
`name`	string	yes
`parameters`	object	no
`parent_run_id`	integer or null (int64)	no
`priority`	integer (int64)	no
`project`	string	yes
`report_seq`	integer (int64)	no
`schedule_id`	integer or null (int64)	no
`scheduled_time`	null or `i64`	no
`start_time`	null or `i64`	no
`state`	`State`	yes
`tags`	array of string	no
`task_counts`	object	no	Task runs of this run counted by state type; empty until tasks exist.
`total_run_time`	null or `i64`	no

`RunGraph`¶

Field	Type	Required
`edges`	`GraphEdge`[]	yes
`nodes`	`GraphNode`[]	yes
`run_id`	integer (int64)	yes

`RunsPage`¶

Field	Type	Required	Description
`items`	`Run`[]	yes
`next_cursor`	integer or null (int64)	no

`Schedule`¶

One of: object, object, object.

`ScheduleBody`¶

Type: any.

`ScheduleDecl`¶

Type: any.

`SchedulePatchBody`¶

Field	Type	Required
`anchor`	integer or null (int64)	no
`catchup`	null or `CatchupPolicy`	no
`catchup_max`	integer or null (int64)	no
`cron`	string or null	no
`day_or`	boolean or null	no
`interval`	number or null (double)	no
`persist`	boolean or null	no
`rrule`	string or null	no
`timezone`	string or null	no

`ScheduleRow`¶

Placeholders for later phases; defined now so the schema and API types are stable from the start. A stored schedule row: the schedule itself plus policy and bookkeeping.

Field	Type	Required	Description
`active`	boolean	yes
`catchup`	`CatchupPolicy`	yes
`catchup_max`	integer (int64)	yes
`code_key`	string or null	no
`created_at`	`i64`	yes
`external_id`	`Id`	yes
`flow_id`	integer (int64)	yes
`id`	integer (int64)	yes
`next_fire`	null or `i64`	no
`paused_reason`	string or null	no
`paused_until`	null or `i64`	no
`persist`	boolean	yes
`schedule`	`Schedule`	yes
`skipped`	integer (int64)	no	Future fires skipped by a person, counted by the scheduler (not stored).
`source`	string	yes	`code` for schedules declared on the flow, `ui` for ones created in the interface, `mcp` for ones created by an agent. Startup reconciliation singles out `code` alone; every other value is left as it is.
`updated_at`	`i64`	yes

`ServerInfo`¶

Field	Type	Required
`engines`	array of any	yes
`home`	string	yes
`pid`	integer (int32)	yes
`queued`	integer	yes
`served_dir`	string or null	no
`started_at`	integer (int64)	yes
`stream_seq`	integer (int64)	yes
`url`	string	yes
`version`	string	yes

`Settings`¶

Field	Type	Required
`catchup_default`	string	yes
`crash_retries_default`	integer (int64)	yes
`custom_routes`	`RouteSpec`[]	yes
`database_bytes`	integer (int64)	yes
`database_path`	string	yes
`email_configured`	boolean	yes
`engine_max_runs`	integer (int32)	yes
`engine_saturation_risk`	boolean	yes
`home`	string	yes
`host`	string	yes
`max_engines`	integer	yes
`pid`	integer (int32)	yes
`port`	integer (int32)	yes
`resources`	object	yes
`retain_days`	integer (int64)	yes
`saturation_flows`	array of string	yes
`saturation_reason`	string or null	no
`secret_key_missing`	boolean	yes
`secret_key_present`	boolean	yes
`served_dir`	string or null	no
`version`	string	yes
`wal_bytes`	integer (int64)	yes

`SettingsPatch`¶

Field	Type	Required
`crash_retries`	integer or null (int64)	no
`resources`	object or null	no
`retain_days`	integer or null (int64)	no

`SkipBody`¶

Field	Type	Required	Description
`by`	string or null	no	Who asked: `ui` or `api` (the default).
`fires`	array of integer (int64)	no	Fire times to skip, in microseconds, as the upcoming list gives them.
`next`	integer or null	no	Skip the next N fires not already skipped instead.

`SkipResponse`¶

Field	Type	Required	Description
`downstream`	`DownstreamSkip`[]	yes
`schedule`	`ScheduleRow`	yes
`skipped`	array of integer (int64)	yes	The fires this request skipped.

`State`¶

Field	Type	Required
`details`	object	no
`message`	string or null	no
`name`	string	yes
`timestamp`	`i64`	yes
`type`	`StateType`	yes

`StateEntry`¶

Field	Type	Required	Description
`is_sub_state`	boolean	yes
`name`	string	yes
`state_type`	string	yes	For a sub-state, the type it belongs to; for a type, itself.

`StateType`¶

One of: Scheduled, Pending, Running, Completed, Failed, Cancelled, Crashed, Paused, Cancelling.

`TaskRun`¶

Field	Type	Required	Description
`crash_count`	integer (int32)	yes
`created_at`	`i64`	yes
`dynamic_key`	string	yes
`end_time`	null or `i64`	no
`external_id`	`Id`	yes
`failure_count`	integer (int32)	yes
`flow_id`	integer (int64)	no
`flow_name`	string	no
`id`	integer (int64)	yes
`name`	string	yes
`parents`	`Id`[]	no	External ids of task runs this one waited on (futures and wait_for).
`project`	string	no
`run_id`	integer (int64)	yes
`run_name`	string	no
`start_time`	null or `i64`	no
`state`	`State`	yes
`task_key`	string	yes
`total_run_time`	null or `i64`	no

`TaskRunsPage`¶

Field	Type	Required	Description
`items`	`TaskRun`[]	yes
`next_cursor`	integer or null (int64)	no

`TransitionBody`¶

Field	Type	Required
`details`	object	no
`force`	boolean	no
`message`	string or null	no
`name`	string or null	no
`type`	`StateType`	yes

`TransitionRejected`¶

Field	Type	Required
`current`	null or `State`	no
`error`	string	yes
`reason`	string	yes

`UpcomingItem`¶

One entry of the upcoming list: a run, or with projected=N a fire without one.

One of: UpcomingRun, ProjectedFire.

`UpcomingRun`¶

A materialized run in the upcoming list.

Type: any.

`VariableBody`¶

Field	Type	Required
`name`	string	yes
`overwrite`	boolean	no
`secret`	boolean	no
`tags`	array of string	no
`value`	object	yes

`VariablePatch`¶

Field	Type	Required
`secret`	boolean or null	no
`tags`	array or null	no
`value`	object	no

`VariableRow`¶

Field	Type	Required	Description
`created_at`	`i64`	yes
`name`	string	yes
`secret`	boolean	yes
`tags`	array of string	no
`updated_at`	`i64`	yes
`value`	object	yes	Plain JSON value, or `"********"` for secrets in API responses.

`VariableWithRaw`¶

Type: any.

`Vocabulary`¶

Field	Type	Required	Description
`events`	`EventEntry`[]	yes	Every engine-emitted event, in catalogue order.
`reserved_prefixes`	array of string	yes	Prefixes the engine owns. A name under one of these must be an entry in `events`; any other name is a custom event and is never checked.
`states`	`StateEntry`[]	yes	Every value a rule's `states` accepts: the types then the sub-states. A rule naming a type also matches that type's sub-states.

`WorkItem`¶

Work handed to an engine.

Field	Type	Required	Description
`cancel_requested`	boolean	yes
`external_id`	string	yes
`flow`	string	yes
`kind`	string	no	`run`, `hooks`, or `bulk_complete`.
`options`	object	yes
`parameters`	object	yes
`payload`	object	no
`project`	string	yes
`run_id`	integer (int64)	yes
`run_name`	string	yes

`WorkRequest`¶

Field	Type	Required	Description
`engine_id`	string	yes
`isolated`	boolean	no
`module`	string	yes
`nice`	integer (int32)	no
`pid`	integer (int32)	yes
`source_dir`	string	yes
`wait_ms`	integer (int64)	no	Long-poll wait in milliseconds (max 30000).

`WorkResponse`¶

Field	Type	Required	Description
`exit`	boolean	no
`run`	null or `WorkItem`	no

`i64`¶

Type: integer (int64).

HTTP API¶

Health and server¶

GET /api/counts¶

GET /api/health¶

GET /api/server¶

GET /api/settings¶

PATCH /api/settings¶

GET /api/stream¶

GET /api/vocabulary¶

Flows¶

GET /api/flows¶

GET /api/flows/{id}¶

DELETE /api/flows/{id}¶

POST /api/flows/{id}/backfill¶

GET /api/flows/{id}/backfills¶

POST /api/flows/{id}/pause¶

POST /api/flows/{id}/resume¶

POST /api/flows/{id}/runs¶

GET /api/flows/{id}/schedules¶

POST /api/flows/{id}/schedules¶

GET /api/flows/{id}/upcoming¶

Runs¶

GET /api/runs¶

POST /api/runs¶

GET /api/runs/{id}¶

DELETE /api/runs/{id}¶

GET /api/runs/{id}/artifacts¶

POST /api/runs/{id}/cancel¶

GET /api/runs/{id}/graph¶

GET /api/runs/{id}/input¶

GET /api/runs/{id}/logs¶

POST /api/runs/{id}/resume¶

GET /api/runs/{id}/tasks¶

POST /api/runs/{id}/transition¶

Task runs¶

GET /api/task-runs¶

GET /api/task-runs/{id}¶

GET /api/task-runs/{id}/artifacts¶

GET /api/task-runs/{id}/logs¶

Schedules¶

POST /api/schedules/preview¶

PATCH /api/schedules/{sid}¶

DELETE /api/schedules/{sid}¶

POST /api/schedules/{sid}/pause¶

POST /api/schedules/{sid}/resume¶

POST /api/schedules/{sid}/skips¶

DELETE /api/schedules/{sid}/skips/{fire}¶

Backfills¶

GET /api/backfills/{id}¶

POST /api/backfills/{id}/cancel¶

POST /api/backfills/{id}/prefilter¶

Events¶

GET /api/events¶

POST /api/events¶

GET /api/events/{id}¶

Rules¶

GET /api/rules¶

POST /api/rules¶

GET /api/rules/{id}¶

PATCH /api/rules/{id}¶

DELETE /api/rules/{id}¶

GET /api/rules/{id}/expectations¶

GET /api/rules/{id}/firings¶

POST /api/rules/{id}/test¶

Artifacts¶

GET /api/artifacts¶

POST /api/artifacts¶

Variables¶

GET /api/variables¶

POST /api/variables¶

GET /api/variables/{name}¶

PATCH /api/variables/{name}¶

DELETE /api/variables/{name}¶

Resources¶

POST /api/resources/acquire¶

POST /api/resources/release¶

Engine (internal)¶

POST /api/engine/failed¶

POST /api/engine/heartbeat¶

POST /api/engine/report¶

`GET /api/counts`¶

`GET /api/health`¶

`GET /api/server`¶

`GET /api/settings`¶

`PATCH /api/settings`¶

`GET /api/stream`¶

`GET /api/vocabulary`¶

`GET /api/flows`¶

`GET /api/flows/{id}`¶

`DELETE /api/flows/{id}`¶

`POST /api/flows/{id}/backfill`¶

`GET /api/flows/{id}/backfills`¶

`POST /api/flows/{id}/pause`¶

`POST /api/flows/{id}/resume`¶

`POST /api/flows/{id}/runs`¶

`GET /api/flows/{id}/schedules`¶

`POST /api/flows/{id}/schedules`¶

`GET /api/flows/{id}/upcoming`¶

`GET /api/runs`¶

`POST /api/runs`¶

`GET /api/runs/{id}`¶

`DELETE /api/runs/{id}`¶

`GET /api/runs/{id}/artifacts`¶

`POST /api/runs/{id}/cancel`¶

`GET /api/runs/{id}/graph`¶

`GET /api/runs/{id}/input`¶

`GET /api/runs/{id}/logs`¶

`POST /api/runs/{id}/resume`¶

`GET /api/runs/{id}/tasks`¶

`POST /api/runs/{id}/transition`¶

`GET /api/task-runs`¶

`GET /api/task-runs/{id}`¶

`GET /api/task-runs/{id}/artifacts`¶

`GET /api/task-runs/{id}/logs`¶

`POST /api/schedules/preview`¶

`PATCH /api/schedules/{sid}`¶

`DELETE /api/schedules/{sid}`¶

`POST /api/schedules/{sid}/pause`¶

`POST /api/schedules/{sid}/resume`¶

`POST /api/schedules/{sid}/skips`¶

`DELETE /api/schedules/{sid}/skips/{fire}`¶

`GET /api/backfills/{id}`¶

`POST /api/backfills/{id}/cancel`¶

`POST /api/backfills/{id}/prefilter`¶

`GET /api/events`¶

`POST /api/events`¶

`GET /api/events/{id}`¶

`GET /api/rules`¶

`POST /api/rules`¶

`GET /api/rules/{id}`¶

`PATCH /api/rules/{id}`¶

`DELETE /api/rules/{id}`¶

`GET /api/rules/{id}/expectations`¶

`GET /api/rules/{id}/firings`¶

`POST /api/rules/{id}/test`¶

`GET /api/artifacts`¶

`POST /api/artifacts`¶

`GET /api/variables`¶

`POST /api/variables`¶

`GET /api/variables/{name}`¶

`PATCH /api/variables/{name}`¶

`DELETE /api/variables/{name}`¶

`POST /api/resources/acquire`¶

`POST /api/resources/release`¶

`POST /api/engine/failed`¶

`POST /api/engine/heartbeat`¶

`POST /api/engine/report`¶

`POST /api/engine/work`¶

`AcquireRequest`¶

`AfterSpec`¶

`ArtifactBody`¶

`ArtifactListItem`¶

`ArtifactRow`¶

`ArtifactsPage`¶

`Backfill`¶

`BackfillBody`¶

`BackfillStatus`¶

`CatchupPolicy`¶

`Counts`¶

`CreateRunBody`¶