Workflow Authoring Reference

Use this reference when you want Dawn, an agent, or an API client to create and update workflows predictably. It documents the workflow definition shape, field semantics, validation flow, and links to the event, node, and run-state subpages.

When To Use This Reference

Use this page when you need the exact workflow definition fields, request shape, or authoring sequence. For product concepts, start with Workflows. For constants and detailed behavior, use these subpages:

• Workflow Events lists event type IDs, provider native event IDs, subject kinds, and compatible source kinds.
• Workflow Nodes And Branches lists agent_run and control node behavior, condition syntax, joins, fan-out, and loops.
• Workflow Runs And Statuses lists run, step, delivery, retry, rerun, and output delivery states.

The live workspace API is still authoritative. A workspace can only create workflows for events and recipes returned by that workspace’s workflow-recipes and workflow-event-support endpoints, because those results account for connected integrations and linked sources.

Required Role

Workflow definition and run-control endpoints require workspace manager access. The workflow does not grant extra source permissions: the selected agent must already be assigned to the connected source that the trigger uses.

Authoring Flow

For agent-created workflows, use this sequence:

1. List available recipes and event support for the workspace.
2. Select a compatible source and event type from the returned descriptors.
3. Select an agent that is assigned to the same source and has the tools the prompt needs.
4. Build a workflow definition with stable nodeKey values.
5. Validate the definition before saving or enabling it.
6. Save disabled first when the workflow was generated from free-form instructions.
7. Enable only after validation passes and the user confirms the source, events, and prompt.

Core Definition Fields

Concurrency Policies

queueDedupeSeconds applies to queued workflow starts. Use it when the workflow should keep queue semantics but avoid duplicate pending runs caused by repeated delivery of the same event or rapid identical updates.

Trigger Fields

For integration workflows, eventTypes must all be supported by the selected source. For schedule workflows, use provider dawn, trigger type schedule, and event type dawn.schedule.elapsed when an event type is required by the caller.

Step Fields

Use stable, readable nodeKey values such as review, security_review, summary, and notify. Do not generate random node keys unless the workflow is temporary, because condition outputs, loops, and canvas layout reference these keys.

Minimal Workflow Example

{
  "name": "PR review",
  "description": "Review pull requests when they are opened or updated.",
  "enabled": false,
  "agentProfileId": "00000000-0000-0000-0000-000000000000",
  "concurrencyPolicy": "debounce_by_subject",
  "debounceSeconds": 90,
  "queueDedupeSeconds": null,
  "triggers": [
    {
      "triggerType": "integration_event",
      "provider": "github",
      "connectionId": "11111111-1111-1111-1111-111111111111",
      "sourceId": "22222222-2222-2222-2222-222222222222",
      "eventTypes": [
        "github.pull_request.created",
        "github.pull_request.updated"
      ]
    }
  ],
  "steps": [
    {
      "order": 1,
      "nodeKey": "review",
      "name": "Review pull request",
      "stepType": "agent_run",
      "prompt": "/pr-review\n\nReview the pull request that triggered this workflow. Return findings first, with file references where possible, and say explicitly when no blocking findings are found.",
      "dependsOn": []
    }
  ]
}

Parallel Review Example

Use separate root agent_run nodes to fan out work. Add a join node before a summary step when downstream output should wait for every review branch.

{
  "steps": [
    {
      "order": 1,
      "nodeKey": "general_review",
      "name": "General review",
      "stepType": "agent_run",
      "prompt": "Review correctness, regressions, and missing tests.",
      "dependsOn": []
    },
    {
      "order": 2,
      "nodeKey": "security_review",
      "name": "Security review",
      "stepType": "agent_run",
      "prompt": "Review authentication, authorization, secret handling, and unsafe data exposure.",
      "dependsOn": []
    },
    {
      "order": 3,
      "nodeKey": "join_reviews",
      "name": "Wait for reviews",
      "stepType": "control",
      "settingsJson": "{\"controlType\":\"join\",\"joinPolicy\":\"all_terminal\"}",
      "dependsOn": ["general_review", "security_review"]
    },
    {
      "order": 4,
      "nodeKey": "summary",
      "name": "Summarize review",
      "stepType": "agent_run",
      "prompt": "Summarize the upstream review outputs into one concise PR comment.",
      "dependsOn": ["join_reviews"]
    }
  ]
}

Validation And Save

Validate before create or update:

• POST /api/v1/workspaces/{workspaceId}/workflows/validate validates a new definition.
• POST /api/v1/workspaces/{workspaceId}/workflows/{workflowId}/validate validates an update.
• POST /api/v1/workspaces/{workspaceId}/workflows creates.
• PATCH /api/v1/workspaces/{workspaceId}/workflows/{workflowId} updates.

Validation returns:

Recipe Instantiation

Recipes are provider- or system-owned starting points. They are listed by:

GET /api/v1/workspaces/{workspaceId}/workflow-recipes

Each recipe exposes:

Instantiate a recipe with:

POST /api/v1/workspaces/{workspaceId}/workflow-recipes/{recipeId}/instantiate

Request fields:

Safe Agent Authoring Rules

Agents that create workflows should follow these rules:

• Prefer recipes when a matching recipe exists.
• Read event support before inventing event IDs.
• Save generated workflows disabled unless the user explicitly asks to enable them.
• Use debounce_by_subject for PR and issue update flows unless every event must run.
• Use queue for scheduled reports and human-visible lifecycle events.
• Use stable nodeKey values and never duplicate a nodeKey in one workflow.
• Use Prompt Commands in prompt when the workflow should behave like a manual chat command.
• Validate before saving, then show validation issues rather than guessing a fix.
• Do not create delivery targets other than the built-in workspace notification unless the target is documented for the current environment.