The n8n API: What It Does and How to Use It
By Rick Kennerknecht, NoCode Guide
November 17, 2026

Last verified: October 2026
The n8n API is a public REST API built into every n8n instance. You create a key under Settings, send it in an X-N8N-API-KEY header, and you can list, create, activate and delete workflows, read executions, and manage credentials and tags. It is the tool for backups, deployments and monitoring, not for calling other services from inside a workflow.
That last sentence is the one most people get wrong, so it gets its own section below. First, the shape of the thing.
What the n8n API actually is
Every n8n instance, Cloud or self-hosted, exposes an HTTP API at /api/v1 on the same address you use for the editor. On Cloud that is https://your-name.app.n8n.cloud/api/v1. On a self-hosted box it is your domain plus /api/v1, or host:port/path/api/v1 if you run behind a path prefix.
The n8n docs describe it as a way to "perform many of the same tasks you can do in the n8n GUI" programmatically. That is a fair description. Anything you would do by clicking around the Workflows list, the Executions list, the Credentials page or the tag picker, you can do with a request instead. What you cannot do through it is run the business logic of a workflow step by step; for that, you build a workflow and trigger it.
Availability matters before you plan around it. The n8n API overview lists it as available on Cloud Starter, Pro and Enterprise, and on every self-hosted edition, including the free Community Edition. It is not available during the Cloud free trial. If you are evaluating n8n on a trial and want to test API-driven deployment, spin up a local Docker instance alongside it; the API behaves the same.
n8n REST API vs the HTTP Request node vs webhooks
Three things in n8n involve HTTP and get mixed up constantly. They point in different directions.
| Mechanism | Direction | What it is for | Example |
|---|---|---|---|
| n8n public API | Outside world calls n8n, about n8n | Managing the instance: workflows, executions, credentials, tags, users | A CI job that pushes a workflow JSON file from git into production |
| HTTP Request node | A workflow calls the outside world | Fetching or posting data to any third-party API as a step in a workflow | A node that pulls today's orders from Shopify |
| Webhook node | Outside world calls n8n, to run a workflow | Starting a workflow when something happens elsewhere | Stripe posts a payment event and the workflow sends a receipt |
So: if you want a workflow to run when something happens, you want a webhook trigger. If you want a workflow to talk to another service, you want the HTTP Request node. The public API is only the right tool when the subject of the request is n8n itself.
One wrinkle: there is also an n8n node you can drop inside a workflow. It wraps the public API, so a workflow can manage other workflows. That is how people build things like "deactivate every workflow tagged staging at midnight" without leaving n8n. It still needs an API key, which brings us to the part everyone has to do first.
Creating an n8n API key
The process is the same on Cloud and self-hosted, and it is documented on the API authentication page.
- Log in and open Settings, then n8n API.
- Click Create an API key.
- Give it a label that says what will use it (github-deploy, backup-cron). Future you will thank present you.
- Set an expiration. Pick one. A key with no expiry is a key you will forget exists.
- On Enterprise plans, choose scopes. On every other plan there are no scopes: the docs state that non-Enterprise keys "have full access to all the account's resources and capabilities."
- Copy the key from My API Key. Store it in a secrets manager or a
.envfile that is not in git.
That point about scopes deserves a second look. On a Starter, Pro, Business or Community instance, an API key is a master key. It can read every credential's metadata, export every workflow, and delete all of them. Treat it like the owner password, because functionally that is what it is. If you hand a key to a contractor for one project, you have handed them the whole instance. The honest workaround on non-Enterprise plans is separate n8n instances per trust boundary, which is one of the quieter arguments in the Cloud vs self-hosted decision.
What the n8n public API covers
The endpoint reference is generated from n8n's OpenAPI spec and groups endpoints by resource. As of October 2026 the groups are Workflow, Execution, Credential, User, Audit, Tags, Source Control, Variables, Data Table and Projects, with a note that there are more.
In practice four groups carry almost all the traffic:
- Workflows. List, get, create, update, delete, archive, activate, deactivate. Creating one requires
name,nodes,connectionsandsettingsin the body. The get endpoint returns the full workflow JSON, nodes and connections included, which is what makes backups and deployments possible. - Executions. List and filter by workflow and status, fetch one with its data, delete. This is your monitoring feed.
- Credentials. List, get, create, update, delete and test. You can create a credential by posting its fields, which lets a deployment script provision a fresh instance. The list and get responses state plainly that "credential data (secrets) is not included", so you cannot read secret values back out, and you should be glad about that.
- Tags. Create, rename, delete and attach to workflows. Tags are how you select groups of workflows in scripts.
Pagination is cursor-based. Default page size is 100, maximum 250. The response is an object with a data array and a nextCursor string; pass that string back as cursor to get the next page. If your script only ever reads the first page, you have a bug waiting for your 101st workflow.
A first n8n API call with curl
Replace the host and the key. This lists only active workflows and asks for JSON back.
export N8N_HOST="https://n8n.example.com"
export N8N_API_KEY="paste-your-key-here"
curl -s "$N8N_HOST/api/v1/workflows?active=true" \
-H "X-N8N-API-KEY: $N8N_API_KEY" \
-H "accept: application/json" | jq '.data[] | {id, name, active}'
If you get a 401, the header name is wrong or the key expired. If you get HTML back instead of JSON, you hit the editor URL rather than /api/v1, usually because of a reverse proxy rule that rewrites paths. If it hangs, your proxy is not forwarding to port 5678; the self-hosting guide covers the usual proxy setups.
Three jobs the n8n API is good for
Nightly backups of every workflow
n8n stores workflows in its database. If that database is SQLite on a single VPS and the disk dies, so do the workflows. A cron job that pulls every workflow as JSON into a git repository is cheap insurance and gives you history for free.
#!/usr/bin/env bash
set -euo pipefail
mkdir -p backup
cursor=""
while :; do
page=$(curl -s "$N8N_HOST/api/v1/workflows?limit=250&cursor=$cursor" \
-H "X-N8N-API-KEY: $N8N_API_KEY")
echo "$page" | jq -c '.data[]' | while read -r wf; do
id=$(echo "$wf" | jq -r '.id')
echo "$wf" | jq '.' > "backup/$id.json"
done
cursor=$(echo "$page" | jq -r '.nextCursor // empty')
[ -z "$cursor" ] && break
done
cd backup && git add . && git commit -qm "n8n backup $(date -u +%F)" || true
Run it before every update as well as nightly. The update guide explains why I treat a pre-update export as non-negotiable even though n8n does not require it.
Deploying workflows from git
The reverse direction: keep workflow JSON in a repository, review changes in pull requests, and have a pipeline push merged files to the production instance with a create-or-update call. Two cautions. Credentials never travel inside workflow JSON, so the credential IDs referenced by nodes must already exist on the target instance with matching names. And a workflow created through the API arrives inactive, exactly as one created in the editor does; activate it afterwards, or you will deploy a change that silently does nothing. If you want to understand what is inside the JSON you are shipping, the anatomy of an n8n workflow walks through nodes, connections and settings.
Monitoring executions from outside n8n
n8n has no built-in failure dashboard. The error-workflow pattern in n8n error handling catches failures as they happen; the Executions endpoint lets you also ask "how many errors in the last hour, per workflow" from an external monitor like Uptime Kuma, Grafana or a plain cron script. Filter by status=error, count the results, alert over a threshold. It is also the only way to get execution counts out of Cloud in a form you can chart, which matters once you are watching your monthly cap on the Starter or Pro plan.
Limits and gotchas
- Not on the Cloud trial. Covered above, but it surprises people on day one.
- No scopes below Enterprise. One key, full access. Rotate it when anyone who had it leaves.
- Execution data can be large. Fetching an execution with its data returns every item that flowed through every node. On a workflow that processed 10,000 rows, that is one very big JSON document. Use the list endpoint for status and only fetch the full execution when you need the payload.
- Rate limits are yours to impose. A self-hosted instance has nothing between your script and the database. A tight loop over the executions endpoint will slow the editor for everyone. Add a sleep.
- Versioned path, moving target. The path says
v1, but new resources such as Data Table and Projects arrive under that same prefix as n8n evolves, so pin your n8n version in Docker and read release notes when you update.
The n8n CLI and the API node
Two wrappers sit on top of the same endpoints. The n8n CLI wraps the public API for terminal and CI use, so if you would rather type a command than write curl, that exists. The n8n node inside the editor does the same from within a workflow. Both need the same key, both have the same reach, and both are subject to the same "full access" caveat. Pick whichever matches where the automation lives: shell scripts get the CLI, scheduled housekeeping inside n8n gets the node, and everything else gets plain HTTP, which is the version that will still work in five years.
Frequently asked questions
Yes on self-hosted n8n, including the free Community Edition, and on Cloud Starter, Pro and Enterprise plans. The only place it is switched off is the Cloud free trial.
Open Settings, then n8n API, and click Create an API key. Copy the key from My API Key straight away and store it somewhere safe, such as a secrets manager or an untracked .env file.
Your instance address followed by /api/v1. On Cloud that is https://your-name.app.n8n.cloud/api/v1; on self-hosted it is your domain plus /api/v1.
Not directly. The public API manages workflows, executions, credentials and tags; it does not run a workflow on demand. To start a workflow from outside, use a Webhook trigger node and call its URL.
Only on Enterprise plans, which support scopes. On Starter, Pro, Business and Community Edition, every API key has full access to everything the account can do, so treat it like the owner password.
No. You can create and delete credentials through the API, but secret values are never readable back out. Deployments must recreate credentials on the target instance rather than copy them.
Related guides
Updating n8n takes about five minutes: back up your data folder, pull the new Docker image, and rest
Last verified: August 2026 n8n error handling works in three layers: Retry On Fail on the node, On E
Last verified: August 2026 The fastest way to learn n8n is to import a working workflow and take it
