---
title: "Patch a workflow definition (create/update/delete nodes)"
method: PATCH
path: "/api/workflows/{id}"
tags: ["Workflows"]
---

# Patch a workflow definition (create/update/delete nodes)

`PATCH /api/workflows/{id}`

## Path parameters

- `id` string, required

## Request body

- object
  - `update` object[] — Nodes to update (partial merge)
    - `nodeId` string, required — ID of the node to update
    - `node` object, required — Partial node data to merge
      - `type` string — Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'validate', 'property-match'
      - `label` string — Human-readable label for UI display
      - `config` object — Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode? }. 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` object
        - `executor` string
        - `config` object, required
        - `mustPass` boolean
        - `retry` object
          - `maxRetries` integer
          - `strategy` 'exponential' | 'static' | 'linear'
          - `baseDelayMs` integer
          - `maxDelayMs` integer
      - `retry` object
        - `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.
  - `delete` string[] — Node IDs to delete
  - `create` object[] — New nodes to add
    - `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? }. 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` object
      - `executor` string
      - `config` object, required
      - `mustPass` boolean
      - `retry` object
        - `maxRetries` integer
        - `strategy` 'exponential' | 'static' | 'linear'
        - `baseDelayMs` integer
        - `maxDelayMs` integer
    - `retry` object
      - `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' — Update the definition-level onNodeFailure behavior
  - `triggerSchema` object, nullable — Optional JSON-Schema describing the expected trigger payload shape. Pass an object to set/replace; pass null to clear; omit to leave unchanged. Validator subset: type, required, properties, enum, const, items. Other JSON-Schema keywords are silently ignored.
  - `key` string — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.

## Response `200`

Workflow patched (version snapshot created)

## Other responses

- `400` — Invalid patch or resulting definition
- `404` — Workflow not found

## Changes

- **2026-07-11** `f1022d5edb0d` — 1 info
  - added the new optional request property `key`
- **2026-07-02** `0c910612f9ac` — 1 warning
  - removed the request property `key`

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/workflows/:id/patch.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/revisions/92a1dcbd2fc7/schema)