REST API & Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The n8n REST API serves as the primary interface for programmatically interacting with the automation platform. It enables external systems to manage workflows, credentials, and executions through standardized HTTP requests. The API architecture is integrated into the backend core, utilizing a Controller-Service-Repository pattern to ensure decoupled logic and scalable endpoint management.
The API serves two distinct purposes: internal platform operations (facilitating the Vue.js frontend) and public-facing integrations. Developers can use the API to automate workflow deployment, retrieve execution history, and trigger active webhooks.
Sources: CONTRIBUTING.md, AGENTS.md, packages/cli/src/server.ts
Architecture and Core Components
The REST API is hosted within the packages/cli module, which contains the Express server and routing logic. The system follows a modular architecture where controllers handle incoming HTTP requests and delegate business logic to underlying services.
Request Lifecycle
When a request is made to an endpoint, it passes through several layers:
- Express Routing: Routes defined in
server.tsdirect traffic based on the URL path. - Controller Layer: Classes like
WorkflowsControllervalidate parameters and coordinate responses. - Service Layer: Encapsulates complex logic such as workflow validation or database operations.
- Data Access: TypeORM repositories interact with the database (SQLite or PostgreSQL).
The diagram shows the standard flow from a client request through the Express server to the data persistence layer.
Sources: AGENTS.md, packages/cli/src/server.ts, CONTRIBUTING.md
Public API (v1) Endpoints
The Public API is documented using an OpenAPI specification, providing structured access to n8n resources. These endpoints are designed for stability and external integration.
Workflow Management
The API allows for full CRUD operations on workflows. Users can retrieve lists of workflows, fetch specific definitions, and create new automation paths by providing a JSON schema.
| Endpoint | Method | Description |
|---|---|---|
/workflows | GET | List all workflows with pagination support |
/workflows/{id} | GET | Retrieve a specific workflow definition |
/workflows | POST | Create a new workflow from a JSON body |
/workflows/{id} | DELETE | Remove a workflow from the system |
Sources: packages/cli/src/public-api/v1/openapi.yml, packages/cli/src/controllers/workflows.controller.ts
Authentication and Security
The API utilizes specialized credentials for security. While standard nodes use internal credential management, the Public API typically requires an API Key passed in the headers.
- Header Name:
x-api-key - Security Principle: Security improvements must not degrade the building experience, ensuring that while endpoints are protected, they remain accessible for developer automation.
Sources: AGENTS.md, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json
Webhook Integrations
Webhooks are a specific subset of endpoints that act as triggers for workflows. Unlike standard REST endpoints that manage resources, webhooks receive data to initiate automated processes.
Webhook Lifecycle
Webhooks support multiple HTTP methods (GET, POST, PUT, DELETE) and can be configured with specific response modes such as lastNode or responseNode.
This sequence illustrates how an external system triggers a workflow via a POST request to a webhook endpoint and receives a response back once the workflow logic completes.
Sources: packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json, packages/cli/src/server.ts
Webhook Path Structure
Webhooks are typically exposed under specific paths:
- Test URL:
/webhook-test/{id}/{path}(Used during active development in the editor) - Production URL:
/webhook/{id}/{path}(Used when a workflow is active)
Data Structures and Models
The API frequently interacts with the WorkflowJSON structure, which defines the nodes, connections, and metadata of an automation.
Key Data Fields
| Field | Type | Description |
|---|---|---|
nodes | Array | A collection of node objects with types, positions, and parameters |
connections | Object | Map of connections between nodes, indexed by source node |
meta | Object | Metadata including template IDs and creation timestamps |
id | String | Unique identifier for the workflow resource |
Sources: AGENTS.md, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json
Error Handling and Validation
The API employs standardized error responses to assist developers in debugging. Controllers use specific error classes instead of generic application errors.
- UnexpectedError: Used for unhandled system failures.
- OperationalError: Used for expected runtime issues.
- UserError: Used for validation failures or incorrect request parameters.
The API validation logic ensures that incoming JSON for workflows adheres to the required schema before attempting persistence.
Sources: AGENTS.md, packages/cli/src/controllers/workflows.controller.ts
Conclusion
The REST API and its associated endpoints form the backbone of n8n's extensibility. By combining a structured Public API with dynamic Webhook triggers, the system allows for deep integration with third-party applications and robust internal lifecycle management. The use of a clear Controller-Service-Repository architecture ensures that as the API evolves, it maintains the balance between high performance and developer-friendly accessibility.