---
title: "Get a workflow by ID"
method: GET
path: "/api/workflows/{id}"
tags: ["Workflows"]
---

# Get a workflow by ID

`GET /api/workflows/{id}`

## Path parameters

- `id` string, required

## Response `200`

Workflow details with auto-generated edges

- object
  - `id` string, uuid, required
  - `key` string, required — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
  - `name` string, required
  - `description` string
  - `enabled` boolean, required
  - `definition` WorkflowDefinition, required
    - `nodes` WorkflowNode[], required
      - `id` string, required — Unique node identifier, used in 'next' and 'inputs' mappings
      - `type` string, required — Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'validate', 'property-match'
      - `label` string — Human-readable label for UI display
      - `config` object, required — Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode?, timeoutMs? (1000-300000) }. Values support {{interpolation}} from the node's inputs context. NOTE: config.outputSchema on agent-task nodes validates the AGENT's raw JSON output, while node-level outputSchema validates the EXECUTOR's return value ({taskId, taskOutput}).
      - `next` union — Next node(s): string for simple chaining, string[] for fan-out to parallel nodes, or record for port-based routing ({pass: 'a', fail: 'b'})
        - string
        - string[]
        - object
      - `validation` StepValidationConfig
        - `executor` string
        - `config` object, required
        - `mustPass` boolean
        - `retry` RetryPolicy
          - `maxRetries` integer
          - `strategy` 'exponential' | 'static' | 'linear'
          - `baseDelayMs` integer
          - `maxDelayMs` integer
      - `retry` RetryPolicy
        - `maxRetries` integer
        - `strategy` 'exponential' | 'static' | 'linear'
        - `baseDelayMs` integer
        - `maxDelayMs` integer
      - `inputs` object — REQUIRED for cross-node data access. Maps local names to context paths. Without this, upstream step outputs are NOT available for interpolation — only 'trigger' and 'input' are. Example: { "cityData": "generate-city" } → use {{cityData.taskOutput.field}} in config templates. For trigger data: { "pr": "trigger.pullRequest" }.
      - `inputSchema` object — JSON Schema to validate resolved inputs before execution
      - `outputSchema` object — JSON Schema to validate the executor's output (e.g. {taskId, taskOutput} for agent-task). Different from config.outputSchema which validates the agent's raw output.
    - `onNodeFailure` 'fail' | 'continue' — Behavior when a node's task fails or is cancelled. 'fail' (default): mark the entire run as failed. 'continue': treat the failed node as completed with error output and proceed — downstream convergence nodes receive '[FAILED: reason]' and can handle partial results.
  - `triggers` union[]
    - union
      - object
        - `type` 'webhook', required
        - `hmacSecret` string
        - `hmacHeader` string — Legacy HMAC header for webhook verification. Prefer verification.header for new workflows.
        - `verification` union — Optional webhook verification format. Omit to keep legacy HMAC-SHA256 behavior with fallback header scanning.
          - object
            - `format` 'hmac-sha256', required
            - `header` string — Header containing HMAC-SHA256 over the raw request body. Accepts sha256=<hex> or bare hex.
          - object
            - `format` 'timestamped-hmac-sha256', required
            - `header` string, required — Header containing comma-separated timestamp/signature pairs such as t=<timestamp>,v1=<hex>.
            - `timestampKey` string — Timestamp field key in the signature header
            - `signatureKey` string — Signature field key in the signature header; multiple entries are allowed
            - `toleranceSeconds` integer — Maximum allowed clock skew, in seconds, for replay protection
          - object
            - `format` 'token-equality', required
            - `header` string, required — Header containing the shared token to compare
      - object
        - `type` 'schedule', required
        - `scheduleId` string, uuid, required
  - `cooldown` object
    - `hours` number
    - `minutes` number
    - `seconds` number
  - `input` object
  - `triggerSchema` object
  - `dir` string
  - `vcsRepo` string
  - `createdByAgentId` string
  - `createdAt` string, required
  - `lastUpdatedAt` string, required
  - `createdBy` string
  - `updatedBy` string
  - `favorite` boolean
  - `edges` WorkflowEdge[], required
    - `id` string, required
    - `source` string, required
    - `sourcePort` string, required
    - `target` string, required

## Other responses

- `404` — Workflow not found

---

[API](https://skmtc.net/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.net/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/versions/0375890be8c4/schema)