Workflow Versions
A workflow is a stable parent resource with metadata and nested versions. Executable definitions and editor layouts belong to versions. There is at most one editable working version and exactly one current published version after the first publication. Earlier publications remain immutable history; existing runs keep their exact version and compiled step contracts.
Create a parent with POST /api/v2/workflows and {"name":"Customer follow-up"}. The response is
201 with its absolute Location. It contains no graph and starts disabled. Rename it or change
is_enabled with PATCH /api/v2/workflows/{workflow_id}. Metadata changes take effect immediately
and do not require publication. Enabling requires a published version.
A workflow may also carry an optional plain-text description of at most 1000 characters. Set it
on create or with the same PATCH, and clear it with {"description":null}. Values are trimmed;
a blank string returns a field-level 422 instead of clearing. The description is metadata, not
part of a version: changing it creates no working version and needs no publication. Workflow lists
and details return it, and omit it when none is set.
Discover authoring contextโ
GET /api/v2/workflows/authoring-context?object_ref=service_request&assignee_search=Owner
resolves one exact custom-object slug or UUID, its supported scalar trigger fields and the first
five matching assignees. The response includes assignee pagination metadata; use
GET /api/v2/workflows/assignees for further pages. Omit assignee_search when no assignment is
needed. Unknown object references return 404; blank/oversized searches and unsupported parameters
return field-level 422 errors.
Repeat include to request only the additional metadata needed:
capabilities: current Script/Agent model configurations and supported workflow limits.record_schema: field/choice IDs and exact projected read/write schemas. Supply repeatedreadable_attribute_ids/writable_attribute_idsfor the selected contracts (at most 512 distinct IDs each). These selections requireinclude=record_schema.tools: at most seven permitted SDK/native Agent tool contracts.
Basic context requires workflows:manage. Record contracts additionally require
objects:records:read and object READ ACL; writable selections also require
objects:records:update and object WRITE ACL. Tool contracts remain grant-filtered. This endpoint
reads no record values, executes no code steps and never grants execution permission. Missing grants
or denied object ACL return 403. Responses use Cache-Control: no-store.
Script and Agent input/output contracts are part of their inline configuration in the workflow version. If the object reference is unknown, use
the paginated /api/v2/workflows/objects search first. Ask Rob and MCP expose the same read as
workflows_authoring_context_get. Objects in that search, in the authoring context and in the
record schema carry the definition's optional icon and color, so an editor can show them without
reading the definitions separately.
Author a working versionโ
POST /api/v2/workflows/{workflow_id}/versions with {} creates an empty working version. To copy
an existing version of the same workflow, send {"source_version_id":"VERSION_UUID"} instead.
Both return 201 with the version's absolute Location. An existing working version returns 409;
a copy never overwrites it. The parent exposes its identity as draft_version_id.
Save content with PATCH /api/v2/workflows/{workflow_id}/versions/{version_id}:
{
"definition": {"actions": [], "edges": []},
"layout": {"nodes": []},
"lock_version": 0
}
Use application/merge-patch+json; application/json is also accepted. Omitted fields remain
unchanged, explicit null cannot clear required structures, and arrays replace as a whole.
Incomplete graphs can be saved. Their validation_issues identify what must be resolved before
publication, using pointers under #/definition or #/layout. The version's optional
lock_version checks its content independently of the parent's metadata lock.
Action-specific fieldsโ
Each action has a required id and type. Its type selects a closed schema with only the
fields that action supports. For example, create_task accepts title, assignment and record
link fields; script accepts inline configuration, an optional name and input bindings; end and join accept
no configuration. OpenAPI describes all 21 variants as a discriminated oneOf union.
Every action and trigger also accepts an optional plain-text description of at most 500
characters, a note for people reading the workflow. Values are trimmed; a blank string or a longer
value returns a field-level 422, for example at #/definition/actions/0/description. Execution
ignores descriptions. They are saved with the working version, published with it and returned
wherever the definition is, including the version pinned by a run.
Fields belonging to another action are rejected with a field-level 422, including fields
sent as null. A missing or unknown type also returns 422. Relevant fields may remain absent
in an incomplete draft: saving a Script without configuration succeeds with validation issues, while
publication requires complete source and contracts. Record actions accept their corresponding read,
update or upsert configuration and operation.
To change an action's type, replace it with the complete new variant in the actions array.
The array replaces as a whole; omitted fields from the previous action are not retained.
Publish and retain historyโ
POST /api/v2/workflows/{workflow_id}/versions/{version_id}/publish with {} or
{"lock_version":1} returns 200 and publishes that version in place. Its UUID and number stay
the same. Publication validates the entire graph and freezes exact dependencies atomically.
First publication enables the workflow; later publications preserve its live or paused state.
The parent points to this version through published_version_id; draft_version_id is absent
until another working version is created.
Versions expose state (draft or published) and is_current. Only the version named by the
parent's publication pointer has is_current: true. Publishing a newer version leaves earlier
versions readable with state: published and is_current: false. Published content cannot be
edited, republished or deleted (409). Runs already admitted retain their original snapshots.
Read a version with GET /api/v2/workflows/{workflow_id}/versions/{version_id}. List metadata with
GET /api/v2/workflows/{workflow_id}/versions?page=0&size=20; the standard items and page
envelope includes the working version and publication history, ordered by descending version
number. All nested operations verify that the version belongs to the supplied workflow and
workspace. Every authoring operation requires workflows:manage; publication also checks grants
required by selected executable dependencies.
Discard an unpublished, unreferenced working version with
DELETE /api/v2/workflows/{workflow_id}/versions/{version_id} (204, no request body). Numbers
are allocated when a version is created and are never reused, so deletion can leave gaps.
Continue only when a condition matchesโ
Use an if_else action with an End on its otherwise path when the rest of the run should execute
only for matching input:
{
"id": "00000000-0000-4000-8000-000000000002",
"type": "if_else",
"condition": {
"source_node_id": "00000000-0000-4000-8000-000000000001",
"field_path": "record.display_name",
"operator": "contains",
"value": "Ready"
}
}
The source identifies the trigger or an output from a step preceding the consumer on at least one path.
If that step was skipped on the taken path, the comparison receives null. Preview reports execution
outputs as unknown instead of guessing their values.
Use one condition or a flat condition_group with mode: "all" or "any" and 1โ10 comparisons.
Existing typed comparison rules apply; missing/null matches only is_empty.
Connect branch: "matched" to the next action and branch: "otherwise" to an end action.
A nonmatch then ends the run successfully, retaining earlier effects. The If/Else step succeeds
in either case; run history records condition_matched and skips the unselected path.
Incomplete conditions can be saved, but publication requires a valid comparison and both paths.
Only if_else accepts condition or condition_group. Ordinary actions reject either field,
including explicit null, with a field-level 422. To skip one action and continue, put it on an
If/Else path and reconnect both paths through a Join. Preview reports the comparison and marks
unselected nodes skipped; it creates no effects.
Inspect admitted runsโ
Use GET /api/v2/workflows/{workflow_id}/runs?version_id=VERSION_UUID for one publication's runs.
Detail is nested under the workflow: GET /api/v2/workflows/{workflow_id}/runs/{run_id}.
include=version returns the exact pinned publication, including retained runs after the parent
is deleted. See Workflow Runs for results, steps and cancellation.