# n8n CLI REST API Endpoints: Complete Architecture and Reference Guide

> Explore n8n CLI REST API endpoints in this complete architecture and reference guide. Learn about workflows, executions, and projects exposed via Nest-style controllers in packages/cli/src.

- Repository: [n8n - Workflow Automation/n8n](https://github.com/n8n-io/n8n)
- Tags: api-reference
- Published: 2026-02-24

---

**The n8n CLI exposes a comprehensive REST API through Nest-style controllers organized under domain-specific base paths such as `/workflows`, `/executions`, and `/projects`, with every endpoint defined declaratively in `packages/cli/src/` using TypeScript method decorators.**

The n8n CLI functions as the server-side engine for the n8n workflow automation platform, implementing a decorator-based routing system that serves the public REST API. According to the n8n-io/n8n source code, controllers located in `packages/cli/src/` define all routes using `@RestController` base paths combined with HTTP method decorators, resulting in a predictable URL structure where the final endpoint equals the base path plus the method's specific path.

## REST API Architecture

The n8n CLI adopts a NestJS-inspired controller pattern where each domain logic group resides in a dedicated TypeScript file under `packages/cli/src/`. Controllers are decorated with `@RestController('<base-path>')` and individual handler methods use `@Get`, `@Post`, `@Patch`, `@Put`, or `@Delete` decorators. At runtime, the Express server registers these controllers under the root path `/`, constructing final URLs by concatenating the base path with the method-level path. There is no dynamic routing logic elsewhere in the codebase—all routes are defined declaratively in their respective controller files.

## Core API Endpoints by Domain

### Workflows (`/workflows`)

The `WorkflowsController` in [`packages/cli/src/workflows/workflows.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/workflows/workflows.controller.ts) manages workflow CRUD operations, activation states, sharing, and manual executions.

| Method | Path | Source Location |
|--------|------|-----------------|
| **POST** | `/` | `WorkflowsController.create` |
| **GET** | `/` | `WorkflowsController.getAll` |
| **GET** | `/new` | `WorkflowsController.getNewName` |
| **GET** | `/:workflowId` | `WorkflowsController.getWorkflow` |
| **GET** | `/:workflowId/exists` | `WorkflowsController.exists` |
| **PATCH** | `/:workflowId` | `WorkflowsController.update` |
| **DELETE** | `/:workflowId` | `WorkflowsController.delete` |
| **POST** | `/:workflowId/activate` | `WorkflowsController.activate` |
| **POST** | `/:workflowId/deactivate` | `WorkflowsController.deactivate` |
| **POST** | `/:workflowId/run` | `WorkflowsController.runManually` |
| **PUT** | `/:workflowId/share` | `WorkflowsController.share` |
| **PUT** | `/:workflowId/transfer` | `WorkflowsController.transfer` |
| **GET** | `/:workflowId/executions/last-successful` | `WorkflowsController.getLastSuccessfulExecution` |
| **POST** | `/with-node-types` | `WorkflowsController.getWorkflowsWithNodesIncluded` |

### Executions (`/executions`)

The `ExecutionsController` in [`packages/cli/src/executions/executions.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/executions/executions.controller.ts) handles execution history, pagination, and detail retrieval.

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/` (supports `Range` header) | `ExecutionsController.getAll` |
| **GET** | `/:id` | `ExecutionsController.getOne` |

### Projects and Folders (`/projects`)

Project management is handled by `ProjectController` in [`packages/cli/src/controllers/project.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/project.controller.ts), while folder operations reside in [`packages/cli/src/controllers/folder.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/folder.controller.ts).

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/` | `ProjectController.getAll` |
| **POST** | `/` | `ProjectController.create` |
| **GET** | `/:projectId` | `ProjectController.getOne` |
| **PATCH** | `/:projectId` | `ProjectController.update` |
| **DELETE** | `/:projectId` | `ProjectController.delete` |
| **GET** | `/my-projects` | `ProjectController.getMyProjects` |
| **GET** | `/personal` | `ProjectController.getPersonalProject` |
| **GET** | `/:projectId/folders` | `FolderController.getAll` |
| **POST** | `/:projectId/folders` | `FolderController.create` |
| **GET** | `/:projectId/folders/:folderId/tree` | `FolderController.getTree` |
| **GET** | `/:projectId/folders/:folderId/credentials` | `FolderController.getCredentials` |
| **GET** | `/:projectId/folders/:folderId/content` | `FolderController.getContent` |

### Credentials (`/credentials`)

Managed by `CredentialsController` in [`packages/cli/src/credentials/credentials.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/credentials/credentials.controller.ts).

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/` | `CredentialsController.getAll` |
| **GET** | `/for-workflow` | `CredentialsController.getForWorkflow` |
| **GET** | `/:credentialId` | `CredentialsController.getOne` |
| **POST** | `/` | `CredentialsController.create` |
| **PATCH** | `/:credentialId` | `CredentialsController.update` |
| **DELETE** | `/:credentialId` | `CredentialsController.delete` |

### Users (`/users`)

Defined in [`packages/cli/src/controllers/users.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/users.controller.ts).

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/` | `UsersController.getAll` |
| **GET** | `/:id/password-reset-link` | `UsersController.getPasswordResetLink` |
| **POST** | `/` | `UsersController.create` |
| **PATCH** | `/:id` | `UsersController.update` |
| **DELETE** | `/:id` | `UsersController.delete` |

### Tags (`/tags`)

Managed by `TagsController` in [`packages/cli/src/controllers/tags.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/tags.controller.ts).

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/` | `TagsController.getAll` |
| **POST** | `/` | `TagsController.create` |
| **PATCH** | `/:id` | `TagsController.update` |
| **DELETE** | `/:id` | `TagsController.delete` |

### Active Workflows (`/active-workflows`)

The `ActiveWorkflowsController` in [`packages/cli/src/controllers/active-workflows.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/active-workflows.controller.ts) lists currently running workflows.

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/` | `ActiveWorkflowsController.getAll` |
| **GET** | `/:workflowId` | `ActiveWorkflowsController.getOne` |

### Workflow Statistics (`/workflow-stats`)

The `WorkflowStatisticsController` in [`packages/cli/src/controllers/workflow-statistics.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/workflow-statistics.controller.ts) provides metrics endpoints.

| Method | Path | Source Location |
|--------|------|-----------------|
| **GET** | `/:id/counts/` | `WorkflowStatisticsController.getCounts` |
| **GET** | `/:id/times/` | `WorkflowStatisticsController.getTimes` |
| **GET** | `/:id/data-loaded/` | `WorkflowStatisticsController.getDataLoaded` |

### System and Enterprise Endpoints

Additional controllers handle authentication, licensing, telemetry, and enterprise features:

- **`/auth`** – Login and token resolution via `AuthController` ([`packages/cli/src/controllers/auth.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/auth.controller.ts))
- **`/api-keys`** – API key management via `ApiKeysController` ([`packages/cli/src/controllers/api-keys.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/api-keys.controller.ts))
- **`/license`** – License status via `LicenseController` ([`packages/cli/src/license/license.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/license/license.controller.ts))
- **`/me`** – Current user profile via `MeController` ([`packages/cli/src/controllers/me.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/me.controller.ts))
- **`/telemetry`** – RudderStack configuration via `TelemetryController`
- **`/insights`** – Workflow analytics via `InsightsController` ([`packages/cli/src/modules/insights/insights.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/insights/insights.controller.ts))
- **`/source-control`** – Git integration status via `SourceControlController` ([`packages/cli/src/modules/source-control.ee/source-control.controller.ee.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/source-control.ee/source-control.controller.ee.ts))
- **`/sso/saml`** – SAML metadata and ACS endpoints via `SAMLController`
- **`/sso/oidc`** – OIDC configuration via `OIDCController`
- **`/external-secrets`** – Secret provider management via `ExternalSecretsController`
- **`/ldap`** – LDAP synchronization via `LDAPController` ([`packages/cli/src/modules/ldap.ee/ldap.controller.ee.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/ldap.ee/ldap.controller.ee.ts))
- **`/mcp`** – MCP API-key retrieval via `MCPSettingsController` ([`packages/cli/src/modules/mcp/mcp.settings.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/modules/mcp/mcp.settings.controller.ts))

## Practical API Usage Examples

The following `curl` commands demonstrate common operations against the n8n CLI REST API. Replace `HOST` with your server URL (e.g., `http://localhost:5678`) and `TOKEN` with a valid bearer token.

List all workflows:

```bash
curl -H "Authorization: Bearer $TOKEN" \
     "$HOST/workflows?projectId=123"

```

Create a new workflow:

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "My New Workflow",
           "nodes": [],
           "connections": {}
         }' \
     "$HOST/workflows"

```

Activate a workflow:

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "versionId": "v1", "name": "Activated" }' \
     "$HOST/workflows/af3c7e5b-2f1a-4d3c-9d0e-9a7b3c5e9f01/activate"

```

Run a workflow manually:

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"workflowData": {"id":"af3c7e5b-2f1a-4d3c-9d0e-9a7b3c5e9f01"}}' \
     "$HOST/workflows/af3c7e5b-2f1a-4d3c-9d0e-9a7b3c5e9f01/run"

```

Retrieve execution history:

```bash
curl -H "Authorization: Bearer $TOKEN" \
     "$HOST/executions?limit=20&offset=0"

```

Get the last successful execution of a specific workflow:

```bash
curl -H "Authorization: Bearer $TOKEN" \
     "$HOST/workflows/af3c7e5b-2f1a-4d3c-9d0e-9a7b3c5e9f01/executions/last-successful"

```

Share a workflow with other projects:

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"shareWithIds":["project-2","project-3"]}' \
     "$HOST/workflows/af3c7e5b-2f1a-4d3c-9d0e-9a7b3c5e9f01/share"

```

List credentials usable for a workflow:

```bash
curl -H "Authorization: Bearer $TOKEN" \
     "$HOST/credentials/for-workflow?workflowId=af3c7e5b-2f1a-4d3c-9d0e-9a7b3c5e9f01"

```

## Summary

- The n8n CLI implements a **decorator-based routing architecture** using Nest-style controllers located in `packages/cli/src/`
- **Workflow endpoints** (`/workflows`) in [`workflows.controller.ts`](https://github.com/n8n-io/n8n/blob/main/workflows.controller.ts) support CRUD operations, activation, manual runs, sharing, and transfer between projects
- **Execution endpoints** (`/executions`) in [`executions.controller.ts`](https://github.com/n8n-io/n8n/blob/main/executions.controller.ts) provide pagination via range headers and detailed execution retrieval
- **Project and folder endpoints** (`/projects`) enable multi-tenant organization with folder hierarchies and credential scoping
- **System endpoints** cover authentication (`/auth`), licensing (`/license`), telemetry (`/telemetry`), and enterprise features including SSO, LDAP, and source control
- All endpoints return JSON payloads, use standard HTTP status codes, and require Bearer token authentication via the `Authorization` header

## Frequently Asked Questions

### What authentication method does the n8n CLI REST API use?

The n8n CLI REST API uses **Bearer token authentication**. Clients must include an `Authorization: Bearer <token>` header with every request. API keys can be generated and managed via the `/api-keys` endpoints defined in [`packages/cli/src/controllers/api-keys.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/api-keys.controller.ts), which support creating, listing, and deleting access tokens.

### How are the REST API routes defined in the n8n CLI source code?

Routes are defined **declaratively using TypeScript decorators** with no dynamic routing logic. Controllers use `@RestController('<base-path>')` to set their URL prefix (such as `/workflows` or `/executions`), while individual methods use `@Get`, `@Post`, `@Patch`, `@Put`, or `@Delete` decorators to map HTTP verbs to handler functions in files like [`packages/cli/src/workflows/workflows.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/workflows/workflows.controller.ts).

### Can I trigger workflow executions via the n8n CLI REST API?

Yes, the **POST `/:workflowId/run`** endpoint in `WorkflowsController` allows manual execution of workflows by sending a JSON payload containing `workflowData`. For production automation, workflows should be activated using **POST `/:workflowId/activate`** to enable trigger-based execution rather than manual triggering.

### Where can I find the source code for the workflow statistics endpoints?

The workflow statistics endpoints under `/workflow-stats` are implemented in [`packages/cli/src/controllers/workflow-statistics.controller.ts`](https://github.com/n8n-io/n8n/blob/main/packages/cli/src/controllers/workflow-statistics.controller.ts). This controller exposes three primary GET routes for retrieving execution counts (`getCounts`), timing metrics (`getTimes`), and data-loaded statistics (`getDataLoaded`) for any workflow ID passed as a path parameter.