n8n CLI REST API Endpoints: Complete Architecture and Reference Guide

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 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 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, while folder operations reside in 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.

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.

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.

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 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 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)
• /api-keys – API key management via ApiKeysController (packages/cli/src/controllers/api-keys.controller.ts)
• /license – License status via LicenseController (packages/cli/src/license/license.controller.ts)
• /me – Current user profile via MeController (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)
• /source-control – Git integration status via SourceControlController (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)
• /mcp – MCP API-key retrieval via MCPSettingsController (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:

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

Create a new workflow:

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

Activate a workflow:

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:

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:

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

Get the last successful execution of a specific workflow:

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

Share a workflow with other projects:

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:

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 support CRUD operations, activation, manual runs, sharing, and transfer between projects
• Execution endpoints (/executions) in 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, 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.

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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}