Update a workflow’s draft

Body

nameOptional · string

Trimmed. An empty string is ignored (the existing name is kept), not applied; spaces alone are a 400.

descriptionOptional · string

Send "" to clear it; omit to keep it.

definitionOptional · object

The workflow definition, and the single most important shape in this API.

A workflow definition: its fields are in Workflow definition.

triggerTypeOptional · string

Overridden whenever the definition carries a trigger — it is re-derived from definition.trigger after the merge, so the value sent has no lasting effect.

One of manual, cron, webhook, callable, event, error, run_finished, poll.

expectedRevOptional · integer

The definitionRev you read. When it no longer matches the stored row the save is refused with 409 instead of overwriting whoever saved in between. Omit it, or send null, 0 or a negative number, for an unconditional last-write-wins save.

tabOptional · string

The builder’s tab id (the opaque tab its presence beat sends to POST /api/workflows/{id}/presence). With it, the save is refused with 409 EDITING_ELSEWHERE while the workflow’s advisory editing lock is held by another tab, the same person’s or someone else’s, so a tab that has not yet heard it lost the lock cannot write under the one that holds it. A free lock, or one this tab holds, lets the save through, and so does presence that cannot be read. Omit it (API clients, MCP and the partner API do): the editing lock is then not consulted, as before.

testPayloadsOptional · object

The canvas test-fixture library, stored outside the definition so publishing or restoring a version never resets it. Absent = keep.

pinnedDataOptional · object

The pin library: {"pins": {"<stepName>": {"data": {…}}}}. A pinned step emits its fixture INSTEAD of executing, and only on environment=test runs — production always executes for real. One pin is capped at 2 MB. Absent = keep. The server re-stamps the library on every save of the definition (this update, version restore, the assistant): a pin whose step config has changed is flagged staleAt, not deleted, and is never replayed; a pin whose step is removed, or now runs another app, is deleted with it, so a step that later takes that name starts with no pin.

cronExpressionOptional · string or null

Stored and answered as sent, and read by nothing: the schedule runs from the trigger’s own config, and no write derives this. Leave it out.

Response · 200 OK

dataobject

A workflow row. definition is always the DRAFT — the tree the editor holds. What production actually runs is the snapshot named by latestVersionId, which only changes when you publish.

idUUID

namestring

descriptionstring

definitionobject

The workflow definition, and the single most important shape in this API.

A workflow definition: its fields are in Workflow definition.

statusstring

draft = never published. active = live, triggers registered and the webhook URL reachable. paused = was live, now switched off. Server-owned: it moves only through publish/unpublish, never through a create or update body.

One of draft, active, paused.

triggerTypestring

Mirrors definition.trigger.type for dispatch. Derived server-side from the definition by every update and publish, so treat it as read-only in practice. A create that sends its own value keeps it until then, unchecked.

One of manual, cron, webhook, callable, event, error, run_finished, poll.

cronExpressionstring or null

Nothing derives or reads this: the schedule runs from the trigger’s own config, and nextRunAt projects from it too. Null unless a caller wrote one with PUT /api/workflows/{id}.

webhookTokenstring or null

The secret segment of the public webhook URL. Made by the first update of a webhook workflow, or at publish; absent until then (so absent in the answers of create, duplicate and import). Returned ONLY to a caller holding workflow:run: by GET /api/workflows/{id} and in the answers of update, publish, unpublish and restore (rotate answers it to its caller). It is never present on a list row, an export or a version snapshot. It is a bearer capability against an unauthenticated endpoint — possessing it is the ability to fire this workflow in production. Rotate it with POST /api/workflows/{id}/webhook/rotate.

latestVersionIdUUID or null

The published snapshot production executes. Absent means nothing has ever been published.

definitionRevinteger

Optimistic-lock revision, bumped by every definition save. Populated by GET /api/workflows/{id}, by the update response and by the answers of create, duplicate and import; absent (0) on list rows. Send it back as expectedRev on an update to refuse a clobbering write.

hasUnpublishedChangesboolean

The draft has moved ahead of the published version. Computed on the single-workflow read and on every list row; always false for a workflow never published.

folderIdUUID or null

Absent/null = uncategorized. Changed only through PUT /api/workflows/{id}/folder.

tagsarray of strings

Changed only through PUT /api/workflows/{id}/tags or the bulk addTags operation — never through the workflow update body.

testPayloadsobject or null

The saved test-fixture library, stored outside the definition so publish and version restore never reset it.

pinnedDataobject or null

The pin library ({"pins": {"<stepName>": {"data": …, "pinnedAt": …, "configHash": …, "staleAt": …, "pieceId": …}}}). A pinned step emits its fixture instead of executing, and only on test runs. configHash, staleAt and pieceId are the server’s: a step whose config changed keeps its pin marked stale, and a stale pin is not replayed (the step runs); a step whose app was replaced loses it.

workspaceIdUUID

Stamped from the credential’s scope; never accepted from a request body.

orgIdUUID

createdByUUID or null

createdByNamestring

List rows only: the creator’s name, else their email address. Absent when the creator is unknown or not a member of the organization (staff who built it on a support visit, someone since removed), and on every row for an embedded person whose installation switched presence off (an embedded person is never told an address).

createdAttime

updatedAttime

When the workflow itself was last edited. Publishing, pausing, tagging and filing it are not edits and leave it alone.

failingboolean

List rows only: the workflow is live (status: active) and its latest FINISHED production run (one that worked or failed) failed. A later run that is waiting, running, held or was cancelled changes nothing, and test runs never count. A paused or draft workflow is never failing.

failingSincetime

Only on a failing row: when the first production run failed after the last one that worked (runs cancelled, held or running in between neither break nor begin the streak). Left out for a caller without run:read.

failingRunobject

Only on a failing row: the run that decided it, its latest finished production run, with why it failed. It is lastRun unless a later run is waiting, running, held or was cancelled. Without run:read it carries status and startedAt alone.

idUUID

statusstring

One of failed.

startedAttime

finishedAttime or null

errorobject

Why it failed, as lastRun.error says it.

stepstring or null

stepKeystring or null

messagestring

summaryobject

List rows only: what a list draws instead of the definition.

triggerobject or null

The chosen trigger; null while none is chosen.

pieceIdstring

actionIdstring

displayNamestring

piecesarray of objects

The apps the workflow uses, each once, in walk order (the trigger first), with their display names.

idstring

namestring

stepCountinteger

Steps after the trigger, across branch arms, loop bodies and error paths.

needsSetupinteger

Steps (and a chosen trigger) the editor marks to configure: valid: false, or no app and action chosen.

runs7darray of integers

List rows without view=summary only: counted runs per UTC day over the last seven days, oldest first (production runs that are not a sub-flow’s, cancelled runs left out).

nextRunAttime

Next fire time of an active schedule workflow, projected from its cron in the trigger’s own timezone. Populated by the list endpoint.

lastRunobject or null

The most recent PRODUCTION run’s outcome (test runs never count). Populated on list rows only. Without run:read it carries status and startedAt alone.

idUUID

finishedAttime or null

errorobject

Only when status is failed: why.

stepstring or null

The display name of the step it failed at; null when the reason names no step.

stepKeystring or null

messagestring

The reason’s first clause, at most 160 characters.

statusstring

One of pending, running, completed, failed, cancelled, paused.

startedAttime