n8n

Troubleshooting

If requests fail, run zero doctor check-connector --env-name N8N_TOKEN or zero doctor check-connector --url ${N8N_BASE_URL}/api/v1/workflows --method GET

Authentication

All endpoints require the API key in a header:

X-N8N-API-KEY: $N8N_TOKEN

Environment Variables

Variable	Description
`N8N_TOKEN`	n8n API key (generated in Settings → n8n API)
`N8N_BASE_URL`	Base URL of your n8n instance, e.g. `https://your-instance.app.n8n.cloud`

Base URL

All endpoints are at ${N8N_BASE_URL}/api/v1.

The API is not available during the n8n Cloud free trial. For self-hosted instances it requires n8n ≥ 0.174.

Workflows

List Workflows

curl -s "${N8N_BASE_URL}/api/v1/workflows" --header "X-N8N-API-KEY: $N8N_TOKEN"

With pagination (max 250 per page):

curl -s "${N8N_BASE_URL}/api/v1/workflows?limit=50&cursor=<next-cursor>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Filter by tag:

curl -s "${N8N_BASE_URL}/api/v1/workflows?tags=<tag-name>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Get a Workflow

curl -s "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Activate a Workflow

curl -s -X POST "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>/activate" --header "X-N8N-API-KEY: $N8N_TOKEN"

Deactivate a Workflow

curl -s -X POST "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>/deactivate" --header "X-N8N-API-KEY: $N8N_TOKEN"

Create a Workflow

Write to /tmp/n8n_workflow.json:

{
  "name": "<workflow-name>",
  "nodes": [],
  "connections": {},
  "settings": {
    "executionOrder": "v1"
  }
}

curl -s -X POST "${N8N_BASE_URL}/api/v1/workflows" --header "X-N8N-API-KEY: $N8N_TOKEN" --header "Content-Type: application/json" -d @/tmp/n8n_workflow.json

Update a Workflow

Write the full updated workflow definition to /tmp/n8n_workflow.json:

curl -s -X PUT "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>" --header "X-N8N-API-KEY: $N8N_TOKEN" --header "Content-Type: application/json" -d @/tmp/n8n_workflow.json

Delete a Workflow

curl -s -X DELETE "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Get Workflow Tags

curl -s "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>/tags" --header "X-N8N-API-KEY: $N8N_TOKEN"

Update Workflow Tags

Write to /tmp/n8n_tags.json:

[
  { "id": "<tag-id>" }
]

curl -s -X PUT "${N8N_BASE_URL}/api/v1/workflows/<workflow-id>/tags" --header "X-N8N-API-KEY: $N8N_TOKEN" --header "Content-Type: application/json" -d @/tmp/n8n_tags.json

Executions

List Executions

curl -s "${N8N_BASE_URL}/api/v1/executions" --header "X-N8N-API-KEY: $N8N_TOKEN"

Filter by workflow or status:

curl -s "${N8N_BASE_URL}/api/v1/executions?workflowId=<workflow-id>&status=error&limit=20" --header "X-N8N-API-KEY: $N8N_TOKEN"

Available status values: error, success, running, waiting.

Include full execution data:

curl -s "${N8N_BASE_URL}/api/v1/executions?includeData=true&limit=5" --header "X-N8N-API-KEY: $N8N_TOKEN"

Get an Execution

curl -s "${N8N_BASE_URL}/api/v1/executions/<execution-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Retry a Failed Execution

curl -s -X POST "${N8N_BASE_URL}/api/v1/executions/<execution-id>/retry" --header "X-N8N-API-KEY: $N8N_TOKEN"

Stop a Running Execution

curl -s -X POST "${N8N_BASE_URL}/api/v1/executions/<execution-id>/stop" --header "X-N8N-API-KEY: $N8N_TOKEN"

Delete an Execution

curl -s -X DELETE "${N8N_BASE_URL}/api/v1/executions/<execution-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Credentials

List Credentials

curl -s "${N8N_BASE_URL}/api/v1/credentials" --header "X-N8N-API-KEY: $N8N_TOKEN"

Get a Credential

curl -s "${N8N_BASE_URL}/api/v1/credentials/<credential-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Get Credential Schema

Retrieve the required fields for a given credential type (e.g. githubApi, slackApi):

curl -s "${N8N_BASE_URL}/api/v1/credentials/schema/<credential-type-name>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Delete a Credential

curl -s -X DELETE "${N8N_BASE_URL}/api/v1/credentials/<credential-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Variables

List Variables

curl -s "${N8N_BASE_URL}/api/v1/variables" --header "X-N8N-API-KEY: $N8N_TOKEN"

Create a Variable

Write to /tmp/n8n_variable.json:

{
  "key": "<variable-name>",
  "value": "<variable-value>"
}

curl -s -X POST "${N8N_BASE_URL}/api/v1/variables" --header "X-N8N-API-KEY: $N8N_TOKEN" --header "Content-Type: application/json" -d @/tmp/n8n_variable.json

Delete a Variable

curl -s -X DELETE "${N8N_BASE_URL}/api/v1/variables/<variable-id>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Users (instance owner only)

List Users

curl -s "${N8N_BASE_URL}/api/v1/users" --header "X-N8N-API-KEY: $N8N_TOKEN"

Get a User

curl -s "${N8N_BASE_URL}/api/v1/users/<user-id-or-email>" --header "X-N8N-API-KEY: $N8N_TOKEN"

Security Audit

Generate a security audit report for the instance:

curl -s -X POST "${N8N_BASE_URL}/api/v1/audit" --header "X-N8N-API-KEY: $N8N_TOKEN"

Response Codes

Status	Description
`200`	Success
`201`	Created
`204`	Deleted successfully
`400`	Bad request / invalid body
`401`	Missing or invalid API key
`403`	Insufficient permissions
`404`	Resource not found

Guidelines

API availability — The REST API requires a paid n8n Cloud plan or a self-hosted instance. Free trial accounts return 401.
Pagination — List endpoints return up to 250 items. Use the cursor field from the response nextCursor to fetch subsequent pages.
Workflow updates are full replaces — PUT /workflows/{id} replaces the entire workflow definition. Always GET the workflow first, modify what you need, then PUT the full object.
Credential values are write-only — Credential data cannot be read back after creation for security reasons; you can only delete or update.
Owner-only operations — User management endpoints require the API key to belong to the instance owner.

API Reference

API overview: https://docs.n8n.io/api/
API reference: https://docs.n8n.io/api/api-reference/