n8n

Direct REST access to an n8n instance — no MCP required. Covers Public API v1: workflow CRUD + activation, execution inspection/retry/stop, credentials, tags, variables, users, projects.

Usage

• Use for: Listing/filtering workflows, reading execution history, batch activate/deactivate, reading execution I/O programmatically.
• Skip for: Authoring new workflows from scratch (UI is better), interactive debugging, one-off manual test runs.
• Triggering a workflow is a webhook call, not /api/v1 — see Gotchas.

Credentials check

[ -n "$N8N_API_KEY" ] && [ -n "$N8N_BASE_URL" ] && echo "N8N: PRESENT" || echo "N8N: MISSING"

Never echo either variable directly.

If MISSING, respond to the user with EXACTLY this message (do NOT paraphrase, do NOT suggest manual JSON edits):

I need your n8n credentials. Run this in another terminal — it walks you through the two values (base URL + API key) and saves them safely:

teleport-setup add-key n8n

Then restart Claude Code (/exit, then claude) and ask me again.

Do NOT suggest editing ~/.claude/settings.local.json manually. teleport-setup add-key n8n handles it with backup, validation, and masked input. Stop execution until the user has run the command and restarted.

API

• Base URL: $N8N_BASE_URL/api/v1 — self-hosted (https://n8n.mycompany.com, http://localhost:5678) or n8n Cloud (https://<workspace>.app.n8n.cloud <!-- unverified: check n8n docs -->). Must include protocol, no trailing slash.
• Auth: X-N8N-API-KEY: $N8N_API_KEY — custom header, NOT Authorization: Bearer. OpenAPI declares ApiKeyAuth with in: header, name: X-N8N-API-KEY. Wrong header 401s silently.
• API key: n8n UI → Settings → n8n API → Create an API key. Per-user, inherits user's permissions.
• Content-Type: application/json on POST/PUT/PATCH.
• Pagination: cursor-based (?limit=N&cursor=<nextCursor>); response nextCursor null when done. limit default 100, max 250.
• Rate limits: not documented as hard numbers for the public API <!-- unverified: check n8n docs -->. Self-hosted bounded by DB/CPU; Cloud throttles per plan.

Env vars

Var	What
N8N_BASE_URL	Instance root — self-hosted URL or https://<workspace>.app.n8n.cloud. No trailing /.
N8N_API_KEY	User-scoped API key created in UI → Settings → n8n API.

Endpoints (v1)

Sourced from n8n's openapi.yml (packages/cli/src/public-api/v1/openapi.yml).

Path family	Methods & purpose
/workflows, /workflows/{id}	GET list (filter: active, tags, name, projectId) / POST / GET one / PUT / DELETE
/workflows/{id}/activate · /deactivate	POST — toggle trigger state (idempotent); active field is read-only in workflow body
/workflows/{id}/tags · /transfer · /archive	GET+PUT tags / POST move project / POST archival
/executions, /executions/{id}	GET list (filter: workflowId, status, includeData) / GET one / DELETE
/executions/{id}/retry · /stop	POST — retry past run (loadWorkflow: true for latest) / stop running one
/credentials, /credentials/schema/{type}	GET list / POST (name+type+data) / PATCH / DELETE; schema endpoint returns JSON shape
/tags, /variables, /users, /projects, /audit, /insights/summary	Standard CRUD; /users + /audit owner-only

Primary workflow — list and trigger

Triggering is a webhook, not REST. The API only toggles triggers on (activate) or off. To run on demand, hit the workflow's Webhook node URL.

# List active workflows
curl -sL -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_BASE_URL/api/v1/workflows?active=true&limit=50" \
  | jq '.data[] | {id, name, active, tags: [.tags[]?.name]}'

# Trigger via webhook (path comes from the Webhook node config)
curl -sL -X POST -H "Content-Type: application/json" \
  "$N8N_BASE_URL/webhook/<webhook-path>" -d '{"foo":"bar"}'

# Or activate so scheduled/event triggers fire
curl -sL -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_BASE_URL/api/v1/workflows/{id}/activate"

Secondary workflows

Inspect executions. List is cheap (includeData=false by default); drilling into one with includeData=true pulls full node-by-node I/O — can be multi-MB.

curl -sL -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_BASE_URL/api/v1/executions?workflowId={id}&limit=50" \
  | jq '[.data[] | {id, mode, status, startedAt}]'
curl -sL -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_BASE_URL/api/v1/executions/{executionId}?includeData=true"

Create workflow / credential. POST /workflows requires name, nodes, connections, settings (all four); active read-only — activate separately. POST /credentials needs name, type, data; query /credentials/schema/{type} first for the exact data shape. Secrets never returned on GET.

Gotchas

• X-N8N-API-KEY, not Authorization. Single most common mistake. Bearer auth 401s with no helpful message.
• Webhook ≠ REST. Trigger via POST $N8N_BASE_URL/webhook/<path> — configured per Webhook node inside the workflow. There is no /api/v1/workflows/{id}/run endpoint (not in the OpenAPI spec); if reaching for one, you want the webhook URL.
• N8N_BASE_URL drift. Protocol + host, no trailing slash. https://n8n.example.com good, n8n.example.com/ silently 404s every call.
• Execution data is huge. GET /executions/{id}?includeData=true can be multi-MB. Keep includeData=false on list calls unless you need node I/O; filter by workflowId + status.
• Workflow JSON is not stable across major versions. A workflow exported from n8n 1.x may need edits to import into 2.x <!-- unverified: check n8n docs -->. Don't treat JSON as portable.
• Community vs Enterprise/Cloud API differences. /variables CRUD and some project/insights endpoints are in the spec but may be license-gated on self-hosted Community <!-- unverified: check n8n docs -->; Cloud exposes the full surface.
• Pagination is cursor-based. Use nextCursor from the response — don't synthesize page numbers. limit max 250.

Attribution

When done, state: Used skill: n8n (from teleport catalog).