How to Use the n8n API (Keys, Endpoints, Pagination)

What the n8n API is for

n8n's public REST API lets you do from code most of what you do in the editor: list, create and update workflows, activate or deactivate them, read executions, and manage credentials, tags and users. It's useful for:

• deploying workflows from Git;
• backing up an instance;
• building dashboards on top of execution data.

This is not the same as calling a workflow through a Webhook node. A Webhook node gives one workflow its own URL. The API manages the n8n instance itself.

Which plans include it

n8n edition	API available?
Self-hosted (any edition)	Yes
n8n Cloud Starter, Pro, Enterprise	Yes
n8n Cloud free trial	No

Step 1: Create an API key

1. In n8n, open Settings > n8n API.
2. Select Create an API key.
3. Give it a label and choose an expiration.
4. On Enterprise plans you can also pick scopes, which limit what the key can do. Choose the fewest the job needs. On other plans, a key has full access to everything your account can do, so treat it like a password.
5. Copy the key. You won't be able to see it again.

To revoke a key, go back to Settings > n8n API, select Delete next to it, then Delete Forever.

Step 2: Find your base URL

Where n8n runs	Base URL
n8n Cloud	https://<name>.app.n8n.cloud/api/v1
Self-hosted	https://<your-instance-url>/api/v1

For a local Docker install, that's http://localhost:5678/api/v1. If you serve n8n under a sub-path, the path goes before /api.

Step 3: Make your first request

List your active workflows:

curl -X GET \
  'https://<your-instance-url>/api/v1/workflows?active=true' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'

The header name is exactly X-N8N-API-KEY. A wrong or missing key returns 401 Unauthorized.

Step 4: Page through results

List endpoints return results in pages:

• limit sets the page size: 100 by default, 250 at most.
• Each response has a nextCursor value. Pass it as cursor to get the next page.
• When nextCursor is null, you've reached the last page.

# first page
curl -H 'X-N8N-API-KEY: <your-api-key>' \
  'https://<your-instance-url>/api/v1/workflows?active=true&limit=150'

# next page: use the nextCursor value from the previous response
curl -H 'X-N8N-API-KEY: <your-api-key>' \
  'https://<your-instance-url>/api/v1/workflows?active=true&limit=150&cursor=<nextCursor>'

Responses have the shape { "data": [ ... ], "nextCursor": "..." }.

Avoid duplicates when retrying

For POST requests, n8n supports an Idempotency-Key header. Send the same key when you retry a request that may have timed out, and n8n won't create the item twice.

Try endpoints in the API playground

Self-hosted instances include an interactive API playground where you can try each endpoint with your key; see n8n's API docs. It isn't available on n8n Cloud. The full endpoint reference is generated from n8n's OpenAPI specification.

Common problems

• 401 Unauthorized. The header name is wrong, or the key has expired or been deleted. Create a new key.
• The API option is missing in Settings. You're on the n8n Cloud free trial; the API needs a paid Cloud plan or a self-hosted instance.
• Only part of the list came back. You got the first page. Follow nextCursor as shown above.