Automations

Package automations is workflows that run themselves, on a schedule or a webhook.

automations

POST /v1/automations/connectors/{id}/run

Run executes one connector action in-process and answers the outcome. The caller's resolved credential travels in auth, delivered to the action verbatim — the runtime resolves no credential itself. An action that ran and failed (or an action name the connector does not have) answers ok:false with the failure message, not an HTTP error; an unknown connector is 404 and a missing action 422.

Request body — application/json (required)

GET /v1/automations/connectors

Connectors returns the connector catalogue. Each entry is an external service a flow step can invoke, carrying its auth descriptor and the input properties of its actions and triggers. The catalogue is the same for every tenant, so the gate is a validated principal rather than a per-org view.

POST /v1/automations/flows/{id}/disable

Disarms a flow's trigger and marks it DISABLED. Its schedule and its event subscriptions are dropped, so a disabled flow is never a live target; runs already in flight are unaffected, and it can still be started on demand.

POST /v1/automations/flows/{id}/enable

Arms a flow's trigger and marks it ENABLED. A POLLING trigger gets a cron schedule on the durable engine; a WEBHOOK trigger gets a subscription in the routing index, so an inbound event starts it; a MANUAL trigger arms nothing and still runs on demand.

POST /v1/automations/flows/{id}/operations

Edit a flow — rename it, retarget its trigger, or add, move and delete steps

Applies ONE flow operation and answers the thing it changed. The operation is named by type, with its arguments under request: CHANGE_NAME, UPDATE_TRIGGER, ADD_ACTION, UPDATE_ACTION, MOVE_ACTION, DELETE_ACTION edit the flow's LATEST version and answer with that version, and CHANGE_STATUS instead enables or disables the flow and answers with the FLOW. Two response shapes on one address is the rule a reader would otherwise get wrong, and it is why this route is not a typed op.

Edits land on the latest version only — the published version a run executes is untouched until it is republished — and the whole resulting step tree is re-validated against the step-count and size caps after every operation, so a long sequence of ADD_ACTION calls cannot grow a flow past a bound one step at a time (422 when it would). Org-scoped and fails closed: a validated principal is required (403 without one), the flow and its version are read under the caller's OWN org so another tenant's id is a 404, and an operation whose request does not decode is a 400.

POST /v1/automations/flows/{id}/run

Starts one durable run of a flow now. It runs the flow's published version if one is pinned, else its latest, and answers the run record it created. The run is bounded by the org's per-minute run-start budget and its in-flight concurrency ceiling; over either, or with the engine not ready, no run is started and no run id is burned.

GET /v1/automations/flows/{id}/versions

Returns one flow's versions, newest first. The optional limit query bounds the page.

POST /v1/automations/flows/{id}/versions

Adds a new DRAFT version to a flow. The version is created invalid unless it carries a trigger, and it does not become the running version until it is published (PATCH the flow's publishedVersionId) or becomes the latest.

Request body — application/json (required)

GET /v1/automations/flows/{id}

Returns one automation and its latest version. That is the flow record plus the step tree the builder edits; a flow of another org answers not-found.

PATCH /v1/automations/flows/{id}

Updates one automation's metadata in place. Every field is optional; a field the request omits is left alone. Publishing a version pins which one runs, and is refused unless that version belongs to this flow.

Request body — application/json (required)

DELETE /v1/automations/flows/{id}

Deletes one automation, its versions and its run history. It answers no content, and a flow of another org answers not-found.

GET /v1/automations/flows

Returns the caller org's automations, most-recently-updated first. The optional limit query bounds the page.

POST /v1/automations/flows

Creates an automation and its initial DRAFT version in one call. The new flow is DISABLED — creating it does not arm its trigger; POST /v1/automations/flows/{id}/enable does that.

Request body — application/json (required)

POST /v1/automations/hooks/{source}/{event}

Fire an event that starts every enabled flow subscribed to it

Delivers one event to the org's automation triggers and answers {matched:n} — how many enabled flows had a webhook trigger on this (source, event) key and were started by it. A zero match is a success, not an error: nothing was subscribed.

The path is the trigger key and the JSON object body is the event payload, threaded into each started run as {{trigger.*}} with all of its keys intact — which is why this is not a typed op, since a declared input struct would silently DISCARD every payload key it had no field for. Re-delivery is a no-op: an X-Idempotency-Key header dedupes, and with none the body is content-hashed instead, so a hammer of identical posts collapses to ONE run rather than minting a fresh one per post. An in-platform producer may propagate X-Causation-Depth so a firing that a flow caused is bounded against a loop; an absent or invalid header reads as depth 0, an external origin.

Authenticated and org-scoped, unlike a provider's public webhook URL: a validated principal is required (403 without one) and the org is that principal's, never the body's, so a producer can only fire into its own tenant's flows. Both path segments are required (400) and a payload over the size limit is a 413.

GET /v1/automations/pieces

Pieces is the retired-name alias of the connector catalogue. It serves exactly what GET /v1/automations/connectors serves, under the name this surface used before "piece" (the ActivePieces term) became "connector", and stays valid for clients pinned to the old path. Prefer /connectors.

POST /v1/automations/runs/{id}/resume

Release a run waiting at an approval step, with the approval payload

Delivers the durable resume signal to a run parked on a wait_for_approval waitpoint and answers {resumed:true} once the engine has taken it.

The body is an ARBITRARY JSON value — object, array, string, number — delivered VERBATIM into the workflow as that waitpoint's output, so it is what the steps after the approval read as their input. An empty body resumes with no payload. That open shape is why this route is not a typed op: an operation's input can carry the payload or the run address, never both.

Org-scoped and fails closed: a validated principal is required (403 without one), the run is read under the caller's OWN org so another tenant's run id is a 404, a body that is not JSON is a 400, and a payload over the size limit is a 413 — it becomes durable engine state, so it is bounded here rather than after it lands. The resume is audited as automations.run.resume.

GET /v1/automations/runs/{id}

Returns one run. A run that has not reached a terminal status is refreshed from the durable engine first — scoped to the org's own namespace — so the caller sees live progress rather than the last status that happened to be persisted.

GET /v1/automations/runs

Returns the caller org's run history, newest first. The optional flowId query narrows it to one flow and limit bounds the page.

---

All Hanzo APIs · Interactive reference