A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The n8n API is how an app or AI agent works with an n8n instance: listing and creating workflows, activating and deactivating them, reading and retrying executions, and managing credentials, tags, users, and projects. Access is granted through an API key sent in a request header, and on Enterprise instances that key can be limited to specific scopes, so an agent reaches only the resources and actions those scopes allow. The same instance can also be driven through a first-party MCP server that an AI client connects to directly.
How an app or AI agent connects to n8n determines what it can reach. There are two routes, a REST API governed by an API key and a first-party MCP server, each limited by the key behind it and the scopes that key carries.
The Public REST API answers under a base path of /api/v1 on the instance's own host, such as a self-hosted address or a Cloud subdomain. It uses JSON over HTTPS and an API key in the X-N8N-API-KEY header.
n8n ships a first-party MCP server, built into every edition including Cloud, Enterprise, and the self-hosted Community Edition, that lets an AI client build, validate, and test workflows in the instance directly. It is in public preview and works best on n8n 2.18.4 or later.
An API key authenticates Public API calls through the X-N8N-API-KEY header. A key is created under Settings then n8n API with a label and an expiration. On Enterprise instances a key can be limited to specific scopes; on non-Enterprise instances a key has full access to the account.
An Enterprise option that supports OAuth 2.0 Token Exchange under RFC 8693, for delegated API access and embedding n8n in another application. It sits alongside the API key as a second way to authenticate.
The n8n Public API is split into areas an agent can act on, such as workflows, executions, credentials, users, and projects. Each area has its own methods and, on Enterprise instances, its own scope, and some reach far more than others.
List, read, create, update, and delete workflows, activate and deactivate them, and read or change the tags attached to a workflow.
List and read past workflow executions, delete an execution, retry a failed or stopped one, and stop running executions.
Create, update, and delete the credentials nodes use to reach external services, read a credential, and look up the data schema for a credential type.
List, read, create, update, and delete the tags used to organize workflows.
List and read users, create and delete users, and change a user's global role on the instance.
List, create, update, and delete the variables that store configuration values shared across workflows.
List, create, update, and delete the projects that group workflows and credentials for a team.
Pull the latest changes from the connected Git repository into the instance.
Generate a security audit of the instance across risk categories.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
WorkflowsList, read, create, update, and delete workflows, activate and deactivate them, and read or change the tags attached to a workflow.9 | ||||||
| GET | /workflows | Retrieve all workflows, with optional filtering by active status, tags, name, and project. | read | workflow:list | Current | |
On Enterprise instances a key needs the workflow:list scope. On non-Enterprise instances any valid key has full access. Acts onworkflow Permission (capability) workflow:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflows | Create a workflow. | write | workflow:create | Current | |
A created workflow can be assigned to a project with an optional projectId. Enterprise scope: workflow:create. Acts onworkflow Permission (capability) workflow:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflows/{id} | Retrieve a single workflow by id. | read | workflow:read | Current | |
Enterprise scope: workflow:read. Acts onworkflow Permission (capability) workflow:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /workflows/{id} | Update a workflow, replacing its nodes, connections, and settings. | write | workflow:update | Current | |
Enterprise scope: workflow:update. Acts onworkflow Permission (capability) workflow:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /workflows/{id} | Delete a workflow. | write | workflow:delete | Current | |
Enterprise scope: workflow:delete. Acts onworkflow Permission (capability) workflow:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflows/{id}/activate | Activate (publish) a workflow so its triggers run. | write | workflow:activate | Current | |
Activating puts a workflow live so its trigger nodes fire. Enterprise scope: workflow:activate. Acts onworkflow Permission (capability) workflow:activateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflows/{id}/deactivate | Deactivate a workflow so its triggers stop running. | write | workflow:deactivate | Current | |
Enterprise scope: workflow:deactivate. Acts onworkflow Permission (capability) workflow:deactivateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflows/{id}/tags | Get the tags attached to a workflow. | read | workflowTags:list | Current | |
Enterprise scope: workflowTags:list. Acts onworkflow Permission (capability) workflowTags:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /workflows/{id}/tags | Replace the tags attached to a workflow. | write | workflowTags:update | Current | |
Enterprise scope: workflowTags:update. Acts onworkflow Permission (capability) workflowTags:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ExecutionsList and read past workflow executions, delete an execution, retry a failed or stopped one, and stop running executions.5 | ||||||
| GET | /executions | Retrieve all executions, with optional filtering by status, workflow, and project. | read | execution:list | Current | |
Enterprise scope: execution:list. Acts onexecution Permission (capability) execution:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /executions/{id} | Retrieve a single execution, optionally including its run data. | read | execution:read | Current | |
Run data can hold the inputs and outputs each node passed. Enterprise scope: execution:read. Acts onexecution Permission (capability) execution:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /executions/{id} | Delete an execution. | write | execution:delete | Current | |
Enterprise scope: execution:delete. Acts onexecution Permission (capability) execution:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /executions/{id}/retry | Retry a failed or stopped execution. | write | execution:retry | Current | |
A retry re-runs the workflow, so side effects can happen again. Enterprise scope: execution:retry. Acts onexecution Permission (capability) execution:retryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /executions/stop | Stop one or more running executions. | write | execution:stop | Current | |
Enterprise scope: execution:stop. Acts onexecution Permission (capability) execution:stopVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CredentialsCreate, update, and delete the credentials nodes use to reach external services, read a credential, and look up the data schema for a credential type.5 | ||||||
| POST | /credentials | Create a credential that nodes of a given type can use. | write | credential:create | Current | |
A credential stores the secret a node uses to reach an external service. Enterprise scope: credential:create. Acts oncredential Permission (capability) credential:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /credentials/{id} | Get a credential by id. | read | credential:read | Current | |
The Public API does not return the decrypted secret data of a credential. Enterprise scope: credential:read. Acts oncredential Permission (capability) credential:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /credentials/{id} | Update a credential by id. | write | credential:update | Current | |
Enterprise scope: credential:update. Acts oncredential Permission (capability) credential:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /credentials/{id} | Delete a credential by id. | write | credential:delete | Current | |
Enterprise scope: credential:delete. Acts oncredential Permission (capability) credential:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /credentials/schema/{credentialTypeName} | Show the data schema for a credential type. | read | — | Current | |
This method requires no scope; it returns only the shape of the fields a credential type expects, not any secret. Enterprise scope: none. Acts oncredential Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList, read, create, update, and delete the tags used to organize workflows.5 | ||||||
| GET | /tags | Retrieve all tags. | read | tag:list | Current | |
Enterprise scope: tag:list. Acts ontag Permission (capability) tag:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tags | Create a tag. | write | tag:create | Current | |
Enterprise scope: tag:create. Acts ontag Permission (capability) tag:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /tags/{id} | Retrieve a single tag by id. | read | tag:read | Current | |
Enterprise scope: tag:read. Acts ontag Permission (capability) tag:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /tags/{id} | Update a tag. | write | tag:update | Current | |
Enterprise scope: tag:update. Acts ontag Permission (capability) tag:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /tags/{id} | Delete a tag. | write | tag:delete | Current | |
Enterprise scope: tag:delete. Acts ontag Permission (capability) tag:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList and read users, create and delete users, and change a user's global role on the instance.5 | ||||||
| GET | /users | Retrieve all users, with optional filtering by project and role. | read | user:list | Current | |
Restricted to the instance owner. Enterprise scope: user:list. Acts onuser Permission (capability) user:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users | Create one or more users by email, with optional roles. | write | user:create | Current | |
Restricted to the instance owner; the response includes an invite URL per user. Enterprise scope: user:create. Acts onuser Permission (capability) user:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{id} | Get a user by id or email. | read | user:read | Current | |
Restricted to the instance owner. Enterprise scope: user:read. Acts onuser Permission (capability) user:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /users/{id} | Delete a user by id or email. | write | user:delete | Current | |
Restricted to the instance owner. Enterprise scope: user:delete. Acts onuser Permission (capability) user:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /users/{id}/role | Change a user's global role on the instance. | write | user:changeRole | Current | |
The global role sets a person's instance-wide access. Enterprise scope: user:changeRole. Acts onuser Permission (capability) user:changeRoleVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VariablesList, create, update, and delete the variables that store configuration values shared across workflows.4 | ||||||
| GET | /variables | Retrieve all variables. | read | variable:list | Current | |
Enterprise scope: variable:list. Acts onvariable Permission (capability) variable:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /variables | Create a variable. | write | variable:create | Current | |
Variables are read by workflows across the instance. Enterprise scope: variable:create. Acts onvariable Permission (capability) variable:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /variables/{id} | Update a variable. | write | variable:update | Current | |
Enterprise scope: variable:update. Acts onvariable Permission (capability) variable:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /variables/{id} | Delete a variable. | write | variable:delete | Current | |
Enterprise scope: variable:delete. Acts onvariable Permission (capability) variable:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList, create, update, and delete the projects that group workflows and credentials for a team.4 | ||||||
| GET | /projects | Retrieve projects. | read | project:list | Current | |
Projects group a team's workflows and credentials, and are an Enterprise feature. Enterprise scope: project:list. Acts onproject Permission (capability) project:listVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /projects | Create a project. | write | project:create | Current | |
Enterprise scope: project:create. Acts onproject Permission (capability) project:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /projects/{projectId} | Update a project. | write | project:update | Current | |
Enterprise scope: project:update. Acts onproject Permission (capability) project:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /projects/{projectId} | Delete a project. | write | project:delete | Current | |
Enterprise scope: project:delete. Acts onproject Permission (capability) project:deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Source controlPull the latest changes from the connected Git repository into the instance.1 | ||||||
| POST | /source-control/pull | Pull changes from the connected Git repository into the instance. | write | sourceControl:pull | Current | |
A pull replaces local workflows and credentials with the repository's version, and is an Enterprise feature. Enterprise scope: sourceControl:pull. Acts onsource control Permission (capability) sourceControl:pullVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AuditGenerate a security audit of the instance across risk categories.1 | ||||||
| POST | /audit | Generate a security audit of the instance across risk categories. | read | securityAudit:generate | Current | |
The audit reads instance configuration to report risks such as outdated nodes and credential exposure. Enterprise scope: securityAudit:generate. Acts onaudit Permission (capability) securityAudit:generateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| Event | What it signals | Triggered by |
|---|
n8n limits how much an app or AI agent reads back at once through cursor pagination on its list endpoints. The Public API itself sets no request-rate ceiling on self-hosted instances by default, so the cap comes from the instance and its host.
The n8n Public API does not document a request-rate ceiling of its own, and a self-hosted instance sets none by default, so how fast an app or AI agent can call is bounded by the instance, its host, and any reverse proxy in front of it. n8n Cloud runs on n8n's managed infrastructure, which can apply its own platform limits. Self-hosted instances expose an interactive playground at the instance address under /api/v1/docs where a key can be tested against the live endpoints.
List endpoints use cursor pagination. A response that has more than one page returns a nextCursor value, which is passed back as the cursor query parameter to fetch the following page, rather than building a page number by hand. The limit parameter sets the page size, defaulting to 100 results, with a maximum of 250.
Requests and responses are JSON. There is no single documented payload size limit across the Public API; the practical ceiling is the instance and its host configuration. Execution responses can be large, so the run data of an execution is returned only when explicitly requested.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid, such as a missing required field in the body. | Correct the request body or parameters and resend. |
| 401 | Unauthorized | The API key is missing, invalid, or expired, or the X-N8N-API-KEY header was not sent. | Send a valid, unexpired API key in the X-N8N-API-KEY header. |
| 403 | Forbidden | The key is valid but not permitted for this call. On Enterprise instances the key lacks the required scope, or the method is restricted to the instance owner or admin. | Grant the missing scope, or use a key for the instance owner or admin where the method requires it. |
| 404 | Not Found | The resource does not exist, such as a workflow, execution, or credential id that is not on the instance. | Confirm the id and the path, then retry. |
| 429 | Too Many Requests | Too many requests were sent in a short window. A self-hosted instance sets no Public API rate ceiling by default, so this comes from the instance, its host, or a proxy in front of it. | Slow the request rate and retry after a short wait. |
| 500 | Internal Server Error | The instance hit an unexpected error while handling the request. | Retry after a short wait, and check the instance logs if it persists. |
n8n versions its Public API by a single path segment, v1, and ships dated changes to it through the product release notes rather than minting a new API version. The current version is v1.
The Public API has one version, v1, and every endpoint sits under a base path of /api/v1. New methods, scopes, and resources are added through dated product releases rather than by minting a new API version, so v1 has stayed stable while its surface has grown. The entries below are notable dated changes to that surface, newest first.
n8n's native MCP server, built into every edition, gained the ability to build and update workflows, letting an AI client create, validate, and test workflows in the instance directly. It is in public preview and works best on n8n 2.18.4 or later. Announced on 4 May 2026.
The n8n 2.17.0 release, on 13 April 2026, extended the Public API: workflow creation accepts an optional projectId to scope a new workflow to a project, and community-package operations require a key with the matching communityPackage scope.
The n8n 2.16.0 release, on 7 April 2026, added an insights:read API key scope for the insights summary endpoint, and introduced OAuth 2.0 Token Exchange under RFC 8693 as a second authentication mechanism for delegated and embedded access.
The n8n 1.112.0 release, on 15 September 2025, expanded the executions surface of the Public API with more detail in the list response and additional filtering and retry handling.
The n8n 1.96.0 release, on 2 June 2025, added Public API support for assigning users to projects and managing their project roles programmatically.
The v1 path has stayed stable while methods, scopes, and resources were added through versioned product releases.
n8n release notes ↗Bollard AI sits between a team's AI agents and n8n. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.