The n8n REST API: managing your instance and workflows programmatically

The n8n interface is fine as long as you manage five workflows by hand. But once the instance grows — dozens of workflows, several environments, a team deploying regularly — clicking through the editor to administer everything becomes a bottleneck. That's exactly what n8n's public REST API is for: everything you do in the administration interface (list, activate, export, monitor), you can do programmatically, from a script, a CI/CD pipeline… or from another n8n workflow.

Creating an API key: Settings → n8n API

The public API authenticates with a key, generated in Settings → n8n API via the Create an API key button. Two things to know right away:

• The key is shown only once. Copy it immediately into a secrets manager or an environment variable — if you lose it, you'll have to generate a new one.
• It inherits the rights of the account that creates it. On most self-hosted instances, that amounts to broad administrative rights over workflows, executions and credentials.

Every API request then carries the key in the dedicated X-N8N-API-KEY header:

curl -s "https://n8n.example.com/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Note the $N8N_API_KEY: the key lives in an environment variable, never hardcoded in the script. Our n8n environment variables guide covers the good practices for handling this kind of secret cleanly, both on the instance side and in your scripts.

The main endpoints

The API is versioned under the /api/v1 prefix and follows classic REST logic: resources (workflows, executions, credentials), HTTP verbs (GET to read, POST to create, DELETE to remove), JSON responses. That's no accident: this architectural style was formalized by Roy Fielding and Richard Taylor in "Principled Design of the Modern Web Architecture" (ACM Transactions on Internet Technology, 2002 — see on Google Scholar), the foundational paper behind virtually every modern web API, n8n's included. In practice, it means any developer who has ever consumed a REST API feels at home immediately.

The three resource families that cover most needs:

• /api/v1/workflows — list the instance's workflows, fetch a workflow's complete JSON definition (its nodes, connections, parameters), create, update or delete workflows, and above all activate or deactivate them via dedicated sub-routes.
• /api/v1/executions — browse execution history, with filters (notably by status and by workflow) that make it easy to isolate recent failures.
• /api/v1/credentials — create and delete credentials programmatically. Important point: by design, the API does not return decrypted secrets — you can provision a credential, but not read its contents back.

Other resources exist depending on your n8n version and edition (tags, users, variables…), but these three are enough to industrialize the majority of everyday operations.

Use case #1: activating or deactivating workflows in bulk

A classic scenario: database maintenance is scheduled, and you want to cleanly switch off the instance's thirty scheduled workflows rather than let them fail in a loop. By hand, that's thirty round trips through the interface. Through the API, it's a loop:

# List active workflows, then deactivate each one
curl -s "https://n8n.example.com/api/v1/workflows?active=true" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  | jq -r '.data[].id' \
  | while read id; do
      curl -s -X POST "https://n8n.example.com/api/v1/workflows/$id/deactivate" \
        -H "X-N8N-API-KEY: $N8N_API_KEY"
    done

The same pattern in reverse reactivates everything after the maintenance window. It's also the building block of a "kill switch": a script that shuts down every workflow carrying a given tag when a third-party API has an incident.

Use case #2: exporting all workflows for backup

The workflows endpoint returns the complete JSON definition of each workflow — exactly what the manual export from the editor produces. A script of a few lines can therefore fetch every workflow each night and write them into a folder, one file per workflow. Combined with an automatic git commit, you get a versioned history of the whole instance without any manual action.

It's the natural complement to the approach described in our guide on backing up and versioning workflows with Git: Git provides the history and traceability, the API provides the automated collection. One caveat: credentials are not included in the exports (and rightly so) — backing up secrets follows a separate path, detailed in our article on securing credentials.

Use case #3: monitoring failures from an external tool

The executions endpoint, filtered on the "error" status, turns n8n into a metrics source for your existing supervision tooling. A script called every five minutes by your monitoring system counts recent failed executions and raises an alert past a threshold:

curl -s "https://n8n.example.com/api/v1/executions?status=error&limit=20" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

The advantage over an internal Error Workflow: the monitoring lives outside the instance. If n8n itself has gone down, the API call fails and your monitoring tool sees it — whereas an Error Workflow hosted on the sick instance will never warn anyone. The two approaches complement each other, as detailed in our guide on monitoring an n8n instance.

Use case #4: deploying a workflow from dev to prod

With two instances (one for development, one for production), the API enables scriptable deployment: fetch the workflow's JSON definition from the dev instance, adjust what needs adjusting (credential identifiers, URLs), then push it to the prod instance — creating the workflow if it doesn't exist yet, updating it otherwise — before activating it. Integrated into a CI/CD pipeline, this script turns workflow deployment into a reproducible process, triggered by a merge rather than a manual copy-paste between two browser tabs. Setting up that two-instance architecture is covered in our guide on dev and prod environments for n8n.

Use case #5: driving n8n… from n8n

Nothing prevents an n8n workflow from calling its own instance's API with an HTTP Request node. It's actually a surprisingly useful pattern: a nightly workflow that exports all the other workflows to external storage, a "housekeeping" workflow that deactivates workflows unused for 90 days after sending a notification, or an internal dashboard that aggregates execution statuses. Create a Header Auth credential carrying the X-N8N-API-KEY header (rather than pasting the key into the node), point the HTTP Request node at http://localhost:5678/api/v1/... if the workflow runs on the same machine, and the instance becomes able to administer itself.

Public API vs. webhooks: two doors, two privilege levels

The confusion is common among beginners: "I already have webhooks, why an API?" Because the two have neither the same role nor the same reach:

• A webhook triggers one specific workflow. Its scope is limited to what that workflow does, its authentication is configured node by node, and it's designed to be exposed to third-party systems (see our complete n8n webhooks guide).
• The public API administers the whole instance: any workflow can be read, modified, deleted or deactivated, credentials manipulated, history browsed.

Plainly put: handing a webhook URL to a partner is routine; handing over an API key is handing over the keys to the engine room. That calls for strict hygiene: key stored in an environment variable, never in a Git repository or in a node's parameters; network access to the instance restricted as much as possible (reverse proxy with an IP allowlist, VPN, or at the very least mandatory HTTPS); key rotation when a team member leaves; and one dedicated key per use (one for backup, one for monitoring) so you can revoke with precision.

Common pitfalls

• Hardcoding the API key in a script or a workflow. It ends up in Git, in logs or in a shared export. An environment variable on the script side, a Header Auth credential on the n8n side: never anything else.
• Forgetting pagination. The workflows endpoint, like the executions endpoint, returns results in pages, with a cursor to request the next batch. An export script that ignores pagination silently backs up a fraction of the instance and gives a false sense of safety.
• Confusing triggering with administering. Using the API key to trigger a business process that a plain webhook would have covered means exposing administrative privileges where a narrow door would have sufficed.
• Pushing a dev workflow to prod without adjusting references. Credential identifiers differ from one instance to the other: an API deployment that doesn't remap them produces an active workflow… wired to the wrong accounts, or to nothing at all.
• Treating the API response as stable across versions. The overall schema changes little, but exact fields can evolve with n8n releases: a robust script checks for the presence of the fields it consumes instead of assuming them.

Going further

The public API is the building block that takes an n8n instance from personal tool to team infrastructure: automated backups, reproducible deployments, external supervision. The logical next step is traceability of what actually runs: the Compliance & Audit Pack (€149) provides ready-to-use workflows to log and trace what happens inside your automations once the instance is industrialized — the audit trail that naturally completes API-driven management. And if your instance isn't self-hosted yet, start with our guide on installing n8n with Docker: it's the foundation everything else rests on.