Use when integrating with n8n programmatically, managing workflows via API, or building n8n admin tools. Prevents authentication errors and incorrect endpoint usage. Covers all REST API endpoints (workflows, executions, credentials, users, tags, variables, projects), API key authentication via X-N8N-API-KEY header, cursor-based pagination, and API configuration. Keywords: n8n, REST API, endpoints, API key, X-N8N-API-KEY, pagination,, manage workflows via API, programmatic access, admin tool, external control. workflows, executions, credentials, admin tools.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when integrating with n8n programmatically, managing workflows via API, or building n8n admin tools. Prevents authentication errors and incorrect endpoint usage. Covers all REST API endpoints (workflows, executions, credentials, users, tags, variables, projects), API key authentication via X-N8N-API-KEY header, cursor-based pagination, and API configuration. Keywords: n8n, REST API, endpoints, API key, X-N8N-API-KEY, pagination,, manage workflows via API, programmatic access, admin tool, external control. workflows, executions, credentials, admin tools.
license
MIT
compatibility
Designed for Claude Code. Requires n8n v1.x.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
n8n-core-api
Quick Reference
API Fundamentals
Aspect
Value
Base URL
<N8N_HOST>:<N8N_PORT>/<N8N_PATH>/api/v1/
Authentication
X-N8N-API-KEY header
Content-Type
application/json
Pagination
Cursor-based (nextCursor field)
Max page size
250 results
Default page size
100 results
API Playground
<base-url>/api/v1/docs (Scalar UI)
Availability
Requires a paid plan (not available during free trial)
Resource Endpoints Overview
Resource
CRUD
Special Operations
Workflows
GET, POST, PUT, DELETE
activate, deactivate, transfer, tags, versions
Executions
GET, DELETE
retry, stop, stop-bulk, tags
Credentials
GET, POST, PUT, DELETE
transfer, credential-type schema
Users
GET
role management
Tags
GET, POST, PUT, DELETE
—
Variables
GET, POST, PUT, DELETE
—
Projects
GET, POST, PUT, DELETE
user management
Audit
POST
security audit
Source Control
POST
pull from source control
Critical Warnings
NEVER use offset-based pagination -- n8n uses cursor-based pagination exclusively. ALWAYS use the nextCursor value from the response to fetch the next page.
NEVER hardcode API keys in source code or commit them to version control. ALWAYS use environment variables or secret management systems to store API keys.
NEVER use limit values greater than 250 -- the API silently caps at 250 results per page. ALWAYS implement cursor-based pagination for large result sets.
NEVER attempt to delete a running execution -- the API returns an error. ALWAYS stop the execution first with POST /executions/:id/stop, then delete it.
NEVER assume API access is available on free trial instances -- the public REST API requires a paid plan.
Authentication
API Key Creation
Navigate to Settings > n8n API in the n8n UI
Select Create API Key
Provide a label and set an expiration period
On enterprise plans, select specific scopes for resource access
Copy the generated key immediately (it is shown only once)
Header Format
ALWAYS include the API key in every request:
X-N8N-API-KEY: <your-api-key>
Scope System (Enterprise Only)
Non-enterprise API keys grant full access to all account resources. Enterprise instances support scope-based restrictions per key. Scopes follow the pattern resource:action:
Scope Pattern
Example
workflow:list
List workflows
workflow:create
Create workflows
workflow:read
Read single workflow
workflow:update
Update workflow content
workflow:delete
Delete workflow
workflow:activate
Activate workflow
workflow:deactivate
Deactivate workflow
workflow:move
Transfer workflow to another project
execution:list
List executions
execution:read
Read single execution
execution:delete
Delete execution
execution:retry
Retry failed execution
execution:stop
Stop running execution
credential:list
List credentials
credential:create
Create credentials
credential:update
Update credentials
credential:delete
Delete credentials
credential:move
Transfer credentials
Cursor-Based Pagination
How It Works
First request: specify limit (default 100, max 250)
Response contains data array and nextCursor string
Pass nextCursor as cursor parameter in the next request
When nextCursor is null or absent, you have reached the last page
Pagination Pattern
Request 1: GET /api/v1/workflows?limit=100
Response 1: { "data": [...], "nextCursor": "MTIzNA==" }
Request 2: GET /api/v1/workflows?limit=100&cursor=MTIzNA==
Response 2: { "data": [...], "nextCursor": "NTY3OA==" }
Request 3: GET /api/v1/workflows?limit=100&cursor=NTY3OA==
Response 3: { "data": [...], "nextCursor": null } // Last page
ALWAYS check for nextCursor being null or absent to detect the final page. NEVER assume a fixed number of pages.
The interactive API documentation (Scalar UI) is available at:
<base-url>/api/v1/docs
This is available on self-hosted instances by default. Set N8N_PUBLIC_API_SWAGGERUI_DISABLED=true to disable it in production.
Decision Trees
Which Endpoint to Use?
Need to manage workflow definitions?
├── List/search workflows → GET /workflows (with query filters)
├── Create new workflow → POST /workflows
├── Update workflow JSON → PUT /workflows/:id
├── Delete workflow → DELETE /workflows/:id
├── Toggle activation → POST /workflows/:id/activate or /deactivate
└── Move to project → POST /workflows/:id/transfer
Need to inspect or manage executions?
├── List executions → GET /executions (filter by status, workflowId)
├── Get execution detail → GET /executions/:id?includeData=true
├── Retry failed → POST /executions/:id/retry
├── Stop running → POST /executions/:id/stop
└── Bulk stop → POST /executions/stop
Need to manage credentials?
├── List credentials → GET /credentials
├── Create credential → POST /credentials
├── Update credential → PUT /credentials/:id
├── Delete credential → DELETE /credentials/:id
├── Get type schema → GET /credential-types/:typeName
└── Move to project → POST /credentials/:id/transfer
Need organizational resources?
├── Tags → /tags (CRUD)
├── Variables → /variables (CRUD)
├── Projects → /projects (CRUD + user management)
└── Users → /users (list, get, role)
Should You Use the API or the CLI?
Running n8n in Docker/remote?
├── YES → Use REST API (only option for remote management)
└── NO (local access to n8n process)
├── Need programmatic integration? → REST API
├── One-off admin task? → CLI (n8n export, n8n import)
└── Backup automation? → CLI for export, API for monitoring
Reference Links
references/methods.md -- Complete endpoint reference with methods, paths, and scopes
references/examples.md -- curl examples for each major resource type with authentication and pagination
