N8n API Reference

n8n REST API Reference

Overview

n8n Public API v1.1.1. OpenAPI 3.0 specification. 37 endpoints across 11 tags.

The public API allows programmatic access to workflows, executions, credentials, tags, users, variables, projects, data tables, source control, and audit features.

Full OpenAPI spec available at: references/n8n-api.json

Authentication

All API requests require an API key passed via the X-N8N-API-KEY header.

Generating an API Key

1. Open your n8n instance
2. Go to Settings → API
3. Click Create API Key
4. Copy the generated key

Base URL

${N8N_API_URL}/api/v1

Header Format

X-N8N-API-KEY: <your-api-key>

Quick Verification

curl -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/api/v1/workflows?limit=1"

If you get a 200 response with workflow data, authentication is working.

Endpoint Reference by Tag

Workflow (10 endpoints)

Query parameters for GET /workflows:

• limit — Number of results (default 10, max 250)
• cursor — Pagination cursor from previous response
• tags — Filter by tag name
• name — Filter by workflow name (partial match)
• active — Filter by active status (true/false)
• projectId — Filter by project

Execution (7 endpoints)

Query parameters for GET /executions:

• workflowId — Filter by workflow ID
• status — Filter: error, success, waiting, running, new
• limit — Number of results (default 10, max 250)
• cursor — Pagination cursor
• startedBefore / startedAfter — Date range filters (ISO 8601)

Credential (5 endpoints)

Important: GET /credentials never returns secret data. Use the schema endpoint to understand required fields before creating credentials.

DataTable (7 endpoints)

User (4 endpoints)

Roles: global:owner, global:admin, global:member

Tags (4 endpoints)

Audit (1 endpoint)

Body options:

{
  "categories": ["credentials", "nodes", "database", "filesystem", "instance"]
}

SourceControl (1 endpoint)

Variables (4 endpoints)

Variables are accessible in workflows via $vars.variableName.

Projects (4+ endpoints)

Projects support member management — add/remove users with specific roles per project.

Discover (1 endpoint)

Common curl Patterns

List Workflows

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows"

Get Workflow by ID

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows/123"

Create Workflow

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Workflow","nodes":[],"connections":{},"settings":{}}' \
  "$N8N_API_URL/api/v1/workflows"

Activate Workflow

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows/123/activate"

Deactivate Workflow

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows/123/deactivate"

List Executions (filtered)

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/executions?workflowId=123&status=error&limit=10"

Retry Failed Execution

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/executions/456/retry"

Create Credential

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My API Key","type":"httpHeaderAuth","data":{"name":"Authorization","value":"Bearer xxx"}}' \
  "$N8N_API_URL/api/v1/credentials"

Get Credential Schema

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/credentials/schema/httpHeaderAuth"

Create Tag

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}' \
  "$N8N_API_URL/api/v1/tags"

Tag a Workflow

curl -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"id":"tag-id-here"}]' \
  "$N8N_API_URL/api/v1/workflows/123/tags"

List Variables

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/variables"

Run Security Audit

curl -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categories":["credentials","nodes","instance"]}' \
  "$N8N_API_URL/api/v1/audit"

Get Data Table Rows

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/data-tables/dt-abc123/rows?limit=50"

Pagination

The n8n API uses cursor-based pagination.

How It Works

1. First request: GET /workflows?limit=10
2. Response includes nextCursor if more results exist
3. Next request: GET /workflows?limit=10&cursor=<nextCursor-value>
4. Repeat until nextCursor is absent

Response Structure

{
  "data": [...],
  "nextCursor": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9"
}

When nextCursor is null or absent, you have reached the last page.

Pagination Example (bash loop)

CURSOR=""
while true; do
  RESPONSE=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
    "$N8N_API_URL/api/v1/workflows?limit=50${CURSOR:+&cursor=$CURSOR}")
  echo "$RESPONSE" | jq '.data[]'
  CURSOR=$(echo "$RESPONSE" | jq -r '.nextCursor // empty')
  [ -z "$CURSOR" ] && break
done

Error Responses

Error Response Format

{
  "code": 404,
  "message": "Workflow with ID \"999\" could not be found."
}

Rate Limits and Best Practices

• No official rate limits documented, but self-hosted instances may have resource constraints
• Use pagination (limit + cursor) for large datasets instead of fetching all at once
• Cache credential schemas — they rarely change
• Use status and workflowId filters on executions to reduce response size
• Prefer PATCH over PUT for credentials to avoid overwriting unchanged fields
• When bulk-operating, add small delays between requests to avoid overloading the instance