REST API

Relevant source files

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

• packages/cli/src/public-api/v1/openapi.yml
• packages/cli/src/controllers/workflows.controller.ts
• packages/cli/src/controllers/executions.controller.ts
• packages/@n8n/api-types/src/index.ts
• CLAUDE.md
• packages/testing/playwright/tests/ui/39-projects.spec.ts
• packages/frontend/editor-ui/src/utils/templates/samples/tutorial/api_fundamentals.json

The n8n REST API provides a programmatic interface for interacting with the n8n platform. It allows users to manage resources such as workflows, executions, credentials, and projects. The API is built on top of an Express server located in the packages/cli module and follows standard RESTful principles. It is the primary way for external systems and scripts to automate and integrate with n8n's core functionalities.

The API is formally defined using the OpenAPI 3.0 specification, which can be found in openapi.yml. This specification details all available endpoints, request/response schemas, and authentication methods. All communication between the n8n frontend and backend, as well as external API calls, relies on shared TypeScript interfaces defined in the packages/@n8n/api-types package to ensure type safety and consistency.

Sources: packages/cli/src/public-api/v1/openapi.yml, CLAUDE.md:21-22, 42, 65-66

Architecture and Authentication

The n8n REST API is served from the /api/v1 base path. The overall architecture follows a Controller-Service-Repository pattern, where incoming API requests are handled by controllers within the packages/cli directory.

Sources: packages/cli/src/public-api/v1/openapi.yml:12-13, CLAUDE.md:44

Authentication

Authentication is handled via an API key. Clients must provide their key in the X-N8N-API-KEY header with every request.

Sources: packages/cli/src/public-api/v1/openapi.yml:98-102

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-N8N-API-KEY

security:
  - ApiKeyAuth: []

Sources: packages/cli/src/public-api/v1/openapi.yml:98-105

Request Flow

The following diagram illustrates the general flow of an API request from a client to the n8n backend.

This diagram shows a typical request-response cycle for the n8n REST API.

Sources: packages/cli/src/public-api/v1/openapi.yml, CLAUDE.md:42-44

API Resources

The REST API is organized around a set of core resources. Each resource corresponds to a major entity within n8n.

Resource	Description
Workflow	Operations about workflows, including creation, activation, and management.
Execution	Operations about workflow executions, including retrieval and retrying.
Credential	Operations about credentials used in workflows.
Project	Operations about projects for organizing resources.
User	Operations about users.
Tags	Operations about tags for labeling workflows.
Variables	Operations about instance-level variables.
Audit	Operations about security audit logs.
SourceControl	Operations about source control integration.

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

Endpoints

The API provides a rich set of endpoints for CRUD (Create, Read, Update, Delete) operations and other actions on its resources.

Workflow Endpoints

These endpoints are used to manage workflows. The logic is handled by workflows.controller.ts.

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:55-66, packages/cli/src/controllers/workflows.controller.ts

Execution Endpoints

These endpoints manage workflow executions and are implemented in executions.controller.ts.

Method	Path	Description
GET	/executions	Retrieve 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:46-51, packages/cli/src/controllers/executions.controller.ts

Project Endpoints

Project endpoints allow for the management and organization of resources into distinct projects.

Method	Path	Description
GET	/projects	Retrieve a list of projects.
POST	/projects	Create a new project.
GET	/projects/{projectId}	Retrieve a specific project.
PUT	/projects/{projectId}	Update a specific project.
GET	/projects/{projectId}/users	List users in a project.

Sources: packages/cli/src/public-api/v1/openapi.yml:83-90

API Usage Example

The n8n test suite provides practical examples of how to interact with the API. The following snippet from a Playwright test demonstrates how to retrieve credentials for a specific project.

// Example of using API calls in a test
async function getCredentialsForProject(n8n: n8nPage, projectId?: string) {
	const params = new URLSearchParams({
		includeScopes: 'true',
		includeData: 'true',
		...(projectId && { filter: JSON.stringify({ projectId }) }),
	});
	return await n8n.api.get('/rest/credentials', params);
}

Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:8-16

Sequence Diagram: Creating a Project and Credential

This diagram shows the sequence of API calls involved in creating a new project and then adding a credential to it, as performed in the UI tests.

API Concepts in n8n Workflows

While the REST API is for managing n8n itself, n8n workflows frequently interact with external APIs using nodes like HTTP Request and Webhook. The "API fundamentals" tutorial workflow provides a conceptual model for understanding how APIs work, which is directly applicable to both using external APIs and understanding n8n's own API.

The tutorial uses a restaurant analogy:

• Client (HTTP Request node): The customer placing an order.
• Server (Webhook node): The kitchen that prepares the order.
• API (Menu & Waiter): The defined set of rules for communication.

This workflow demonstrates key REST concepts:

• GET /menu: Retrieving data (the menu).
• GET /order?extra_cheese=true: Using query parameters to filter or customize a request.
• POST /review: Sending data in a request body to create a new resource (a review).
• Headers (x-api-key): Sending metadata, such as authentication tokens.

Sources: packages/frontend/editor-ui/src/utils/templates/samples/tutorial/api_fundamentals.json

Summary

The n8n REST API is a comprehensive, OpenAPI-documented interface for programmatically managing all core aspects of the n8n platform. It is secured by API keys and organized into logical resources like workflows, executions, and projects. The API is essential for CI/CD, programmatic workflow management, and integration with external monitoring or management tools. Its design and usage are reflected in the project's architecture, from backend controllers to frontend data types and automated testing suites.

Sources: packages/cli/src/public-api/v1/openapi.yml, CLAUDE.md