Workflow

Included from Basic tier

A workflow is a project-owned, versioned definition of a multi-step run: a YAML source compiled to a step list, executed as workflow runs. The workflow resource presents the definition's identity plus a denormalised view of its latest version (draft included); the stored versions themselves are workflow_version resources (opschain docs resources/workflow_version). JSON:API type: workflow.

The v2 OpenAPI document declares this resource's schema; the resource-field coverage gate holds this page to it.

Endpoints

All workflow routes live under the project's node path (the node-path router — there is no top-level /api/workflows):

Route	Serves
GET /api/projects/{project}/workflows	List, lower(name) ascending. The only supported filter is `filter[archived_eq]=true
POST /api/projects/{project}/workflows	Create (first version).
GET /api/projects/{project}/workflows/{code}	Show.
PATCH /api/projects/{project}/workflows/{code}	Update.
DELETE /api/projects/{project}/workflows/{code}	Destroy-or-archive (upstream parity): an unused workflow deletes (204), a used one archives with unused versions pruned (206). The draft-only versions variant lives on the versions path.
GET /api/projects/{project}/workflows/{code}/destroy	Preview the permanent destroy's per-type manifest (nothing deleted). Admin lane — read plus the workflow path's deletable rule action.
POST /api/projects/{project}/workflows/{code}/destroy	Permanently destroy an ARCHIVED workflow — versions and, with with_runs (attribute, meta or query), its runs, their workflow steps and their logs. Refused by name while live, while runs are active, while scheduled activities or triggers reference it, or (without with_runs) while runs exist. Events are retained and an api:workflows:destroyed event is appended.
GET …/workflows/{code}/versions, …/versions/{n}	The version history (see the workflow_version page).
GET …/workflows/{code}/runs, POST …/runs	The workflow's runs (see opschain docs resources/workflow_run).

List meta carries authorisations (update/delete on /projects/{project}/workflows) and partial_response.

Attributes

The identity attributes come from the workflow row; draft, source_yaml, steps and sample_properties are the latest version row's values (highest version number, drafts included).

Attribute	Type	Meaning / origin / null semantics
code	string	The workflow's code (its URL identity within the project).
name	string	Display name.
description	string/null	Description; null when unset.
draft	boolean	Whether the latest version is a draft (unpublished).
archived	boolean	Whether the workflow is archived (the archived_eq filter's column).
created_by	string	Username of the workflow's creator.
created_at / updated_at	string	Row timestamps (ISO8601, six fractional digits).
source_yaml	string	The latest version's YAML source, verbatim.
steps	array	The latest version's compiled step list (the workflow JSON schema's steps).
inputs	object	The latest version's typed run-input declarations, {} when none — see the workflow_version page for the declaration shape.
resolved_steps	array	Always [] on plain reads: a virtual attribute populated upstream only when a show opts into the ?resolved_steps validation run — not a stored value.
sample_properties	object	The latest version's sample properties; {} when none stored.
latest_version	integer	The highest version number, drafts included.
latest_published_version	integer/null	The highest non-draft version number; null while every version is a draft.

Relationships, links and includes

Relationship	Target type	Notes
parent	project	The owning project (related link /api/projects/{project}).
versions	workflow_version	Every stored version, includable via include=versions.

Links: self, runs, versions, latest_version (the versions/N link), and latest_published_version — present only when a published version exists.

State vocabulary

A workflow has no status machine of its own; its lifecycle booleans are draft (latest version unpublished) and archived. Run-time status lives on workflow_run and the workflow step family.

Lifecycle: archive vs destroy

• Archive (PATCH with archived: true, opschain workflows archive) is the reversible soft-hide: the workflow leaves new-run selection while every version, run and log stays browsable. Unarchive restores it. This is the default way to retire a workflow.
• Destroy (POST …/destroy, opschain admin workflows destroy) is permanent clean-up for obsolete workflows: the workflow, all versions and — with with_runs — all runs, workflow steps and logs are removed. Archive-first is enforced, the automation plane (triggers, scheduled activities) must be detached first, and the events table is never touched: the audit trail (and the api:workflows:destroyed record of the destroy itself) survives. Nested changes the runs spawned remain as ordinary change history; other workflows' steps that nested this workflow's runs keep their rows with the nested-run links cleared.

The v2 service — WorkflowService

POST /api/v2/opschain.api.v2.WorkflowService/… carries the whole authoring lane typed: ListWorkflows (code ascending, optional archived filter, summary/full views), GetWorkflow, CreateWorkflow, UpdateWorkflow (create_new_version clones the latest version as a new draft first) and DeleteWorkflow (the v1 204/206 split typed as deleted or the surviving archived workflow). Authorisation mirrors v1: reads need project read; writes update/delete on the workflow's path, 404-on-deny. See opschain docs api-v2.

Related pages

• opschain docs resources/workflow_version — the stored versions.
• opschain docs resources/workflow_run — executions.
• opschain docs cli/runs-create — creating runs from a workflow.