---
title: "Patch a single node in a workflow definition"
method: PATCH
path: "/api/workflows/{id}/nodes/{nodeId}"
tags: ["Workflows"]
---

# Patch a single node in a workflow definition

`PATCH /api/workflows/{id}/nodes/{nodeId}`

## Path parameters

- `id` string, required
- `nodeId` string, required

## Request body

- object
  - `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.

## Response `200`

Node patched (version snapshot created)

## Other responses

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

---

[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)