n8n-api-shape

n8n REST API — Shape Reference (instance-agnostic)

A reusable, instance-agnostic reference for the n8n REST API. Usable on any n8n instance (a client's fresh one, or your own) without hardcoding host, instance, or workflow IDs.

When to Use This Skill

Use this skill when:

• You need to read, update, or verify an n8n workflow via the REST API.
• Prior skills point at a SPECIFIC n8n instance (a host/workflow ID) that does

not apply to the instance you're touching now.

• You hit 400 additional properties on workflow PUT.

Auth

• Header: X-N8N-API-KEY: <key> (generate at Settings → API; store in the vault by label).
• Base: https://<n8n-host>/api/v1/.

Read a workflow (GET)

GET /api/v1/workflows/{id} → returns the workflow JSON.

Update a workflow (PUT) — the exact recipe that works

n8n rejects extra fields on PUT with 400 additional properties. Strip to a minimal 4-key payload:

import json, requests
wf = requests.get(f"{base}/workflows/{wf_id}",
    headers={"X-N8N-API-KEY": key}, timeout=20).json()
for node in wf["nodes"]:
    for k in ["id", "position", "credentials", "webhookId"]:
        node.pop(k, None)
payload = {
    "name": wf["name"],
    "nodes": wf["nodes"],
    "connections": wf["connections"],
    "settings": {"executionOrder": wf["settings"].get("executionOrder", "v1")},
}
r = requests.put(f"{base}/workflows/{wf_id}",
    headers={"X-N8N-API-KEY": key, "Content-Type": "application/json"},
    json=payload, timeout=20)
assert r.status_code == 200, r.text

Banned top-level fields on PUT: id, active, tags, versionId, pinData, staticData, createdAt, updatedAt, meta, activeVersionId, versionCounter, triggerCount, shared, activeVersion, isArchived, description.

Health

GET /api/v1/health → {"status":"ok",...}. Check this first — an n8n instance whose API key is scoped wrong or host unreachable fails here before any workflow edit.

Guardrails

• The API key lives by label in the vault; never hardcode, never echo.
• Save the GET response to disk before editing (enables retry without re-fetch).
• Verify after every PUT (HTTP 200 + spot-check content).
• Never copy another instance's host/workflow IDs into a different profile.

PITFALLS

• 400 additional properties = payload has extra fields → use the strip recipe.
• Check /health before assuming workflow edits are possible.
• credentials must be popped from nodes before PUT or n8n rejects the payload.