Workflow automation

Sellable product

This capability is granted by an API key scoped to the `` product (product face). See the product reference below.

DAG workflow automation as a shared capability. CRUD workflow DEFINITIONS (a DAG of typed steps: transform / http-call / tool / condition / delay / sub-workflow); RUN a workflow (async in-process DAG execution — the ready frontier runs in parallel, with per-step retries + timeout) and poll its per-step status; VALIDATE a DAG (cycles + dangling deps). Deliberate scope: in-process asyncio execution with durable run-state — NOT distributed durable-execution (Temporal's remit). Transform steps run a bounded, safe op vocabulary — never eval/exec of caller data.

• Group: Comms & workflow
• Contract: contracts/workflow-automation/v1/openapi.yaml
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/workflows

Endpoints

Method	Path	Summary
POST	/v1/workflows	Create (or upsert) a workflow definition
GET	/v1/workflows	List an org's workflow definitions
GET	/v1/workflows/{workflow_id}	Fetch a stored workflow definition (org-scoped)
PATCH	/v1/workflows/{workflow_id}	Update a workflow definition (bumps version)
POST	/v1/workflows/{workflow_id}/validate	Validate a DAG (cycles + dangling deps)
POST	/v1/workflows/{workflow_id}/run	Run a workflow (async DAG execution)
GET	/v1/runs/{run_id}	Fetch a run + its per-step results (org-scoped)
GET	/health	Liveness + store/config posture
GET	/metrics	Prometheus exposition (fleet observability SDK — fail-open)

Schemas

Step

A single DAG step. type selects the behaviour; depends_on lists the upstream steps this step waits on; condition (optional) names a condition step that GATES this one (skipped if it is falsy); params is type-specific; retries/retry_backoff_seconds/timeout_seconds govern per-step resilience.

Field	Type	Description
name	string	unique step name within the workflow
type	string
depends_on	array	upstream step names this step waits on (must all succeed)
condition	string	name of a condition step that gates this step (skip if falsy)
params	object	type-specific parameters (op/url/action/seconds/definition/…)
retries	integer	max retry attempts on failure (exponential backoff)
retry_backoff_seconds	number	base backoff between retries (seconds)
timeout_seconds	number	per-step timeout (seconds); defaults to the service default

Definition

a workflow DAG definition (a set of typed steps)

Field	Type	Description
name	string	optional human name for the workflow
steps	array	the DAG's steps (must form an acyclic graph with no dangling dependencies)

WorkflowRequest

Field	Type	Description
organization_id	string	product-tier end-customer tenant (I6)
workflow_id	string	optional explicit id (generated when omitted)
name	string
definition	object

WorkflowPatch

Field	Type	Description
organization_id	string	product-tier end-customer tenant (I6)
name	string
definition	object

Workflow

Field	Type	Description
workflow_id	string
name	object
definition	object
version	integer
created_at	number
updated_at	number

WorkflowSummary

Field	Type	Description
workflow_id	string
name	object
version	integer
created_at	number
updated_at	number

RunRequest

Field	Type	Description
organization_id	string	product-tier end-customer tenant (I6)
inputs	object	run inputs threaded to every step's context

ValidateRequest

Field	Type	Description
organization_id	string	product-tier end-customer tenant (I6); needed only when validating a stored workflow
definition	object

---

Generated by scripts/gen-capability-docs.py from contracts/workflow-automation/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.