The Complete Guide to the n8n API

Disclosure: This post contains one or more links to providers we have a real, registered affiliate/referral relationship with. We may earn a commission at no extra cost to you if you sign up through them.

If you’re running n8n for workflow automation, sooner or later you’ll outgrow the visual editor. That’s where the n8n API comes in — it lets you create, update, trigger, and manage workflows programmatically, without touching the UI. This guide walks through everything you need to start using the n8n API in a real production setup, from authentication to Docker deployment.

n8n (short for “nodemation”) is an open-source, node-based workflow automation tool similar to Zapier or Make, but self-hostable and far more flexible for developers. Its REST API exposes nearly every capability available in the editor — workflows, credentials, executions, tags, and users — making it possible to build automation pipelines that manage themselves.

What Is the n8n API?

The n8n API is a REST interface built into every n8n instance (both cloud and self-hosted). It allows external systems to interact with your n8n instance programmatically: creating workflows from templates, activating or deactivating them, pulling execution logs, or triggering runs via webhook.

For DevOps teams, this is the difference between manually clicking around a UI and treating your automation layer as infrastructure-as-code. You can version-control workflow JSON, deploy it via CI/CD, and monitor executions the same way you’d monitor any other service.

REST API vs Webhook Triggers

n8n actually exposes two distinct ways to interact programmatically:

The REST API (/api/v1/...) — used for managing workflows, credentials, executions, and other administrative tasks. Requires an API key.

Webhook nodes — used to trigger a specific workflow’s execution from an external event (like a GitHub push or a form submission). No API key required unless you configure webhook authentication.

They solve different problems. The REST API is for managing the automation platform itself; webhooks are for feeding data into a specific workflow. Most production setups use both — REST API calls for deployment/CI, and webhooks for the actual event-driven automation.

Setting Up n8n for API Access

Before you can call the API, you need a running n8n instance with API access enabled. The cleanest way to do this — and the way most self-hosters run n8n in production — is via Docker.

Self-Hosting n8n with Docker

Here’s a minimal docker-compose.yml that gets n8n running with persistent storage:

version: "3.8"

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=n8n.yourdomain.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - NODE_ENV=production
      - WEBHOOK_URL=https://n8n.yourdomain.com/
      - GENERIC_TIMEZONE=UTC
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Bring it up with:

docker compose up -d

If you’re new to running multi-container stacks, our Docker Compose fundamentals guide covers the basics of services, volumes, and networking used here.

For production, don’t expose port 5678 directly to the internet — put n8n behind a reverse proxy (Nginx or Caddy) with TLS termination, or use a tunnel service. A small VPS is more than enough to run this; providers like DigitalOcean and Hetzner offer cheap droplets/instances that handle n8n comfortably at low traffic volumes.

Generating an API Key

Once n8n is running, generate an API key from the UI:

1. Log in to your n8n instance.
2. Go to Settings → API.
3. Click Create an API Key.
4. Copy the key — it’s shown only once.

You’ll pass this key in every request as the X-N8N-API-KEY header. Store it in a secrets manager or environment variable — never hardcode it in scripts committed to version control.

export N8N_API_KEY="your-api-key-here"
export N8N_HOST="https://n8n.yourdomain.com"

Working with the n8n REST API

With the API key in hand, you can start scripting against the instance. All endpoints live under /api/v1/. The full reference is in the official n8n API documentation, but here are the endpoints you’ll use most.

Creating and Managing Workflows via API

List all existing workflows:

curl -s -X GET "$N8N_HOST/api/v1/workflows" 
  -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" | jq

Create a new workflow from a JSON definition:

curl -s -X POST "$N8N_HOST/api/v1/workflows" 
  -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Daily Report Sync",
    "nodes": [],
    "connections": {},
    "settings": {}
  }'

Activate a workflow by ID:

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

This pattern — export workflow JSON from a dev instance, commit it to git, and POST it to production via CI — is how most teams keep n8n workflows in sync across environments without manual UI edits.

Triggering Workflows Programmatically

To actually run a workflow from external code, you generally use a Webhook node inside the workflow rather than the REST API directly. Set up a Webhook trigger node, then call it like a normal HTTP endpoint:

curl -s -X POST "$N8N_HOST/webhook/daily-report" 
  -H "Content-Type: application/json" 
  -d '{"report_date": "2026-07-05"}'

If you need to trigger an execution without a webhook (for example, testing), you can also use the executions endpoint on a manually-triggered workflow:

curl -s -X POST "$N8N_HOST/api/v1/workflows/123/execute" 
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Note: this endpoint’s availability depends on your n8n version — check the API reference for your specific release, since the execution API has changed across versions.

Authentication and Security Best Practices

The n8n API is powerful, which means a leaked key is a serious risk — anyone with it can read credentials metadata, modify workflows, or exfiltrate data. A few rules worth following:

Rotate API keys periodically, and immediately if you suspect a leak.

Never expose the n8n management UI or API directly to the public internet — put it behind a VPN, IP allowlist, or a proxy like Cloudflare Access.

Use separate API keys per integration/service so you can revoke one without breaking everything.

Enable basic auth or an additional reverse-proxy auth layer for the /rest and /api paths, in addition to the n8n API key.

Store API keys in a secrets manager (Vault, Doppler, or even Docker secrets) instead of .env files checked into git.

For teams running n8n as critical infrastructure — say, powering internal billing or customer notification workflows — treat the API key with the same care as a database password.

Deploying n8n in Production

A Docker Compose setup on a single VPS works fine for low-to-medium workloads, but if you’re running dozens of active workflows with high execution volume, consider:

Queue mode: n8n supports a Redis-backed queue mode that separates the webhook-receiving process from the execution workers, letting you scale workers independently.

External Postgres: swap the default SQLite database for Postgres to avoid write-lock contention under load.

Reverse proxy + TLS: terminate SSL with Caddy or Nginx, and consider Cloudflare in front of your VPS for DDoS protection and easy TLS certificate management.

Our production Docker deployment checklist covers volume backups, restart policies, and log rotation you’ll want in place before relying on n8n for anything business-critical.

Monitoring and Scaling n8n

Once workflows run unattended, you need visibility into failures. n8n emits execution data you can pull via the API (/api/v1/executions), but for real alerting, pair it with an uptime/monitoring service. BetterStack is a solid option for uptime checks on your n8n webhook endpoints and log aggregation for the underlying container, so you get paged the moment a critical automation silently stops firing.

A simple health check loop:

curl -s -X GET "$N8N_HOST/api/v1/executions?status=error&limit=10" 
  -H "X-N8N-API-KEY: $N8N_API_KEY" | jq '.data | length'

Run this on a cron schedule and alert if the error count spikes — it’s a cheap way to catch broken integrations before they cause downstream failures.

Recommended: Want to explore DigitalOcean yourself? DigitalOcean is a direct vendor link (not an affiliate/tracked link).

FAQ

Do I need a paid n8n plan to use the API?
No. The REST API is available on self-hosted (community edition, free) instances as well as n8n Cloud plans. Rate limits and some enterprise features (like advanced user management endpoints) differ between tiers, but core workflow/execution endpoints work on the free self-hosted version.

What’s the difference between the API key and OAuth credentials stored inside workflows?
The API key authenticates your scripts to the n8n instance itself. OAuth/credential entries inside workflows authenticate n8n to third-party services (Slack, Google, etc.) when a workflow runs. They’re unrelated and serve different purposes.

Can I import an entire workflow JSON file via the API?
Yes. POST the workflow’s JSON export to /api/v1/workflows, matching the schema n8n uses when you export via the UI (Download option). This is the standard way to move workflows between dev and production instances.

Is there a rate limit on the n8n API?
Self-hosted instances don’t impose an artificial rate limit by default, but your server’s resources are the practical limit. n8n Cloud plans do enforce request limits depending on your subscription tier.

How do I test webhook-triggered workflows without exposing my server publicly?
Use a tunnel tool like ngrok or Cloudflare Tunnel during development, then switch to your real domain once the workflow is verified and deployed to production.

Can the n8n API create credentials programmatically?
Yes, the /api/v1/credentials endpoint lets you create and manage credential entries, though sensitive fields (like OAuth tokens) still typically require a manual authorization step through the UI for security reasons.

Wrapping Up

The n8n API turns your automation platform from a UI-driven tool into something you can manage as code: version-controlled workflows, scripted deployments, and monitored executions. Start with a Docker-based self-hosted instance, generate an API key, and script the basics — listing, creating, and activating workflows — before moving into queue mode and production hardening. Once that’s in place, n8n stops being “another tool you click around in” and becomes a real piece of your infrastructure.