n8n API: Complete guide to the Public REST API, authentication, pagination, webhooks, and production architecture

The term “n8n API” can mean two different (but related) things: (A) the Public REST API that n8n provides to manage your n8n instance programmatically, and (B) using n8n to create API endpoints via the Webhook node (so other systems can call your workflow like an API). Most developers will use both: the Public REST API to automate administration and CI/CD, and Webhook-based endpoints to expose workflow-powered APIs.

The Public REST API is officially documented by n8n and is designed to expose common instance operations in a stable, supported way. The docs describe it as a way to “programmatically perform many of the same tasks as you can in the GUI.” See the API landing page: docs.n8n.io/api/. The same page notes feature availability: the n8n API isn’t available during the free trial and requires an upgrade to access.

If you are self-hosting n8n, you typically also see internal endpoints (often referenced as /rest) used by the web editor. Those internal endpoints can change more frequently and may require session/JWT behavior (depending on your configuration), so the recommended integration surface is the Public REST API when possible.

Developers sometimes expect “n8n API” to behave like a single endpoint they can call to “run automation.” In reality:

The most common “API product” pattern looks like this: You create a workflow that starts with a Webhook trigger, performs operations (calls external APIs, writes to DB, triggers other workflows), and then returns a clean response. This can replace a small custom backend for many tasks. The Webhook node supports test and production URLs and different response modes (immediate, last node finishes, or Respond to Webhook node). See: Webhook node docs.

The fastest way to verify your integration is correct is to: 1) create an API key in n8n, 2) call a “list workflows” endpoint with a filter (like active=true), 3) confirm you receive JSON, 4) store your key securely (server-side), and 5) add a basic retry/backoff strategy for transient failures.

# Replace:
# - N8N_HOST (e.g., https://your-n8n.example.com)
# - version number in /api/v
# - your API key value
curl -X 'GET' \
  'https://N8N_HOST/api/v1/workflows?active=true' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: YOUR_N8N_API_KEY'

import fetch from "node-fetch";

const host = process.env.N8N_HOST;              // e.g. https://your-n8n.example.com
const apiKey = process.env.N8N_API_KEY;         // keep server-side!
const url = `${host}/api/v1/workflows?active=true`;

const res = await fetch(url, {
  headers: {
    "accept": "application/json",
    "X-N8N-API-KEY": apiKey,
  }
});

if (!res.ok) throw new Error(`n8n error ${res.status}: ${await res.text()}`);
const data = await res.json();
console.log(JSON.stringify(data, null, 2));

import os, requests

host = os.environ["N8N_HOST"]      # e.g. https://your-n8n.example.com
key  = os.environ["N8N_API_KEY"]
url  = f"{host}/api/v1/workflows?active=true"

res = requests.get(url, headers={
  "accept": "application/json",
  "X-N8N-API-KEY": key
}, timeout=60)

res.raise_for_status()
print(res.json())

The Public REST API uses API keys. n8n’s documentation describes creating an API key in your n8n settings and then sending it in each request as a header named X-N8N-API-KEY. This is the recommended, stable way to authenticate to the Public REST API. See: docs.n8n.io/api/authentication/.

Practical security rules for API keys:

• Never ship an n8n API key to the browser. Always call n8n from your backend or from a secure server environment.
• Use least privilege and expiration where possible. Prefer shorter-lived keys and rotate keys on a schedule.
• Separate keys by environment. Use different keys for dev, staging, and production.
• Log safely. Don’t log the key. Redact headers in your logs and error reports.

If you run n8n behind additional auth (like basic auth or SSO at the reverse proxy), your Public API calls may need to pass that layer as well. This is not the same as the Public API key. In production, keep the layers simple: ideally, restrict network access to the API and rely on API keys for callers that need it.

For the Public REST API, the URL pattern is typically: https://<your-n8n-host>/api/v<version>/.... The authentication docs show an example URL for listing workflows using /api/v<version-number>/workflows. See: API authentication.

In practice, you should treat the API version as part of your integration contract. Hardcode it in a single configuration value in your app (for example, N8N_API_VERSION=1), so if your instance upgrades and the API version changes, you update one place. If you maintain multiple n8n instances (multi-tenant), store the base URL per tenant.

The Public REST API is meant to mirror many UI actions. While the exact endpoints and availability can depend on your edition and instance features, the API commonly covers resources such as:

For the authoritative endpoint list, always link your developers to the official API reference: API reference. This page is the proper source of truth for endpoint paths, required fields, and response shapes.

Workflows are the core object in n8n. Conceptually, a workflow is a directed graph of nodes: triggers (webhooks, cron schedules, app events), actions (HTTP requests, database writes, SaaS operations), transformations (Set node, Code node, expressions), and control flow (IF, Switch, Merge, Wait).

The Public REST API enables programmatic workflow operations that mirror what you can do in the UI. A typical workflow lifecycle looks like:

• Create workflow (initial JSON definition) or import from version control.
• Set environment-specific parameters (base URLs, API endpoints, IDs) using environment variables or workflow variables.
• Attach credentials (or reference shared credentials) for nodes that connect to services.
• Activate the workflow for production runs (especially for triggers like webhooks and cron).
• Monitor executions and adjust error handling, retries, and timeouts.

If you want predictable and safe deployments, treat workflow updates like software releases: keep workflow JSON in a repository, review changes, run a staging environment, then promote to production. If you do “click-ops” in the UI and “code-ops” in the API simultaneously, you can drift. Many teams solve this by making the repository the source of truth and using the API for deployment.

An execution is a single run of a workflow—either a manual run you started while testing or an automatic run in production. Executions are how you debug, audit, and measure reliability. n8n’s documentation explains that executions have manual and production behavior, and recommends keeping workflows inactive while developing and testing. See: Executions.

In practice, your production operations will rely on execution data for:

• Error triage: Which workflow failed? At what node? With what error message?
• Replay and recovery: Can you rerun the workflow safely without duplicating side effects?
• Compliance and audit: Who triggered the workflow? What records were changed?
• Performance: How long do executions take? Which nodes are slow?

A reliable system needs “idempotency thinking.” Many n8n workflows perform side effects (send emails, create tickets, charge payments). If a workflow fails halfway through, you might be tempted to rerun it—but reruns can cause duplication unless you add safe guards: store a dedupe key, check if the record already exists, or use an external system’s idempotency feature. This is true whether you trigger runs via webhook, schedule triggers, or the Public API.

n8n supports user management and governance features (especially important for teams and enterprises), including role-based access control (RBAC) and, in some setups, projects for grouping resources. These controls matter when: multiple people can edit workflows, credentials are shared, or your instance contains sensitive automations and secrets.

A good governance policy for production n8n looks like:

• Separate environments: dev / staging / prod instances, or at minimum separate credentials and tags per environment.
• Least privilege: only allow trusted users to create/edit workflows in production.
• Review gates: changes to critical workflows require peer review (especially those that move money or touch customer data).
• Audit trails: log who changed what, and when workflows were activated/deactivated.

n8n credentials store sensitive information that nodes use to authenticate to services: API keys, OAuth tokens, Basic Auth credentials, and other secrets. In workflows, you should treat credentials as “non-exportable secrets” and follow the principle of least privilege. Your workflows should reference credentials rather than embedding raw secrets in node parameters.

There are two common ways to connect to external APIs in n8n:

• Use a dedicated node (e.g., Slack, Google Sheets, HubSpot) that uses n8n credentials under the hood.
• Use the HTTP Request node for any REST/GraphQL API, with credentials set to API key, Bearer token, OAuth2, etc. See: HTTP Request credentials.

When you integrate the Public REST API into your own software, consider how you’ll manage credentials: In “automation as a feature” setups, you may have many customer-specific OAuth tokens. You can handle this with per-customer credentials, or by passing tokens as data and using them in HTTP headers. The safest approach depends on your threat model: storing tokens in n8n centralizes secrets, while passing tokens can reduce credential sprawl but increases risk of accidental logging if you’re not careful.

As your n8n instance grows, tags become one of the simplest and most effective operations tools. Tags let you label workflows (for example: prod, staging, payments, customer-sync, critical). n8n’s tags documentation notes that tags are global and available to all users on the instance, and shows how to add tags in the UI: Workflow tags.

In production, establish a naming convention + tag strategy early:

• Environment tags: env:dev, env:staging, env:prod
• Owner tags: team:ops, team:marketing, team:eng
• Risk tags: risk:payments, risk:pii, risk:external-webhook
• SLO tags: slo:critical vs slo:best-effort

With a consistent tag strategy, you can filter workflow lists in the UI and via API, build dashboards per tag, and respond to incidents faster because you can instantly find the workflows that matter.

Many n8n API endpoints that return lists use pagination. n8n’s Public REST API pagination docs state: the default page size is 100, you can change it, and the maximum permitted size is 250. When the response contains more than one page, it includes a cursor that you can use to request the next pages. See: API pagination.

# Example pattern (conceptual):
# 1) Request a page of active workflows with a limit
curl -X 'GET' \
  'https://N8N_HOST/api/v1/workflows?active=true&limit=150' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: YOUR_N8N_API_KEY'

# 2) If the response includes a cursor, request the next page using that cursor
# (Exact cursor parameter name and usage are documented in n8n's API pagination docs.)

Safe pagination pattern:
1) Always request with an explicit limit (<= 250).
2) Read the response cursor (if present).
3) Loop until cursor is empty or missing.
4) Add a maximum page count safeguard (to prevent infinite loops on bugs).
5) Cache results where reasonable (especially for admin dashboards).

In production, you should implement pagination defensively. A very common failure mode is “infinite pagination loops” caused by: forgetting to pass the cursor, accidentally reusing the first cursor, or treating cursor tokens as numeric offsets. Cursor tokens are opaque: store them as strings.

When people say “rate limits” in the n8n world, they may mean one of two things:

• Rate limits of external APIs you call from n8n workflows (e.g., OpenAI, Slack, HubSpot). n8n has best-practice guidance for handling third-party API rate limits and designing workflows to back off and retry. See: Handling API rate limits.
• Traffic management for your n8n webhooks/endpoints and your own infrastructure. If your webhook endpoint suddenly receives 1,000 requests per minute, your workflow may run concurrently and overload databases or hit external service quotas. In that case, you need queueing, batching, and concurrency controls.

For external API limits, the simplest approach is: detect 429 Too Many Requests, pause, and retry using the provider’s recommended window. For webhook intake, use gating: accept the webhook quickly, enqueue the work, and process at a sustainable pace. If you must respond synchronously, keep the synchronous work short and the response predictable.

A production-grade n8n integration needs two reliability layers: (1) API-call reliability for the Public REST API, and (2) workflow reliability for the workflows you expose via webhooks. Each layer needs clear error classification, bounded retries, and logging that is helpful without leaking secrets.

For the Public REST API, typical error classes are:

• 401 / 403: missing/invalid API key or insufficient permissions. Fix key, permissions, or upstream auth layer.
• 404: workflow or execution ID not found. Refresh cache or handle “already deleted” gracefully.
• 409: concurrency conflicts (if applicable). Retry carefully or re-fetch state before updating.
• 429: too many requests. Back off and reduce concurrency.
• 5xx: transient service issues. Retry with exponential backoff and jitter.

For webhook endpoints, error handling is more nuanced because you’re now acting as the server. You decide which status codes to return, what your response body looks like, and when the response is returned (immediately vs after last node finishes). The Webhook node supports multiple response modes. See the docs: Webhook node.

n8n’s Public REST API docs mention an API playground feature available for self-hosted n8n. The idea is to help developers explore endpoints, try requests, and understand response shapes. If your team is building deeper automation around n8n, enabling and using the playground can reduce integration time.

Even if you use the playground, treat it as a development tool: do not use a human interactive playground session for production automation. In production, use a server-side integration with safe key storage, retries, and auditing.

The Webhook node is one of n8n’s most powerful features for developers: it lets you create endpoints that external systems can call. The docs describe using the Webhook node as a trigger when you want to receive data and run a workflow based on that data, and it also supports returning data generated at the end of a workflow—making it useful for building an API endpoint. See: Webhook node docs.

Key Webhook node behavior:

• Test URL vs Production URL: The node provides two URLs, and you toggle which one is shown. Use the production URL for live traffic.
• Response modes: You can respond immediately, after the last node finishes, or using the “Respond to Webhook” node for full control.
• API-like workflows: Combine Webhook → validate input → call services → transform → return JSON response.

A clean “API endpoint workflow” includes these steps:

1. Input validation: verify required fields, types, and constraints. Return 400 with helpful messages for invalid input.
2. Authentication: check a shared secret, API key, signature, or require upstream auth at your reverse proxy.
3. Idempotency: for POST operations, dedupe repeated requests using an ID or hash.
4. Business logic: call external APIs, update data stores, and orchestrate processes.
5. Response shaping: return consistent JSON structures and status codes.

Example API contract built with n8n Webhook:
POST /webhook/orders
Body:
{
  "requestId": "ord_12345_2026-02-07T10:12:00Z",
  "customerId": "cus_001",
  "items": [{ "sku": "SKU123", "qty": 2 }]
}

Response (200):
{
  "ok": true,
  "orderId": "A-8891",
  "message": "Order accepted and processing started."
}

Webhook response modes (from n8n docs):
- Immediately: returns a simple response indicating the workflow started.
- When Last Node Finishes: returns output from the last node executed.
- Respond to Webhook node: you define status code + body explicitly.

Best practice:
- If client doesn't need final result, respond fast (202/200) and process async.
- If client needs result, keep workflow fast and deterministic; add timeouts.

n8n can be configured to run executions directly or via a queue. For higher-scale workloads—especially webhook APIs and heavy polling workflows—queue mode helps you isolate web frontends from execution workers and smooth load spikes. n8n documents execution-related environment variables and mentions execution modes (regular vs queue) for configuration. See: Executions environment variables.

A simple scaling architecture is:

• Web/Editor instance(s): serve the UI and accept webhook requests.
• Worker instance(s): execute workflows (more CPU/memory, autoscaled).
• Queue backend: holds pending executions and manages worker concurrency.
• Database: stores workflows, credentials metadata, executions logs.

Even in queue mode, you still need to design workflows for reliability: avoid long-running synchronous webhook responses, manage third-party rate limits, and keep retry logic bounded. Timeouts and execution limits should be configured so runaway workflows don’t overload your system.

n8n is powerful because workflows can call external services and run code nodes. That power also creates risk: if an attacker gains access to create or edit workflows, they may be able to access secrets or execute unintended actions. Your security posture depends heavily on how you host, who has editor access, and whether your instance is exposed publicly.

Practical hardening checklist for self-hosted n8n:

• Restrict editor access to trusted users only. Do not allow anonymous users to create/edit workflows.
• Network segment your instance: keep the editor/admin UI off the public internet if possible, or use a VPN/zero-trust gateway.
• Protect webhooks: add secrets/signatures and rate limits at the edge (reverse proxy/WAF).
• Rotate secrets (API keys, OAuth tokens) and monitor for unexpected access.
• Upgrade quickly when security patches are released.

If you’re building a product on top of n8n (or exposing webhook endpoints to the public internet), treat n8n as critical infrastructure: put it behind managed ingress, monitor it like a production service, and apply least privilege for both n8n users and the external services your workflows connect to.