REST API & Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/public-api/v1/openapi.yml
• AGENTS.md
• CONTRIBUTING.md
• packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json
• packages/nodes-base/nodes/Webhook/Webhook.node.json
• packages/nodes-base/nodes/HttpRequest/HttpRequest.node.json
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
• packages/testing/playwright/CONTRIBUTING.md
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/notification.ts

The n8n platform exposes a comprehensive REST API for programmatic management and interaction with its core components. This API is a fundamental part of the system, enabling automation of n8n itself and integration with external tools. The backend is a Node.js application using the Express framework, with the REST API and CLI commands housed within the packages/cli module.

The API system in n8n is twofold:

1. Management API: A structured, versioned API for managing resources like workflows, credentials, and executions.
2. Workflow-defined Endpoints: The ability for any workflow to create its own custom API endpoints using the Webhook node.

This document provides a technical overview of the n8n REST API architecture, key endpoints, and related concepts.

Sources: AGENTS.md:7, 32, CONTRIBUTING.md:17, packages/nodes-base/nodes/Webhook/Webhook.node.json

API Architecture

The n8n backend follows a Controller-Service-Repository pattern, which provides a clear separation of concerns for handling API requests.

• Controllers: Located in packages/cli, they are responsible for handling incoming HTTP requests, validating input, and routing them to the appropriate service.
• Services: Contain the core business logic for each resource.
• Repositories: Manage data access and persistence, abstracting the database interactions.

Sources: AGENTS.md:46, CONTRIBUTING.md:17

This diagram illustrates the request flow through the backend architecture.

Authentication

The public API uses API key-based authentication. Clients must provide a valid API key in the X-N8N-API-KEY header with every request.

# packages/cli/src/public-api/v1/openapi.yml:91-95
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-N8N-API-KEY

The "API fundamentals" tutorial workflow provides a practical example of this, using a header with the key x-api-key to authenticate a request to a secure endpoint.

Sources: packages/cli/src/public-api/v1/openapi.yml:91-99, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json:200-213

OpenAPI Specification

The v1 public API is formally defined using an OpenAPI 3.0 specification located at packages/cli/src/public-api/v1/openapi.yml. This file serves as the single source of truth for all available endpoints, their parameters, request bodies, responses, and security schemes.

The main openapi.yml file defines the server, tags, and security, and then references separate YAML files for each resource's path definitions.

# packages/cli/src/public-api/v1/openapi.yml:28-36
paths:
  /audit:
    $ref: './handlers/audit/spec/paths/audit.yml'
  /credentials:
    $ref: './handlers/credentials/spec/paths/credentials.yml'
  /credentials/{id}:
    $ref: './handlers/credentials/spec/paths/credentials.id.yml'
  /executions:
    $ref: './handlers/executions/spec/paths/executions.yml'
  /workflows:
    $ref: './handlers/workflows/spec/paths/workflows.yml'

Sources: packages/cli/src/public-api/v1/openapi.yml:1-36

Core API Resources

The management API is organized around core n8n resources. The primary resources are Workflows, Credentials, and Executions.

Sources: packages/cli/src/public-api/v1/openapi.yml:15-23

Workflows

The Workflow endpoints allow for creating, retrieving, updating, deleting, and managing workflows.

Method	Path	Description
GET	/workflows	Retrieve a list of workflows.
POST	/workflows	Create a new workflow.
GET	/workflows/{id}	Retrieve a specific workflow by its ID.
PUT	/workflows/{id}	Update a specific workflow.
DELETE	/workflows/{id}	Delete a specific workflow.
POST	/workflows/{id}/activate	Activate a workflow.
POST	/workflows/{id}/deactivate	Deactivate a workflow.

Sources: packages/cli/src/public-api/v1/openapi.yml:45-53

Credentials

The Credential endpoints manage the lifecycle of credentials used for authenticating with third-party services.

Method	Path	Description
GET	/credentials	Retrieve a list of credentials.
POST	/credentials	Create a new credential.
GET	/credentials/{id}	Retrieve a specific credential by its ID.
PUT	/credentials/{id}	Update a specific credential.
DELETE	/credentials/{id}	Delete a specific credential.

Sources: packages/cli/src/public-api/v1/openapi.yml:31-35

Executions

The Execution endpoints provide access to workflow execution history.

Method	Path	Description
GET	/executions	Retrieve a list of executions.
DELETE	/executions	Delete a list of executions.
GET	/executions/{id}	Retrieve a specific execution by its ID.
DELETE	/executions/{id}	Delete a specific execution.
POST	/executions/{id}/retry	Retry a failed execution.

Sources: packages/cli/src/public-api/v1/openapi.yml:37-41

Workflow-Defined Endpoints (Webhooks)

A powerful feature of n8n is the ability to create custom API endpoints directly from a workflow using the Webhook node. This node acts as a trigger, listening for incoming HTTP requests at a unique URL. This effectively turns an n8n workflow into a custom API backend.

The "API fundamentals" tutorial workflow is an excellent example of this. It uses multiple Webhook nodes to simulate a restaurant's API, with endpoints for /menu, /order, and /review.

Sources: packages/nodes-base/nodes/Webhook/Webhook.node.json, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json:20-31

The following diagram shows the sequence of an external client interacting with a workflow via a Webhook node.

The Webhook node can be configured to handle different HTTP methods (e.g., GET, POST), paths, and response modes. This allows for the creation of sophisticated, custom REST APIs without writing any server-side code outside of the n8n environment.

Sources: packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json:151-161, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/notification.ts:63-67

API Interaction Nodes

In addition to receiving API calls, n8n workflows can interact with other APIs using dedicated nodes.

HTTP Request Node

The HTTP Request node is the primary tool for making requests to external REST APIs. It supports various HTTP methods, authentication types, and allows for customization of headers, query parameters, and request bodies. It is frequently recommended for fetching data from APIs for analysis or enrichment.

Sources: packages/nodes-base/nodes/HttpRequest/HttpRequest.node.json, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts:58-68

GraphQL Node

For APIs that use GraphQL, the GraphQL node provides a specialized interface for making queries and mutations.

Sources: packages/nodes-base/nodes/GraphQL/GraphQL.node.json

API Testing

The project utilizes Playwright for E2E testing, which includes an API-driven testing layer. This involves API Services and ApiHelpers that interact directly with the n8n REST API to set up test states, create workflows, and verify outcomes, demonstrating the API's central role in programmatic control of the platform.

Sources: packages/testing/playwright/CONTRIBUTING.md:27-33

Summary

The n8n REST API provides a robust and dual-faceted interface for developers. The management API, defined by an OpenAPI specification, offers comprehensive control over core n8n resources. Simultaneously, the Webhook node empowers users to transform any workflow into a custom, serverless API endpoint. This dual approach makes n8n a highly extensible platform, capable of both managing its own state and creating new, automated web services.