JPeetz/agent-skills / skills/api-backend/n8n-api-shape
n8n-api-shape
VerifiedUse this skill when working with the n8n REST API — read, update, or verify workflows on ANY n8n instance. Instance-agnostic: update recipe that strips extra fields on PUT, banned top-level fields, auth header, health endpoint.
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 propertieson 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
/healthbefore assuming workflow edits are possible. credentialsmust be popped from nodes before PUT or n8n rejects the payload.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |