HTTP API

The server's OpenAPI document (version 3.3.1) 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/settings/environment

Status	Body
200	Environment (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
group	query	string or null	no	The resolved group: the one the flow declared, else its project.

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
200	RunConflict (application/json)
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
group	query	string or null	no	The resolved group: the one the flow declared, else its project.
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.
params	query	string or null	no	key=value pairs the run's parameters must match (comma-separated in a query string). Without a start bound, the search covers the last 30 days.
attributes	query	string or null	no	key=value pairs the run's attributes must match, as params.
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
200	RunConflict (application/json)
201	Run (application/json)
404	Unknown flow and no module given
422	no body

POST /api/runs/bulk

Request body (application/json): BulkBody

Status	Body
200	BulkResult (application/json)
422	no body

GET /api/runs/compare

Parameter	In	Type	Required	Description
ids	query	string	yes	Two run ids, comma separated: the baseline first, the run in question second.

Status	Body
200	RunComparison (application/json)
404	no body
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)

PATCH /api/runs/{id}/attributes

Also served on POST, which is what the engine client speaks.

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

Request body (application/json): object

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

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
pass	query	integer or null (int64)	no	One execution of the run's body: 0 the first time, the next after a resume or an in-process flow retry.

Status	Body
200	RunGraph (application/json)

GET /api/runs/{id}/input

Parameter	In	Type	Required	Description
id	path	integer (int64)	yes
index	query	integer or null (int64)	no	Which question: 0 is the first wait_for_input call of the body.

Status	Body
200	With index: {answer: {prompt, input}} or {answer: null}. Without: the pending question, every answer given, and {input} for the first
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}/messages/{topic}

Send a message to a run on topic.

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

Request body (application/json): MessageBody

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

GET /api/runs/{id}/receive

Atomically check the answer store and pending messages for a receive(topic) call. Used by the engine during replay so a message that arrives between passes is found without pausing again.

Parameter	In	Type	Required	Description
id	path	integer (int64)	yes
topic	query	string	yes
index	query	integer (int64)	yes	The question ordinal this receive call expects.

Status	Body
200	{claimed: bool, answer: {...} or null}
404	no body

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

POST /api/runs/{id}/retry

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

Request body (application/json): RetryBody

Status	Body
201	RetryResponse (application/json)
404	no body
409	no body
422	no body

GET /api/runs/{id}/state

Parameter	In	Type	Required	Description
id	path	integer (int64)	yes
scope	query	string or null	no	The task's dynamic key, or empty for the flow body; with key, reads one value.
key	query	string or null	no

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

POST /api/runs/{id}/state

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

Request body (application/json): StateBody

Status	Body
200	ok
404	no body
422	no body

GET /api/runs/{id}/tasks

Parameter	In	Type	Required	Description
id	path	integer (int64)	yes
pass	query	integer or null (int64)	no	One execution of the run's body: 0 the first time, the next after a resume or an in-process flow retry.

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	Description
run_id	query	integer or null (int64)	no
pass	query	integer or null (int64)	no	Only task runs of this execution of the run's body.
project	query	string or null	no
group	query	string or null	no	The resolved group: the one the flow declared, else its project.
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}/now

Start a continuous schedule's waiting run now: it joins the line at once instead of after the rest of its delay.

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

Status	Body
200	ScheduleRow (application/json)
404	no body
409	Not continuous, paused, or no run is waiting

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
409	The schedule is continuous and has no fire times
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
group	query	string or null	no	The resolved group: the one the flow declared, else its project.
run_id	query	integer or null (int64)	no
task_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.
decrypt	query	boolean or null	no	Return a secret decrypted, for a remote worker's engine. Refused unless the server has a token.

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/local-path

A run on a worker used a LocalTarget outside the worker's shared paths.

Note

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

Request body (application/json): LocalPathBody

Status	Body
204	no body

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)

Other

GET /api/database

Status	Body
200	DatabaseInfo (application/json)

POST /api/database/backup

Status	Body
200	BackupResult (application/json)
500	no body

POST /api/database/reset

Request body (application/json): ResetBody

Status	Body
200	ResetResult (application/json)
409	A reset is already running
422	Missing or unknown scope
500	The copy failed; nothing was deleted

GET /api/metrics

Status	Body
200	any (text/plain)

GET /api/metrics/history

Status	Body
200	MetricsHistory (application/json)

GET /api/projects

Status	Body
200	ProjectSummary[] (application/json)

GET /api/projects/{name}

Parameter	In	Type	Required	Description
name	path	string	yes

Status	Body
200	ProjectPreview (application/json)
404	no body

DELETE /api/projects/{name}

Parameter	In	Type	Required	Description
name	path	string	yes

Status	Body
200	DeletedCounts (application/json)
404	no body
409	The project is served, or a run of it is in progress
503	The database is being reset

GET /api/queue

Status	Body
200	QueueView (application/json)

GET /api/results/{key}

Parameter	In	Type	Required	Description
key	path	string	yes

Status	Body
200	array of integer (int32) (application/octet-stream)
404	no body

PUT /api/results/{key}

Parameter	In	Type	Required	Description
key	path	string	yes
part	query	integer (int32)	no	The chunk number, from 0. Part 0 starts the upload over.
last	query	boolean	no	Whether this is the last chunk: the result becomes visible when it lands.
upload	query	string or null	no	Names this upload, so two uploads of one key (two workers saving the same cache entry) write separate temporary files.
offset	query	integer or null (int64)	no	Where this chunk starts in the result. A retried chunk lands at the same place instead of being appended a second time.

Request body (application/octet-stream): array of integer (int32)

Status	Body
204	no body
400	no body
413	Over the size bound

GET /api/scheduler

Status	Body
200	SchedulerStatus (application/json)

POST /api/scheduler/pause

Request body (application/json): PauseBody

Status	Body
200	SchedulerStatus (application/json)
422	no body

POST /api/scheduler/resume

Status	Body
200	SchedulerStatus (application/json)

GET /api/workers

Status	Body
200	WorkerView[] (application/json)

POST /api/workers/register

Request body (application/json): RegisterBody

Status	Body
200	RegisterResponse (application/json)
403	The server has no token
409	Another major version

PATCH /api/workers/{id}

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

Request body (application/json): WorkerPatch

Status	Body
200	WorkerView[] (application/json)
404	no body
422	no body

DELETE /api/workers/{id}

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

Status	Body
204	no body
404	no body
409	The worker is not offline

POST /api/workers/{id}/drain

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

Status	Body
200	WorkerView[] (application/json)
404	no body
409	no body

POST /api/workers/{id}/heartbeat

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

Request body (application/json): HeartbeatBody

Status	Body
200	HeartbeatResponse (application/json)
409	Unknown to this server: register again

POST /api/workers/{id}/leave

The worker is stopping cleanly: it turns offline now. Its own shutdown drain is not left behind, so it registers online when it comes back; a drain an operator set before the shutdown is kept by the worker not calling this.

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

Status	Body
204	no body
404	no body

POST /api/workers/{id}/resume

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

Status	Body
200	WorkerView[] (application/json)
404	no body
409	no body

GET /api/workers/{id}/timeline

Parameter	In	Type	Required	Description
id	path	integer (int64)	yes	A worker id, or 0 for the server
hours	query	integer or null (int32)	no	Hours back from now (default 6, at most 48).

Status	Body
200	Timeline (application/json)
404	no body

Schemas

AcquireRequest

Field	Type	Required	Description
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	Description
data	object	yes
key	string or null	no
kind	string	yes
run_id	integer (int64)	yes
task_run_id	integer or null (int64)	no

ArtifactDiff

Field	Type	Required	Description
changed	boolean	yes	Present on one side only, or data differs.
key	string or null	no
kind	string	yes
left	integer or null (int64)	no
right	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	Description
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	no	Last value of a range, inclusive; not needed with values.
extra_parameters	object	no
force	boolean	no	A restatement: runs ignore targets, caches, checkpoints and bulk_complete.
interval	any	no	Seconds, or a shorthand like 1d, 12h, 30m. Default one day.
missing_only	boolean	no	Leave out values whose latest run Completed.
parameter	string	yes
reverse	boolean	no
start	string	no	First value of a range; not needed with values.
values	array of string	no	Explicit parameter values instead of a range, in this order.

BackfillStatus

Type: any.

BackupResult

Field	Type	Required	Description
backups	integer	yes	db-*.sqlite copies after pruning.
path	string	yes	The copy just written.

BulkBody

Field	Type	Required	Description
action	string	yes	cancel, rerun, retry (from failure), or delete.
dry_run	boolean or null	no	Count only; defaults to true.
filter	any	no	The same filters as GET /api/runs, as an object; empty matches every run.

BulkResult

Field	Type	Required	Description
action	string	yes
affected	integer	yes	Runs the action applied to: every match for delete, non-terminal ones for cancel, terminal ones for rerun.
dry_run	boolean	yes
matched	integer	yes	Runs the filter matched, capped at 10,000.

CatchupPolicy

One of: skip, latest, all.

Checkpoint

A completed task run's stored result, keyed for replay.

Field	Type	Required	Description
dynamic_key	string	yes
input_hash	string	yes
pass	integer (int64)	yes
result_ref	string	yes
run_id	integer (int64)	yes
task_key	string	yes

CompareSummary

Field	Type	Required	Description
artifacts_changed	integer	yes
attributes_changed	integer	yes
new_errors	integer	yes
parameters_changed	integer	yes
tasks_duration_changed	integer	yes	Tasks whose duration moved by more than 10 percent and more than a second.
tasks_state_changed	integer	yes

ConfigEntry

Field	Type	Required	Description
key	string	yes
secret	boolean	yes	True when the value is set and hidden.
source	string	yes	flag, env, app, toml, settings, or default.
source_name	string or null	no	The flag, variable, app.serve() argument, or table and key.
table	string	yes
value	object	yes	The value in effect; null when nothing sets it or it is secret.

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
delay	number or null (double)	no	Start this many seconds from now instead of now; not with scheduled_time.
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
idempotency_key	string or null	no	The same key for this flow within idempotency_ttl answers with the run first created.
idempotency_ttl	number or null (double)	no	Seconds the idempotency key stays valid (default 86400).
module	string or null	no
name	string or null	no
options	object	no
parameter_schema	object	no
parameters	object	no
project	string	yes
scheduled_time	integer or null (int64)	no	Start at this time (microseconds since the epoch) instead of now.
source_dir	string or null	no
tags	array of string	no

CreateRunForFlowBody

Field	Type	Required	Description
delay	number or null (double)	no	Start this many seconds from now instead of now; not with scheduled_time.
idempotency_key	string or null	no	The same key for this flow within idempotency_ttl answers with the run first created.
idempotency_ttl	number or null (double)	no	Seconds the idempotency key stays valid (default 86400).
name	string or null	no
parameters	object	no
scheduled_time	integer or null (int64)	no	Start at this time (microseconds since the epoch) instead of now.
tags	array of string	no

DatabaseInfo

Field	Type	Required	Description
backup_dir	string	yes	Where a reset writes its copy.
backups	integer	yes	db-*.sqlite copies in it.
bytes	integer (int64)	yes
counts	TableCounts	yes
path	string	yes
stale_projects	integer	yes	Projects none of whose flows this server serves.
wal_bytes	integer (int64)	yes

DeletedCounts

Rows deleted by a project removal or a reset.

Field	Type	Required	Description
artifacts	integer (int64)	yes
backfills	integer (int64)	yes
events	integer (int64)	yes
flows	integer (int64)	yes
logs	integer (int64)	yes
rules	integer (int64)	yes
runs	integer (int64)	yes
schedules	integer (int64)	yes
task_runs	integer (int64)	yes
variables	integer (int64)	yes

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

DurationDiff

Field	Type	Required	Description
delta	integer or null (int64)	no	right − left, microseconds, when both are known.
left	integer or null (int64)	no
right	integer or null (int64)	no

EmitEventBody

Field	Type	Required	Description
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

EngineStats

One of the worker's engines and the run it is executing.

Field	Type	Required	Description
engine_id	string	yes
flow	string or null	no
module	string	yes
run_id	integer or null (int64)	no
since_secs	integer (int64)	yes	Seconds in the current run, or since the engine started when it has none.
slot	integer	yes	The processor slot, from 1.
status	string	yes	starting, idle, running or draining.

EngineView

One engine as the Queue page shows it.

Field	Type	Required	Description
host	string	yes	server, or the worker's name.
id	string	yes
module	string	yes	The module the engine has loaded.
run_id	integer or null (int64)	no
since_secs	integer (int64)	yes	Seconds in the current run, or since the engine started when it has none.
slot	integer	yes	The processor slot on that host, from 1.
status	string	yes	starting, idle, running or draining.

EnvVariable

Field	Type	Required	Description
hidden	boolean	yes
name	string	yes
value	string or null	no	Null when hidden.

Environment

Field	Type	Required	Description
cereyan_toml	string or null	no	The served directory's cereyan.toml with its secrets hidden.
cereyan_unset	array of string	yes	Known CEREYAN_* variables that are not set.
configuration	ConfigEntry[]	yes
runtime	Runtime	yes
variables	EnvVariable[]	yes	The server process environment, CEREYAN_* first.

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	Description
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

FlowHealth

Field	Type	Required	Description
deadline	integer or null (int64)	no	The expect_by deadline in force, microseconds.
last_completed_at	integer or null (int64)	no	When the last Completed run ended, microseconds.
reasons	array of string	yes	Why, one sentence per finding; empty for a passing flow.
status	string	yes	PASS, WARN, or FAIL.

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) (count, window_seconds, persist_seconds); a window of None counts failures in a row, reset by a Completed run.
expect_by	string or null	no	Cron by which a run must have completed, in expect_by_tz.
expect_by_tz	string or null	no
expected_duration	number or null (double)	no	Seconds a run is expected to take; longer is overdue.
fresh_within	number or null (double)	no	Seconds a Completed run may be old before the flow is stale.
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.
overdue_factor	number or null (double)	no	Overdue past this many times the median of the last 20 Completed runs.
priority	integer (int64)	no
resources	object	no
retries	integer (int64)	no
runs_on	string or null	no	any (the default: the server or any matching worker) or server.
schedules	ScheduleDecl[]	no
start_deadline	number or null (double)	no	Seconds a run may wait to start before it is skipped; a schedule's own value wins.
timeout_seconds	number or null (double)	no
unique	null or UniqueSpec	no

FlowStats

Runs of one flow that started on a worker since it started.

Field	Type	Required	Description
cancelled	integer (int64)	yes
completed	integer (int64)	yes
crashed	integer (int64)	yes
failed	integer (int64)	yes
flow	string	yes
last_completed_at	integer or null (int64)	no	When the latest completed run here ended (microseconds).
running	integer (int64)	yes

FlowSummary

Type: any.

GraphEdge

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

GraphNode

Field	Type	Required	Description
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

HeartbeatBody

Field	Type	Required	Description
engines	array of string	no	Engine ids the worker runs now.
flows	array or null	no	Fingerprints again when the checkout changed.
meta	object	no	Metadata that changes: free memory, busy processors, git state.

HeartbeatRequest

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

HeartbeatResponse

Field	Type	Required	Description
commands	array of object	yes
drift	array of string	yes
state	string	yes
stats	null or HeartbeatStats	no

HeartbeatStats

Counts the server keeps for a worker: what its status page shows.

Field	Type	Required	Description
by_flow	FlowStats[]	yes
engines	EngineStats[]	yes
since	integer (int64)	yes	The worker's start time (microseconds): runs that started before it are not counted.

HostTotals

Field	Type	Required	Description
busy	integer	yes
count	integer	yes	Processors the host may run at once.
host	string	yes
state	string	yes	online, draining, or offline; the server is always online.

Id

Type: string.

InLine

Field	Type	Required	Description
can_start	boolean	yes
flow	string	yes
module	string	yes
overtaken_by	integer (int32)	yes	Later runs dispatched while this one could not start.
position	integer	yes	1 for the first run in line.
priority	integer (int64)	yes
project	string	yes
reason	string or null	no	Why it cannot start: resource:<name>, max_concurrent, backfill concurrency, or no processor.
run_id	integer (int64)	yes
run_name	string	yes
trigger	string	yes	What made the run: schedule, backfill, rule, dependency, crash rerun, or the run's created_by.
waited_us	integer (int64)	yes	Microseconds since the run joined the line.

Joining

Field	Type	Required	Description
at	integer (int64)	yes	When it joins the line, microseconds since the epoch.
flow	string	yes
kind	string	yes	retry, continuous, schedule, or delayed.
project	string	yes
run_id	integer (int64)	yes
run_name	string	yes
schedule_id	integer or null (int64)	no	The schedule that made the run, when one did.

LocalPathBody

Field	Type	Required	Description
path	string	yes	The resolved path of the LocalTarget, on the worker.
run_id	integer (int64)	yes

Log

Field	Type	Required	Description
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

MessageBody

Field	Type	Required	Description
payload	any	yes	The message payload: any JSON value.

MetricsHistory

Field	Type	Required	Description
interval_secs	integer (int64)	yes
samples	Sample[]	yes

Pause

The global pause: every schedule held at once, with a reason and an end.

Field	Type	Required	Description
reason	string or null	no
since	integer (int64)	yes	When the pause began, microseconds.
suppress_rules	boolean	yes	Rules that would fire are recorded as suppressed instead of acting.
until	integer or null (int64)	no	When the scheduler resumes on its own, microseconds; none means until resumed.

PauseBody

Field	Type	Required	Description
reason	string or null	no	Why, shown in the UI banner and recorded on the event.
suppress_rules	boolean	no	Record rules that would fire as suppressed instead of acting.
until	integer or null (int64)	no	When to resume on its own, microseconds; absent means until resumed.

PausedLoop

A continuous schedule that is paused: its loop has no run waiting.

Field	Type	Required	Description
flow	string	yes
project	string	yes
reason	string or null	no	paused by a person, or disabled by the flow's disable_after.
schedule_id	integer (int64)	yes
until	integer or null (int64)	no	When a disabled loop resumes on its own, microseconds since the epoch.

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

Processors

Field	Type	Required	Description
cap	integer	yes	The most count may be: this machine's CPU count.
count	integer	yes	Engines that may run at once.
hosts	HostTotals[]	yes	Processors per host: the server first, then each worker.
items	EngineView[]	yes
load	number or null (double)	no	The one-minute load average over the CPU count (1.0 is every CPU busy); absent where the platform does not report one.
source	string	yes	Where count came from: flag, toml, settings, or default.

ProjectPreview

Field	Type	Required	Description
active_runs	integer (int64)	yes	Runs that are Pending, Running, Paused or Cancelling.
backfills	integer (int64)	yes
events	integer (int64)	yes
flows	integer (int64)	yes
matching_rules	integer	yes	Rules whose match names the project; they are kept.
name	string	yes
runs	integer (int64)	yes
schedules	integer (int64)	yes
served	boolean	yes

ProjectSummary

Field	Type	Required	Description
flows	integer	yes
last_run_at	integer or null (int64)	no	Start time of the project's latest run.
live_flows	integer	yes	Flows this server registered from code.
name	string	yes
runs	integer (int64)	yes
served	boolean	yes	True when any of its flows is live, so it cannot be removed.

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

QueueView

Field	Type	Required	Description
in_line	InLine[]	yes
joining	Joining[]	yes
more	integer	yes	Runs in line past the listed ones.
paused_loops	PausedLoop[]	yes	Continuous schedules that are paused, so the page can resume them.
processors	Processors	yes

RegisterBody

Field	Type	Required	Description
cpus	integer (int64)	yes
flows	WorkerFlow[]	no
labels	object	no
meta	object	no
name	string	yes
processors	integer (int64)	no
shared_paths	array of string	no
version	string	yes

RegisterResponse

Field	Type	Required	Description
drift	array of string	yes	Modules whose code differs from the server's: the worker takes no run of them.
heartbeat_secs	integer (int64)	yes
refused	array of string	yes	Flows the worker has that the server does not: they never run there.
state	string	yes	online or draining (a worker drained before it restarted stays drained).
worker_id	integer (int64)	yes

ReleaseRequest

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

ReportRequest

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

ReportResponse

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

ResetBody

Field	Type	Required	Description
backup	boolean or null	no	Write a copy to <home>/backups/ first; defaults to true.
scope	string or null	no	history or everything; required.

ResetResult

Field	Type	Required	Description
backup_path	string or null	no	The copy written before the reset, when one was asked for.
deleted	DeletedCounts	yes
scope	string	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).

RetryBody

Field	Type	Required	Description
from	string or null	no	failure (default), start, or a dynamic key such as transform-0.

RetryResponse

Field	Type	Required	Description
from	string	yes
invalidated	array of string	yes	Dynamic keys that will execute again.
replays	integer	yes	Checkpoints the new run replays.
retry_of	integer (int64)	yes
run	Run	yes

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).
chat_id	string or null	no	Telegram chat id.
delay	number or null (double)	no	run_flow: seconds from the firing after which the run starts.
flow	string or null	no
headers	object	no
kind	string	no	run_flow, cancel_run, cancel_runs, set_state, pause_schedule, resume_schedule, webhook, email, call.
message	string or null	no
method	string or null	no
parameters	object	no
preset	string or null	no	Webhook body preset: slack, teams, discord, ntfy, telegram, or pagerduty.
routing_key	string or null	no	PagerDuty Events API routing key.
secret	string or null	no	Webhook signing secret (Standard Webhooks headers when set).
state_type	string or null	no
states	array of string	no	cancel_runs selector: non-terminal state types; empty means all of them.
subject	string or null	no
to	array of string	no
topic	string or null	no	ntfy topic.
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	Description
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	Description
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
after_consecutive	integer (int64)	no	Fire only on an event whose failures_in_a_row is at least this; 0 is off.
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
attributes	object	no	Searchable key-values the run set on itself with set_attributes.
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.
host	string or null	no	Where the run executed: server, or a worker's name.
id	integer (int64)	yes
lease	integer (int64)	no	Incremented on every hand-off to an engine; reports under an older lease are refused.
name	string	yes
parameters	object	no
parent_run_id	integer or null (int64)	no
priority	integer (int64)	no
processor	integer or null (int64)	no	The processor slot on that host, from 1.
project	string	yes
report_seq	integer (int64)	no
schedule_id	integer or null (int64)	no
scheduled_time	null or i64	no
source_hash	string or null	no	Fingerprint of the module that executed the run.
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
unique_key	string or null	no	The admission key the run was created under, when the flow is unique or the request carried an idempotency key.

RunComparison

Field	Type	Required	Description
artifacts	ArtifactDiff[]	yes
attributes	ValueDiff[]	yes
duration	DurationDiff	yes
first_divergence	string or null	no	The first task, in the left run's order, whose state differs or that exists on one side only.
left	Run	yes
new_errors	array of string	yes	Error-level log lines and the failure message present only on the right.
parameters	ValueDiff[]	yes
right	Run	yes
same_flow	boolean	yes
summary	CompareSummary	yes
tasks	TaskDiff[]	yes

RunConflict

The run that holds a unique key already, answered instead of a new one.

Field	Type	Required	Description
conflict	boolean	yes
run	Run	yes

RunGraph

Field	Type	Required	Description
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

Runtime

Field	Type	Required	Description
config_file	string or null	no	The served directory's cereyan.toml, when it has one.
platform	string or null	no
python	string	yes	Python interpreter engines run with.
python_version	string or null	no

Sample

One point of the dashboard's history.

Field	Type	Required	Description
at	integer (int64)	yes	Microseconds since the epoch.
engines_busy	integer	yes
queued	integer	yes
running	integer (int64)	yes

Schedule

One of: object, object, object, object.

ScheduleBody

Type: any.

ScheduleDecl

Type: any.

SchedulePatchBody

Field	Type	Required	Description
anchor	integer or null (int64)	no
catchup	null or CatchupPolicy	no
catchup_max	integer or null (int64)	no
catchup_window	integer or null (int64)	no
cron	string or null	no
day_or	boolean or null	no
delay	number or null (double)	no	Seconds a continuous schedule waits after each run ends.
interval	number or null (double)	no
jitter	integer or null (int64)	no
persist	boolean or null	no
rrule	string or null	no
start_deadline	integer or null (int64)	no
timezone	string or null	no

ScheduleRow

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
catchup_window	integer or null (int64)	no	Seconds: missed fires older than this are not caught up. None is off.
code_key	string or null	no
created_at	i64	yes
external_id	Id	yes
flow_id	integer (int64)	yes
id	integer (int64)	yes
jitter	integer (int64)	no	Seconds: each run becomes due up to this long after its fire time.
loop_state	string or null	no	For a continuous schedule, where its loop is: waiting, in_line, running, or paused (not stored).
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.
start_deadline	integer or null (int64)	no	Seconds: a run that has not started this long after it was due is skipped.
updated_at	i64	yes

SchedulerStatus

Field	Type	Required	Description
held	integer	yes	Scheduled runs whose time has passed and that the pause is holding.
paused	boolean	yes
reason	string or null	no
since	integer or null (int64)	no	When the pause began, microseconds; null when running.
suppress_rules	boolean	yes
until	integer or null (int64)	no	When the scheduler resumes on its own, microseconds.

ServerInfo

Field	Type	Required	Description
auth	boolean	yes	Whether a token is required.
base_path	string	yes	URL path every TCP route is served under; empty at the root.
engines	array of any	yes
exposed	boolean	yes	Bound beyond loopback with no token required.
home	string	yes
paused	null or Pause	no
pid	integer (int32)	yes
queued	integer	yes
served_dir	string or null	no
started_at	integer (int64)	yes
stream_seq	integer (int64)	yes
title	string	yes	UI title in effect: [ui] title from cereyan.toml, or cereyan.
token_file	string or null	no	The file holding the generated token when the server generated one.
url	string	yes	Dialable URL including the base path, with no trailing slash.
version	string	yes

Settings

Field	Type	Required	Description
backup_every	integer (int64)	yes	Hours between scheduled backups; 0 is off.
backup_keep	integer (int64)	yes	Scheduled copies kept.
backups	integer	yes	db-*.sqlite copies under the backup directory.
catchup_default	string	yes
cpu_cap	integer	yes	The most max_engines may be: this machine's CPU count.
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
keep_last_runs_per_flow	integer (int64)	yes	Runs per flow retention never deletes.
last_backup_at	integer or null (int64)	no	Microseconds since the epoch of the last backup, scheduled or on demand.
last_backup_path	string or null	no
max_engines	integer	yes	Engines (processors) that may run at once.
max_engines_source	string	yes	Where max_engines came from: flag, toml, settings, or default.
pid	integer (int32)	yes
port	integer (int32)	yes
resources	object	yes
retain_checkpoints_days	integer (int64)	yes	Days task checkpoints are kept after a run ends; 0 keeps them.
retain_days	integer (int64)	yes
retain_failed_runs_days	integer (int64)	yes	Days to keep Failed and Crashed runs; 0 means retain_runs_days.
retain_runs_days	integer (int64)	yes	Days to keep terminal runs; 0 keeps them.
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
title	string	yes	UI title in effect: [ui] title from cereyan.toml, or cereyan.
version	string	yes
wal_bytes	integer (int64)	yes

SettingsPatch

Field	Type	Required	Description
backup_every	integer or null (int64)	no
backup_keep	integer or null (int64)	no
crash_retries	integer or null (int64)	no
keep_last_runs_per_flow	integer or null (int64)	no
max_engines	integer or null (int64)	no	Engines (processors) that may run at once: 1 up to the CPU count, applied at once and written under [server].
resources	object or null	no
retain_checkpoints_days	integer or null (int64)	no
retain_days	integer or null (int64)	no
retain_failed_runs_days	integer or null (int64)	no
retain_runs_days	integer or null (int64)	no
title	string or null	no	UI title; an empty string removes [ui] title and restores cereyan.

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	Description
details	object	no
message	string or null	no
name	string	yes
timestamp	i64	yes
type	StateType	yes

StateBody

Field	Type	Required	Description
delete	boolean	no	Remove the entry instead of setting it.
key	string	yes
scope	string	no
value		no

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.

StateValue

Field	Type	Required	Description
found	boolean	yes
value		yes

TableCounts

Row counts for the Data tab and the reset dialog.

Field	Type	Required	Description
artifacts	integer (int64)	yes
events	integer (int64)	yes
logs	integer (int64)	yes
runs	integer (int64)	yes
task_runs	integer (int64)	yes
ui_rules	integer (int64)	yes	Rules not registered from code.
ui_schedules	integer (int64)	yes	Schedules not registered from code.
variables	integer (int64)	yes

TaskDiff

Field	Type	Required	Description
delta	integer or null (int64)	no	right − left duration, microseconds, when both ran.
key	string	yes	The dynamic key, step-0, matched across the two runs.
left	null or TaskSide	no
name	string	yes
right	null or TaskSide	no
state_changed	boolean	yes

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
input_hash	string or null	no	Hash of the bound arguments, compared on replay.
name	string	yes
parents	Id[]	no	External ids of task runs this one waited on (futures and wait_for).
pass	integer (int64)	no	Which execution of the run's body created this task run: 0 for the first, the next for a resume or an in-process flow retry. Dynamic keys restart with each pass, so the pass tells repeated calls apart.
project	string	no
result_ref	string or null	no	ResultStore key of the checkpointed result, when the task was checkpointed.
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

TaskSide

Field	Type	Required	Description
duration	integer or null (int64)	no
id	integer (int64)	yes
state	State	yes

TaskStateRow

One entry of a run's task state store.

Field	Type	Required	Description
key	string	yes
scope	string	yes	The task's dynamic key, or empty for the flow body.
updated_at	integer (int64)	yes
value		yes

Timeline

Field	Type	Required	Description
host	string	yes
next	TimelineRun[]	yes	A forecast, not an assignment: runs in line or due within the hour that this host can take, soonest first.
runs	TimelineRun[]	yes
since	integer (int64)	yes

TimelineRun

One run on a processor lane.

Field	Type	Required	Description
end	integer or null (int64)	no
flow	string	yes
processor	integer or null (int64)	no
run_id	integer (int64)	yes
start	integer or null (int64)	no
state	string or null	no	The run's state type; null for a run not started yet.

TransitionBody

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

TransitionRejected

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

UniqueSpec

@flow(unique=Unique(...)): which runs count as the same run.

Field	Type	Required	Description
debounce	number or null (double)	no	debounce: seconds a run waits after the last submission before it starts.
key	string or null	no	Template over the parameters, {day}; every parameter when absent.
max_wait	number or null (double)	no	debounce: the longest a run may be pushed back from its creation.
on_conflict	string	no	skip (answer with the existing run), replace (cancel it and create anew), debounce (move the waiting run along and take the new parameters), or throttle (keep the first run per sliding period).
period	number or null (double)	no	Fixed windows of this many seconds bucket the key.
states	array of string	no	State types in which an existing run counts; empty means every non-terminal one.

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.

ValueDiff

Field	Type	Required	Description
changed	boolean	yes
key	string	yes
left		yes
right		yes

VariableBody

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

VariablePatch

Field	Type	Required	Description
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
checkpoints	Checkpoint[]	no	Checkpoints a new attempt may replay: the run's earlier passes and, for a crash rerun, the chain of crashed runs before it.
external_id	string	yes
flow	string	yes
force	boolean	no	A forced (restated) run: the engine ignores targets, caches and checkpoints.
kind	string	no	run, hooks, or bulk_complete.
lease	integer (int64)	no	The hand-off this execution belongs to. The engine sends it back as X-Cereyan-Lease on reports, heartbeats and transitions; an older lease is refused, so a run rerun elsewhere is not also finished here.
options	object	yes
parameters	object	yes
pass	integer (int64)	no	Which execution of the run's body this is: 0 the first time, the next after a resume. The engine counts its own retries up from here and reports it with every task run it creates.
payload	object	no
project	string	yes
report_seq	integer (int64)	no	The last report sequence the store recorded for this run. A fresh engine process buffers from zero, and the store skips any event at or below the run's sequence as a redelivery, so an engine picking up a run someone else already reported on has to continue that count rather than restart it. Without this a resumed run's whole report was silently dropped.
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

Worker

Placeholders for later phases; defined now so the schema and API types are stable from the start. A registered remote worker: another machine with its own checkout that adds processors to the server's queue.

Field	Type	Required	Description
cpus	integer (int64)	yes
id	integer (int64)	yes
labels	object	no
last_seen_at	i64	yes
meta	object	no	Host metadata the worker reported: hostname, platform, memory, git state.
name	string	yes
processors	integer (int64)	yes	Engines it may run at once, at most cpus.
registered_at	i64	yes
shared_paths	array of string	no	Paths the worker shares with the server (a mounted volume, for example).
state	string	yes	online, draining, or offline.
version	string	yes	The cereyan version the worker runs.

WorkerFlow

Field	Type	Required	Description
flow	string	yes
module	string	yes
module_hash	string	yes	The worker's fingerprint of the module (_core.module_fingerprint).
project	string	yes

WorkerPatch

Field	Type	Required	Description
processors	integer (int64)	yes	Engines the worker may run at once, 1 up to its CPU count.

WorkerView

A worker with what the server knows of it right now.

Type: any.

i64

Type: integer (int64).