jackson2w/claude-code-skills / n8n-workflow-api-authoring
n8n-workflow-api-authoring
UnverifiedThis skill should be used when authoring an n8n workflow as JSON to import via n8n's REST API (rather than hand-clicking in the editor), when an n8n HTTP Request node's attached credential seems to be silently ignored, when an n8n Code node throws "Module 'X' is disallowed", when a `{{ }}` expression field throws a bare "invalid syntax", when downstream Code node fields go missing/undefined after an HTTP Request node, when importing/updating an n8n workflow via `POST`/`PUT /api/v1/workflows` hits errors like "active is read-only", "PATCH method not allowed", or a referenced error-workflow name not resolving, when a Wait-node-delayed check using `$getWorkflowStaticData` gives a stale/wrong answer, or when decoding n8n's SQLite `execution_data` for debugging without an API key. Trigger phrases include "n8n workflow JSON", "n8n REST API import", "n8n credential not working", "n8n expression invalid syntax", "n8n Module crypto is disallowed", "n8n HTTP Request neverError", "n8n workflow active read-only", "POST /api/v1/workflows", "getWorkflowStaticData stale", "n8n Wait node static data", "n8n execution_data flatted decode".
n8n workflow authoring via REST API
Building an n8n workflow as a JSON file (agent-authored, or scripted) and importing it via
POST /api/v1/workflows, instead of hand-clicking every node in the editor. This is a reasonable
middle ground for config-as-code: workflow logic (nodes/connections) is versioned and
diffable; credentials are still created by hand in the editor so secret values never transit a
file or an agent's context (see the credentials section below). All of the gotchas here were
found the hard way building a real multi-node pipeline (Webhook → external API → GitHub Contents
API with retry logic) and getting it working end-to-end, not from documentation.
The workflow JSON shape
{
"name": "my-workflow",
"nodes": [ {"parameters": {...}, "name": "...", "type": "n8n-nodes-base.X", "typeVersion": N, "position": [x,y], "id": "...", "credentials": {...}} ],
"connections": { "Node A": { "main": [[ {"node": "Node B", "type": "main", "index": 0} ]] } },
"settings": { "executionOrder": "v1" }
}
Do not include active or id at the top level when creating — see "Import/update API
quirks" below.
Expression fields (={{ ... }}) are not full JavaScript — build complex bodies in a Code node instead
An HTTP Request node's JSON Body (or any ={{ }} field) looks like it accepts arbitrary JS, but
n8n's expression evaluator does not reliably support multi-statement code — an IIFE like:
={{ (() => { const x = ...; return JSON.stringify(x); })() }}
throws a bare invalid syntax with no useful line/column detail. The failure is also silent
about why — it just refuses to evaluate. This also breaks in a second, sneakier way: nesting a
second ={{ ... }}-looking string inside an outer expression (e.g. building a messages
array where one field's value is itself a quoted "={{ ... }}" string) gets misparsed, because
the expression scanner isn't brace-depth-aware across nested }} occurrences — it can terminate
the outer expression early at the first inner }}, silently truncating the rest of the object.
Fix: never build a nontrivial JSON body inline in an expression field. Add a Code node
immediately before the HTTP Request node that constructs the full body (real JS, JSON.stringify
included) and returns it as a single field, e.g. { ...previousFields, request_json: JSON.stringify(body) }. The HTTP node's Body field then becomes a trivial single-property
reference: ={{ $json.request_json }} — this form is reliable.
Attaching a credentials block is not enough — authentication must also be set
A node can have a valid credentials object (matching a real credential ID) and still silently
send an unauthenticated request, with no error, no warning in the API response — the target
API just sees a request with no auth header and returns its own 401, which looks like a bad
credential when the real bug is a missing parameter. The credentials field only makes a
credential available to the node; a separate parameters.authentication field decides whether
it's actually used:
- Generic Header Auth credential:
parameters.authentication = "genericCredentialType",parameters.genericAuthType = "httpHeaderAuth". - A predefined/built-in credential type (e.g. GitHub, Slack):
parameters.authentication = "predefinedCredentialType",parameters.nodeCredentialType = "githubApi"(or whatever the type name is).
Set both the credentials object and these parameters fields on every HTTP Request node that
needs auth — a credential attached without the matching authentication parameter is a silent
no-op.
HTTP Request nodes throw on non-2xx by default, and continueOnFail discards the whole item
If a workflow needs to inspect a status code (a 404 meaning "doesn't exist yet" is normal, a 409
meaning "retry with a fresh value" is normal), the naive approach — read $json.statusCode in a
downstream node with continueOnFail: true on the HTTP node — silently breaks:
- By default, any non-2xx response makes the HTTP Request node throw, not just return a status code to inspect.
- With
continueOnFail: true, the item that comes out of a thrown failure is a bare{ error: "<message>" }— it does not merge with whatever fields were on the input item. Every field the workflow had built up so far (a computed path, a title, a piece of content) is gone, and a downstream node referencing$json.titlegetsundefinedwith no obvious link back to "the HTTP node ate my data."
Fix: set parameters.options.response.response.neverError = true and
parameters.options.response.response.fullResponse = true. This makes the node return { statusCode, headers, body } for any status code without throwing, so status-code branching
becomes ordinary data inspection ($json.statusCode === 404) instead of exception handling with
data loss. (Note the doubled response.response nesting — that's how this node's parameter
schema is actually structured, not a typo.)
An HTTP Request node's output replaces the item — it does not carry the input forward
Separately from the above: even a successful HTTP Request node's output is just its own
response. It does not automatically merge in whatever fields were on the item flowing into it.
A Code node three hops downstream that assumes $input.first().json.title still has the value
set five nodes ago (after two HTTP Request hops in between) will get the last HTTP response's
fields instead, silently.
Fix: don't rely on implicit pass-through across an HTTP node. Reference the node that
actually produced the data you need, explicitly, from any later Code node:
$('Build Original Data').first().json.title — this works regardless of how many HTTP hops
happened in between, as long as that named node executed earlier in the same run.
The Code node sandbox blocks some require() calls
require('crypto') throws Module 'crypto' is disallowed inside a Code node — the sandbox
restricts which built-in modules are reachable, and crypto isn't in the default allow-list.
This is easy to miss until a specific code path (e.g. a hashing/dedup step) actually runs. If you
need a hash and don't need cryptographic properties (just determinism), write a small plain-JS
hash function (e.g. a djb2/FNV-style rolling hash over charCodeAt) instead of reaching for
crypto.createHash. Plain globals like Buffer are fine — it's specifically module require()
that's restricted, not every Node.js global.
Claude/Anthropic responses can include a thinking block before the text block
If an HTTP Request node calls the Anthropic Messages API and a downstream Code node parses the
response, don't assume response.content[0] is the text block — extended thinking (even if not
deliberately requested) can put a {"type": "thinking", ...} block first, pushing the real
{"type": "text", "text": "..."} block to index 1 or later. Find it by type instead of position:
const textBlock = (resp.content || []).find(b => b.type === 'text');
const text = textBlock?.text;
Import/update REST API quirks
POST /api/v1/workflowsrejectsactivein the body:request/body/active is read-only. Stripactive(andid, if present from a prior export) before posting. Activate separately viaPOST /api/v1/workflows/{id}/activate(there's also a/deactivate) after import.- Updating an existing workflow is
PUT, notPATCH:PATCH /api/v1/workflows/{id}returnsPATCH method not allowed. UsePUT /api/v1/workflows/{id}with the full{name, nodes, connections, settings}body — partial updates aren't supported, soGETthe current definition first, mutate what you need in memory, andPUTthe whole thing back. - An error-workflow reference needs the real numeric/string ID, not a name. If workflow A's
settings.errorWorkflowshould point at workflow B, import B first, capture its returnedidfrom the creation response, and set A'ssettings.errorWorkflowto that ID before importing A. A workflow name string in that field does not resolve. GET /api/v1/credentialsreturns id/name/type/sharing metadata only — never secret values. This is safe to call and inspect freely; use it to map credential names to their real instance-specific IDs so imported workflow JSON (which can only meaningfully carry anamefor portability) gets wired to working credentials rather than needing manual reselection in the editor after every import.- Credentials can be created via
POST /api/v1/credentialswith{name, type, data: {...}}where the shape ofdatamatches the credential type's fields (e.g. Header Auth wants{name, value}; GitHub API wants{server, user, accessToken}). This is fine for credentials that aren't themselves a sensitive third-party secret being freshly typed by a human (e.g. an n8n-internal API key used only for that instance's own execution lookups) — see the security note below for where to draw the line.
No usable API key? Update via the n8n CLI instead of the REST API
If no REST API key value was ever persisted (n8n never returns a key's raw value after creation)
and minting a fresh one means a human clicking through the editor UI, the n8n CLI is a
legitimate DB-backed alternative, run over SSH on the host with N8N_USER_FOLDER set to the
service's data dir:
n8n export:workflow --id=<id> --pretty --output=file.json # rollback point
# ...edit file.json's nodes/connections, keep "id" and "active"...
n8n import:workflow --input=file.json # updates in place by matching "id"
Two gotchas:
import:workflowalways deactivates the workflow, regardless of the JSON's"active"field.--activeState=fromJsonwould preserve it but only works in queue/multi-main mode — on a single-instance deployment it errors outright. Reactivate instead with the deprecated but functionalupdate:workflow --id=<id> --active=true.- Neither CLI command notifies the already-running server process — both write straight to
the DB, but a webhook's active registration lives in the running process's memory (set at
startup). The CLI says as much (
Note: Changes will not take effect if n8n is running...).systemctl restart n8n(or equivalent) is required afterward for the new node graph to actually take effect; verify via the startup log'sActivated workflow "<name>"line.
Where secrets should and shouldn't flow
Workflow JSON only ever references a credential by id/name — it never embeds a secret value.
Keep it that way deliberately: create any credential holding a genuine third-party secret
(an API key for an external service, a webhook shared secret, a bot token) by hand in the n8n
editor UI, not via a script that has the raw value passed through it, so the secret's only
resting place is n8n's own encrypted credential store. Reserve POST /api/v1/credentials
scripting for credentials that are themselves low-sensitivity/internal (e.g. an n8n API key
whose only purpose is calling that same n8n instance's own REST API).
When a secret genuinely does need to move between two hosts to get into place (e.g. reading an
existing token from one host's env file to configure something on another), never print it to
a terminal/tool-output transcript and never write it to a file at rest as an intermediate step —
pipe it directly host-to-host (ssh A "read-the-value" | ssh B "consume-it"), and have the
consuming side read it from stdin into a shell variable used immediately, not from a
positional argument or a file. This keeps the value out of both the visible output and any
on-disk trace, and out of shell history/process-argument visibility on either host.
Rotating an existing credential's value is a different case from creating a new one, and API
scripting is fine here even for a genuine third-party secret — the "create by hand in the
editor" guidance above is about not having a brand-new secret value pass through a script; once
a credential already exists, PATCH /api/v1/credentials/{id} updates it in place (confirmed
working 2026-07-19, credentialSchema-shaped data object, e.g.
{"name": "...", "type": "telegramApi", "data": {"accessToken": "...", "baseUrl": "..."}} for a
Telegram credential — the GET response never echoes data back, consistent with n8n's
write-only-secrets design). Since the destination here is an HTTPS API rather than another
SSH-reachable host, the host-to-host pipe pattern above doesn't directly apply — instead, build
the request body server-side, on the same host that already holds the source value (e.g. a
small Python script using urllib/requests, run over SSH on that host), so the raw value only
ever exists in that host's process memory long enough to make the API call, and never appears in
any command's arguments, any intermediate file, or anything that flows back to the calling
session. See the credential-rotation-protocol skill for the general version of this pattern.
Debugging a failed execution via the API
GET /api/v1/executions/{id}?includeData=true returns the full run, including
data.resultData.error (message/description of what failed and lastNodeExecuted) and
data.resultData.runData (a per-node log of what each node actually received/returned — the
fastest way to see exactly which field was undefined or which status code came back, rather
than guessing from the workflow JSON alone).
$getWorkflowStaticData is unsafe as a signal between separate webhook executions when a Wait node is involved
$getWorkflowStaticData('global') looks like a simple shared mutable object any node in the
workflow can read/write, and it does persist to the workflow_entity.staticData column across
runs. But a paused Wait-node execution resumes from a snapshot of static data taken when it
started/was queued, not a live re-read of the current DB row. If workflow logic looks like
"execution A writes a completion flag, execution B (paused in a Wait node since before A started)
reads that flag after waking up," B will not see A's write even though A's write landed in the DB
well before B resumed — B is working from stale state captured at its own start time. This is
easy to hit with a "did event Y happen before this timeout" pattern across two different webhook
event types hitting the same workflow. Confirmed by inspecting real execution data (see below):
both executions agreed on the same business key (a meeting ID in this case), ruling out a
data-shape mismatch — the write was simply invisible to the already-paused reader.
Fix: don't use static data as a cross-execution signal when a Wait node separates the writer
and reader in time. Make the post-wait check authoritative against real external state instead —
e.g., query the actual system of record (a GitHub file's existence, a database row, an API) for
whatever the "did it happen" question really depends on. Regular node-to-node references
($json, $('Node Name')) are NOT affected by this — they're part of the execution's own
persisted run data and survive a Wait-node pause/resume correctly; it's specifically the
workflow-global static data object that's snapshotted.
Decoding execution data straight from n8n's SQLite DB (no API key needed)
When there's no REST API key and you need to inspect real historical execution payloads/outputs
(e.g. to diagnose the static-data issue above), n8n's execution_data.data column is
flatted-encoded (a deduplicating JSON serialization, not plain JSON) — JSON.parse on it
fails or produces garbage. Decode with the flatted package n8n already ships:
const { parse } = require('/usr/lib/node_modules/n8n/node_modules/flatted/cjs/index.js');
// row.data is the raw column value (read via sqlite3's stdlib module and written to a file —
// avoid piping through multiple nested SSH hops with inline shell quoting, it mangles the string)
const data = parse(fs.readFileSync('/tmp/exec_row.json', 'utf8'));
const run = data.resultData.runData; // keyed by node name, each an array of run attempts
console.log(run['Some Node'][0].data.main[0][0].json);
Get the raw row with a small Python script (stdlib sqlite3, no CLI tool needed) writing straight
to a file — safer than threading the value through shell command substitution across an SSH hop.
execution_entity (id, workflowId, status, startedAt, stoppedAt) is plain columns and queryable
directly; only execution_data.data needs the flatted decode.
Retiring an unused credential on SQLite with no API key (2026-09-12, n8n 2.37)
The CLI can't delete credentials. The public API needs a user API key, and creating one just to delete something is a new credential path. Using the UI is fine if a human is present. Otherwise:
- Prove it's unused, by id AND by name, read-only via Python's stdlib
sqlite3withfile:…?mode=ro, since thesqlite3CLI is often not installed. Checkworkflow_entity.nodes,workflow_history.nodes, and every table with a credential column. - Map the foreign keys first, because 2.x grew many tables:
pragma foreign_key_list(<t>)for each table referencingcredentials_entity. On 2.37:shared_credentials,credential_dependency,agent_credential_dependencyanddynamic_credential_*: CASCADEchat_hub_*: SET NULLinstance_credential_assignment: RESTRICT, so it must have no row for the target
- Take an encrypted backup, loading the env from its file inside a root shell so the encryption
key never goes on a command line:
bash -c 'set -a; . /root/.config/n8n.env; set +a; exec runuser -u n8n -m -- n8n export:credentials --id=<id> --output=<dir>/cred.json'. Confirm itsdatais still an encrypted string. - Stop n8n, copy
database.sqlite,-shmand-waltogether, then delete in one transaction withpragma foreign_keys=ON(SQLite's default is off, so cascades wouldn't run). Assert that exactly 1 row was deleted and the dependent rows went to 0, otherwise roll back. - Start n8n and poll
/healthzfor 200 (about 5 s downtime), then confirm the other credentials and active workflows are intact.
Failed to start Python task runner in internal mode … virtual environment is missing at startup is a
long-standing, benign message on npm installs without the Python runner. Check whether it predates a
change before attributing it to one.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |