Workflows
Read workflow configs, diff and apply new versions with optimistic concurrency, restore old versions, start test runs, and pause or resume workflows.
On this page
A workflow is the set of steps every run in a factory goes through, plus its triggers, limits, rules and run inputs. Workflows are versioned: applying a change creates a new version, new runs use it, and runs already in progress keep the version they started on.
Through the API you can treat workflows as code: pull a config, change it, check the diff and its problems, then apply it as a new version. The duun workflows commands are built on these endpoints.
The workflow object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed wf_. |
object | string | Always "workflow". |
factory_id | string | null | The factory it belongs to. null for built-in workflows. |
name | string | Display name, e.g. Base Loop. |
description | string | Shown wherever the workflow is listed. |
built_in | boolean | true for Base Loop, Small change and Large change. Built-ins are read-only; copy one into a factory to edit it. |
status | enum | draft (never applied with triggers on), on, or paused (won’t start on its own). |
live_revision | integer | The version new runs use. |
config | object | The live version’s workflow config. |
created_at | string | When the workflow was created. |
updated_at | string | When a version was last applied or its status changed. |
{
"id": "wf_base9c1d",
"object": "workflow",
"factory_id": "fac_platform",
"name": "Base Loop",
"description": "Plan, approve, build, test, review and merge.",
"built_in": false,
"status": "on",
"live_revision": 5,
"config": {
"triggers": [
{ "id": "t1", "kind": "issue", "enabled": true, "provider": "linear", "team": "Platform", "label": "ready" },
{ "id": "t2", "kind": "manual", "enabled": true }
],
"inputs": [],
"limits": { "budget_usd": 8, "pause_at_pct": 80, "timeout_min": 120, "max_concurrent_runs": 4 },
"rules": [
{ "id": "r1", "text": "Never touch infra/prod without the operator agent.", "scope": "all", "enforce": "block" }
],
"steps": [
{
"id": "plan",
"kind": "agent",
"name": "Plan with repo context",
"enabled": true,
"owner": { "kind": "agent", "agent": "builder", "model": "opus-5.5" },
"instructions": "Read {{trigger.issue.url}} and the code it touches. Write a short plan: problem, approach, out of scope.",
"done_criteria": "A plan with numbered steps and the files each one touches.",
"skills": ["payments", "ledger"],
"knowledge": ["ledger-schema"],
"depends_on": null,
"gate": { "type": "user_approval" },
"outputs": [{ "key": "summary", "type": "markdown", "description": "The plan" }],
"limits": null
},
{
"id": "implement",
"kind": "agent",
"name": "Implement in isolated worktree",
"enabled": true,
"owner": { "kind": "agent", "agent": "builder", "model": "opus-5.5" },
"instructions": "Implement {{steps.plan.output.summary}}. Keep commits small.",
"done_criteria": "Every plan step is done and the tests pass locally.",
"skills": ["payments"],
"knowledge": [],
"depends_on": null,
"gate": null,
"outputs": [{ "key": "summary", "type": "markdown", "description": "What it did" }],
"limits": { "budget_usd": 5, "timeout_min": 60, "retries": 1 }
},
{
"id": "ci",
"kind": "check",
"name": "CI and contract tests",
"enabled": true,
"owner": { "kind": "orchestrator" },
"instructions": "Run the checks and report each failure with its log.",
"done_criteria": "Every check is green.",
"skills": [],
"knowledge": [],
"depends_on": null,
"gate": {
"type": "ci_green",
"command": "pnpm ci",
"on_fail": { "return_to": "implement", "policy": "retry_with_feedback", "max_attempts": 3 }
},
"outputs": [],
"limits": null
},
{
"id": "ship",
"kind": "deliver",
"name": "Open PR & merge on green",
"enabled": true,
"owner": { "kind": "orchestrator" },
"instructions": "Open a PR from the run branch; merge when checks and reviews pass.",
"done_criteria": "",
"skills": [],
"knowledge": [],
"depends_on": null,
"gate": null,
"outputs": [],
"limits": null,
"mode": "merge_on_green"
}
]
},
"created_at": "2026-09-02T14:11:40Z",
"updated_at": "2026-11-14T16:25:03Z"
}The workflow config
The config is the same structure you edit in the app’s Workflows tab and in a duun workflows pull YAML file. The editor’s concepts are described in Step kinds, Gates, Decide and outcomes, References, Triggers and Limits and budgets.
| Key | Type | Description |
|---|---|---|
triggers | object[] | What starts a run. Each has id, kind (schedule, recurring, mention, cron, manual, issue, alert, webhook or event), enabled and kind-specific fields. |
steps | object[] | Up to 24 steps. List order is the default sequence. |
rules | object[] | Natural-language rules: id, text, scope ("all" or a list of step ids) and enforce (instruct, check or block). |
inputs | object[] | Run inputs, available as {{input.<key>}}. Each is a field definition. |
limits | object | budget_usd per run (1–200), pause_at_pct (50–100), timeout_min (5–600) and max_concurrent_runs (1–16). |
Step keys
Every step has these keys:
| Key | Type | Description |
|---|---|---|
id | string | Slug, unique in the workflow, max 56 characters. Used in {{steps.<id>.…}} references. |
kind | enum | agent, check, human, decide, read, transform, foreach, notify, webhook or deliver. |
name | string | Shown in the editor and on runs. |
enabled | boolean | Turned-off steps are skipped; steps after them run after whatever they ran after. |
owner | object | Who does the work: kind (orchestrator, agent, reviewer or human) plus agent and model for agents, agent for reviewers, or who (issue-owner, codeowners, project-lead, anyone) for humans. |
instructions | string | What the owner does. Supports references. |
done_criteria | string | How the run knows the step is complete. |
skills | string[] | Skill names the owner loads. |
knowledge | string[] | Knowledge items added to the step’s context. |
depends_on | string[] | null | Steps that must finish first. null means the step before it in the list. |
gate | object | null | type (none, judgment, user_approval, ci_green, review_check, qa_check or fact), criteria for judgment and fact checks, command for CI and QA checks, and on_fail with return_to (an earlier step), policy (retry_with_feedback, redispatch or escalate) and max_attempts. |
outputs | object[] | Fields later steps can reference: key, type (text, number, boolean, enum, list, url or markdown), description, values (for enum) and required. |
limits | object | null | Per-step budget_usd, timeout_min and retries. |
Kind-specific keys:
| Kind | Keys |
|---|---|
agent | permission (all, writes or auto, optional) |
human | sla_hours, escalate_to (optional) |
decide | control: mode (first_match or all_matches), cases (each id, label, when, activate) and otherwise.activate |
read | source: type (doc, url, repo_file or issue) plus doc_id, url or path |
transform | input: a reference to shape into the step’s outputs |
foreach | items (a reference to a list output), body (step ids), concurrency (1–8), max_items |
notify | channel: type (slack, person or inbox) plus channel or user_id; message |
webhook | url (https), method (POST or PUT), headers ({ key, value }), payload (JSON text with references), secret_ref |
deliver | mode: merge_on_green, open_pr or draft_pr |
A decide case’s when object has a name and its parameters: { "name": "judged", "question": "…" }, { "name": "output_equals", "ref": "…", "value": "…" }, { "name": "expression", "expr": "{{steps.size.output.prs}} <= 1" }, { "name": "step_output_valid", "step": "…" }, or one of all_checks_succeeded, pr_review_passed, pr_merged and child_run_rollup with no parameters.
The workflow version object
| Field | Type | Description |
|---|---|---|
object | string | Always "workflow_version". |
revision | integer | Version number, starting at 1. |
config | object | The config at that version. |
author | object | kind (user or agent), name, and applied_by when an agent’s proposal was applied by a person. |
label | string | null | A note describing the change. |
restored_from | integer | null | Set when this version re-applies an earlier one. |
created_at | string | When it was applied. |
{
"object": "workflow_version",
"revision": 5,
"config": { "triggers": [], "steps": [], "rules": [], "inputs": [], "limits": { "budget_usd": 8, "pause_at_pct": 80, "timeout_min": 120, "max_concurrent_runs": 4 } },
"author": { "kind": "agent", "name": "architect", "applied_by": "Dana Kim" },
"label": "Skip review for docs-only PRs",
"restored_from": null,
"created_at": "2026-11-14T16:25:03Z"
}Endpoints
List workflows
https://api.duun.ai/v1/workflows Returns workflows the key can see, including the built-ins. Needs workflows:read.
Query parameters
-
factory_idstring Optional -
Only workflows in this factory.
-
built_inboolean Optional -
truefor only the built-ins,falseto leave them out. -
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl "https://api.duun.ai/v1/workflows?factory_id=fac_platform" \
-H "Authorization: Bearer $DUUN_API_KEY"import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
for await (const wf of duun.workflows.list({ factory_id: "fac_platform" })) {
console.log(wf.id, wf.name, `v${wf.live_revision}`, wf.status);
}from duun import Duun
client = Duun()
for wf in client.workflows.list(factory_id="fac_platform"):
print(wf.id, wf.name, f"v{wf.live_revision}", wf.status){
"object": "list",
"data": [
{ "id": "wf_base9c1d", "object": "workflow", "factory_id": "fac_platform", "name": "Base Loop", "built_in": false, "status": "on", "live_revision": 5 },
{ "id": "wf_small4e7a", "object": "workflow", "factory_id": "fac_platform", "name": "Small change", "built_in": false, "status": "on", "live_revision": 2 },
{ "id": "wf_hotfix21b", "object": "workflow", "factory_id": "fac_platform", "name": "Hotfix", "built_in": false, "status": "paused", "live_revision": 3 }
],
"has_more": false,
"next_cursor": null
}List items are full workflow objects, including config; the example is trimmed.
Retrieve a workflow
https://api.duun.ai/v1/workflows/{workflow_id} Returns one workflow with its live config. Needs workflows:read.
Path parameters
-
workflow_idstring Required -
The workflow's id, e.g.
wf_base9c1d.
curl https://api.duun.ai/v1/workflows/wf_base9c1d \
-H "Authorization: Bearer $DUUN_API_KEY"const wf = await duun.workflows.retrieve("wf_base9c1d");
console.log(wf.live_revision, wf.config.steps.map((s) => s.id));wf = client.workflows.retrieve("wf_base9c1d")
print(wf.live_revision, [s.id for s in wf.config.steps])The response is a workflow object.
Create a workflow
https://api.duun.ai/v1/workflows Adds a workflow to a factory, either as a copy of another workflow (including the built-ins) or from a config. The new workflow is a draft at version 1, so it doesn’t start on its own until you resume it. Needs workflows:write.
Body parameters
-
factory_idstring Required -
The factory to add it to.
-
namestring Required -
Display name.
-
descriptionstring Optional -
Shown wherever the workflow is listed.
-
from_workflow_idstring Optional -
Copy this workflow's live config. Use the built-ins to start from Base Loop, Small change or Large change.
-
configobject Optional -
A full workflow config. Provide either
from_workflow_idorconfig.
curl https://api.duun.ai/v1/workflows \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"factory_id": "fac_platform",
"name": "Large change",
"from_workflow_id": "wf_builtin_large"
}'const wf = await duun.workflows.create({
factory_id: "fac_platform",
name: "Large change",
from_workflow_id: "wf_builtin_large",
});wf = client.workflows.create(
factory_id="fac_platform",
name="Large change",
from_workflow_id="wf_builtin_large",
){
"id": "wf_large7b31",
"object": "workflow",
"factory_id": "fac_platform",
"name": "Large change",
"description": "Spec first, then build in slices with a review per slice.",
"built_in": false,
"status": "draft",
"live_revision": 1,
"config": { "triggers": [], "steps": [], "rules": [], "inputs": [], "limits": { "budget_usd": 20, "pause_at_pct": 80, "timeout_min": 240, "max_concurrent_runs": 2 } },
"created_at": "2026-11-15T10:30:00Z",
"updated_at": "2026-11-15T10:30:00Z"
}The example’s config is trimmed. A config with problems returns 422 validation_error; see Apply a new version.
Diff a config
https://api.duun.ai/v1/workflows/{workflow_id}/diff Compares a config with the live version without applying anything, and validates it. Use it in CI to review a change before you apply it. Needs workflows:read.
Path parameters
-
workflow_idstring Required -
The workflow to compare against.
Body parameters
-
configobject Required -
The proposed workflow config.
-
base_revisioninteger Optional -
Compare with this version instead of the live one.
curl https://api.duun.ai/v1/workflows/wf_base9c1d/diff \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-d @proposed-config.jsonconst { changes, problems } = await duun.workflows.diff("wf_base9c1d", { config });
if (problems.some((p) => p.severity === "error")) process.exit(3);result = client.workflows.diff("wf_base9c1d", config=config)
if any(p.severity == "error" for p in result.problems):
raise SystemExit(3){
"object": "workflow_diff",
"base_revision": 5,
"changes": {
"count": 2,
"steps": [
{
"step_id": "security-review",
"change": "added",
"fields": ["name", "owner", "instructions", "runs_after"]
},
{
"step_id": "ci",
"change": "edited",
"fields": ["gate"],
"before": { "gate": { "type": "ci_green", "command": "pnpm ci" } },
"after": { "gate": { "type": "ci_green", "command": "pnpm ci && pnpm e2e" } }
}
],
"triggers": [],
"rules": [],
"limits": [],
"reordered": false
},
"problems": [
{
"step_id": "security-review",
"field": "instructions",
"message": "“Security review” needs instructions before it can be applied.",
"severity": "error"
}
]
}A diff with problems still returns 200; the problems are information, not an error.
Apply a new version
https://api.duun.ai/v1/workflows/{workflow_id}/versions Applies a config as the workflow’s newest version. New runs use it at once; runs in progress keep the version they started on. Needs workflows:write.
Applying uses optimistic concurrency. Send the revision your change is based on as expected_revision. If someone applied another version in the meantime, the request fails with 409 conflict instead of overwriting their change.
Path parameters
-
workflow_idstring Required -
The workflow's id. Built-in workflows can't take new versions.
Body parameters
-
configobject Required -
The full workflow config for the new version.
-
expected_revisioninteger Required -
The
live_revisionyour config was based on. -
labelstring Optional -
A note shown in the version history, e.g. "Add security review". Max 120 characters.
curl https://api.duun.ai/v1/workflows/wf_base9c1d/versions \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wf_base9c1d-from-5-$(git rev-parse --short HEAD)" \
-d '{
"expected_revision": 5,
"label": "Run e2e in CI",
"config": { "triggers": [], "steps": [], "rules": [], "inputs": [], "limits": {} }
}'import Duun from "@duun/sdk";
try {
const version = await duun.workflows.versions.create("wf_base9c1d", {
config,
expected_revision: 5,
label: "Run e2e in CI",
});
console.log(`Applied v${version.revision}`);
} catch (err) {
if (err instanceof Duun.ConflictError) {
console.error("Someone applied a newer version. Pull it, rebase your change and try again.");
} else if (err instanceof Duun.ValidationError) {
for (const p of err.problems) console.error(`${p.step_id ?? "workflow"}: ${p.message}`);
} else {
throw err;
}
}import duun
try:
version = client.workflows.versions.create(
"wf_base9c1d",
config=config,
expected_revision=5,
label="Run e2e in CI",
)
print(f"Applied v{version.revision}")
except duun.ConflictError:
print("Someone applied a newer version. Pull it, rebase your change and try again.")
except duun.ValidationError as err:
for p in err.problems:
print(f"{p.step_id or 'workflow'}: {p.message}"){
"object": "workflow_version",
"revision": 6,
"config": { "triggers": [], "steps": [], "rules": [], "inputs": [], "limits": { "budget_usd": 8, "pause_at_pct": 80, "timeout_min": 120, "max_concurrent_runs": 4 } },
"author": { "kind": "user", "name": "API key: ci-github-actions", "applied_by": null },
"label": "Run e2e in CI",
"restored_from": null,
"created_at": "2026-11-15T10:41:18Z"
}Errors worth handling:
{
"error": {
"type": "conflict",
"code": "revision_mismatch",
"message": "This workflow is at v7, not v5. Someone applied a version while you were editing.",
"param": "expected_revision",
"request_id": "req_Hq72LsXv0Pn3"
}
}{
"error": {
"type": "validation_error",
"code": "workflow_invalid",
"message": "The workflow has 1 problem to fix.",
"param": "config",
"request_id": "req_Zt9Wm2Kd4Ra8",
"problems": [
{
"step_id": "notify",
"field": "message",
"message": "“{{steps.spec.output.doc}}” isn't available here: Spec doesn't run before Notify.",
"severity": "error"
}
]
}
}403 permission_deniedwith codebuilt_in_workflowfor Base Loop, Small change and Large change. Create a copy first.
List versions
https://api.duun.ai/v1/workflows/{workflow_id}/versions Returns the version history, newest first. Needs workflows:read.
Path parameters
-
workflow_idstring Required -
The workflow's id.
Query parameters
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl https://api.duun.ai/v1/workflows/wf_base9c1d/versions \
-H "Authorization: Bearer $DUUN_API_KEY"for await (const v of duun.workflows.versions.list("wf_base9c1d")) {
console.log(`v${v.revision}`, v.author.name, v.label ?? "");
}for v in client.workflows.versions.list("wf_base9c1d"):
print(f"v{v.revision}", v.author.name, v.label or ""){
"object": "list",
"data": [
{ "object": "workflow_version", "revision": 6, "author": { "kind": "user", "name": "API key: ci-github-actions", "applied_by": null }, "label": "Run e2e in CI", "restored_from": null, "created_at": "2026-11-15T10:41:18Z" },
{ "object": "workflow_version", "revision": 5, "author": { "kind": "agent", "name": "architect", "applied_by": "Dana Kim" }, "label": "Skip review for docs-only PRs", "restored_from": null, "created_at": "2026-11-14T16:25:03Z" }
],
"has_more": true,
"next_cursor": "cur_djQtd2ZfYmFzZTljMWQ"
}List items include config; the example leaves it out.
Retrieve a version
https://api.duun.ai/v1/workflows/{workflow_id}/versions/{revision} Returns one version with its full config. Use it to see exactly what a run followed: a run’s workflow_revision names its version. Needs workflows:read.
Path parameters
-
workflow_idstring Required -
The workflow's id.
-
revisioninteger Required -
The version number.
curl https://api.duun.ai/v1/workflows/wf_base9c1d/versions/3 \
-H "Authorization: Bearer $DUUN_API_KEY"const v3 = await duun.workflows.versions.retrieve("wf_base9c1d", 3);v3 = client.workflows.versions.retrieve("wf_base9c1d", 3)The response is a workflow version object.
Restore a version
https://api.duun.ai/v1/workflows/{workflow_id}/restore Re-applies an earlier version as the newest one. Earlier versions stay in the history. The new version has restored_from set. Needs workflows:write.
Path parameters
-
workflow_idstring Required -
The workflow's id.
Body parameters
-
revisioninteger Required -
The version to restore.
-
expected_revisioninteger Required -
The current
live_revision. Prevents restoring over a version you haven't seen.
curl https://api.duun.ai/v1/workflows/wf_base9c1d/restore \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "revision": 3, "expected_revision": 6 }'const version = await duun.workflows.restore("wf_base9c1d", { revision: 3, expected_revision: 6 });
console.log(version.revision, version.restored_from); // 7 3version = client.workflows.restore("wf_base9c1d", revision=3, expected_revision=6)
print(version.revision, version.restored_from) # 7 3{
"object": "workflow_version",
"revision": 7,
"config": { "triggers": [], "steps": [], "rules": [], "inputs": [], "limits": { "budget_usd": 8, "pause_at_pct": 80, "timeout_min": 120, "max_concurrent_runs": 4 } },
"author": { "kind": "user", "name": "API key: ci-github-actions", "applied_by": null },
"label": "Restored v3",
"restored_from": 3,
"created_at": "2026-11-15T11:05:40Z"
}Returns 409 conflict with code revision_mismatch if expected_revision isn’t the live revision, and 404 not_found if revision doesn’t exist.
Start a test run
https://api.duun.ai/v1/workflows/{workflow_id}/test Runs the workflow’s live version as a test, like Test in the editor. A dry run mocks the Notify, Send to URL and Deliver steps: nothing leaves Duun and it costs $0. A live test triggers real events and uses credits. The response is a run with test: true; follow it like any other run. Needs workflows:write and runs:read to follow it.
Path parameters
-
workflow_idstring Required -
The workflow's id.
Body parameters
-
modeenum Optional -
drymocks outward steps and costs $0.livetriggers real events and uses credits. -
inputobject Optional -
The input sample:
{ "issue_url": "…" }for an issue,{ "body": { … } }to replay a webhook payload, or omit it for a manual run with no input. -
force_outcomesobject Optional -
Force a decision's outcome, keyed by decide step id, with the outcome label as the value, e.g.
{ "size": "Small" }. Unlisted decisions run normally.
curl https://api.duun.ai/v1/workflows/wf_base9c1d/test \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"mode": "dry",
"input": { "issue_url": "https://linear.app/acme/issue/PLT-466" },
"force_outcomes": { "size": "Small" }
}'const run = await duun.workflows.test("wf_base9c1d", {
mode: "dry",
input: { issue_url: "https://linear.app/acme/issue/PLT-466" },
force_outcomes: { size: "Small" },
});
for await (const entry of duun.runs.logs(run.id, { follow: true })) console.log(entry.text);run = client.workflows.test(
"wf_base9c1d",
mode="dry",
input={"issue_url": "https://linear.app/acme/issue/PLT-466"},
force_outcomes={"size": "Small"},
)
for entry in client.runs.logs(run.id, follow=True):
print(entry.text){
"id": "run_T4st0Wq9",
"object": "run",
"title": "Test: Add p95 latency panel to payouts dashboard",
"status": "queued",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 7,
"test": true,
"cost": { "spent_usd": 0, "limit_usd": 0, "billed_to": "duun" },
"created_at": "2026-11-15T11:10:02Z"
}The response is a full run object; the example is trimmed. A live test that would exceed a budget pauses at pause_at_pct and opens a budget ask, the same as any run.
Pause a workflow
https://api.duun.ai/v1/workflows/{workflow_id}/pause Stops the workflow from starting runs on its own. Runs in progress continue. Needs workflows:write.
Path parameters
-
workflow_idstring Required -
The workflow's id.
curl -X POST https://api.duun.ai/v1/workflows/wf_hotfix21b/pause \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.workflows.pause("wf_hotfix21b");client.workflows.pause("wf_hotfix21b"){ "id": "wf_hotfix21b", "object": "workflow", "status": "paused", "updated_at": "2026-11-15T11:12:00Z" }Resume a workflow
https://api.duun.ai/v1/workflows/{workflow_id}/resume Turns the workflow on, so its triggers start runs. Resuming a draft turns it on for the first time. Needs workflows:write.
Path parameters
-
workflow_idstring Required -
The workflow's id.
curl -X POST https://api.duun.ai/v1/workflows/wf_large7b31/resume \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.workflows.resume("wf_large7b31");client.workflows.resume("wf_large7b31"){ "id": "wf_large7b31", "object": "workflow", "status": "on", "updated_at": "2026-11-15T11:13:30Z" }Resuming a workflow whose live version has blocking problems returns 422 validation_error with problems. A workflow with no enabled trigger can be resumed, but nothing will start it except manual and API runs.
Related
- Versions and rollback and Test runs
duun workflows pull,diffandapplyfor workflows as code- Roll back a workflow in the help center