canonical: https://jentic.com/apis/n8n.io/n8n

# n8n Public API

n8n is an open-source workflow automation platform used to connect SaaS tools, internal services, and AI models into reusable pipelines. The n8n Public API exposes 40 endpoints for programmatic management of workflows, executions, credentials, users, projects, tags, variables, and source-control sync, so a self-hosted or n8n Cloud instance can be administered by code or by an AI agent. Authentication uses an X-N8N-API-KEY header issued in the n8n UI, scoped to the calling user's permissions.

## For AI agents

Create, activate, and run n8n workflows, manage credentials and users, trigger source-control pulls, and inspect executions across a self-hosted or n8n Cloud instance.

## Scope

Does not run third-party SaaS calls directly, host the workflow engine, or expose internal node debugging - use for managing workflows, executions, credentials, users, and projects on an existing n8n instance only.

## Capabilities

- Create, activate, and deactivate workflows on a self-hosted or cloud n8n instance
- Inspect and delete workflow executions for debugging and replay
- Provision and remove credentials used inside workflow nodes
- Manage users, including invitation, role assignment, and removal
- Trigger a source-control pull to sync workflow definitions from Git
- Manage projects, project memberships, tags, and workflow-level variables

## Use cases

### GitOps for Workflow Definitions

Treat workflow definitions as code by editing JSON files in a Git repository and triggering POST /source-control/pull to sync them into n8n. Combined with PATCH/PUT on /workflows, teams get pull-request review, rollback, and environment promotion for automation pipelines instead of editing in the UI directly. Removes the 'works on my n8n' problem common in shared automation teams.

Example prompt: After a merge to main, call POST /source-control/pull on the production n8n instance and confirm the response shows the latest commit hash.

### Workflow Lifecycle Automation

Activate, deactivate, transfer, and tag workflows programmatically as part of release management. POST /workflows/{id}/activate and /deactivate gate which automations are live, while PUT /workflows/{id}/transfer moves ownership between projects. Useful for blue/green automation deploys, scheduled maintenance windows, and emergency kill-switches on flapping workflows.

Example prompt: Deactivate workflow ID 142 with POST /workflows/{id}/deactivate when an alert fires that it has crossed the error-rate threshold.

### Execution Audit and Cleanup

Pull execution history with GET /executions, drill into individual runs with GET /executions/{id}, and remove old runs with DELETE /executions/{id} for storage management. Operations and SRE teams use this to feed dashboards, debug specific failures, and enforce retention. Also useful for compliance reviews where you need to demonstrate which runs touched a particular dataset.

Example prompt: List executions with GET /executions filtered by workflowId and status=error, then post a digest of the last 24 hours of failures to a monitoring channel.

### Multi-Tenant Project Administration

n8n's project model isolates workflows, credentials, and users per team. The /projects, /projects/{projectId}/users, and /workflows/{id}/transfer endpoints let admins onboard new teams, move workflows between projects, and set per-project membership. Saves manual ClickOps when scaling beyond a handful of users on a self-hosted instance.

Example prompt: Create a new project via POST /projects and add three users with POST /projects/{projectId}/users for the new analytics squad.

### AI Agent Workflow Orchestrator

Wire n8n into an AI agent through Jentic so the agent can list workflows, trigger source-control pulls, deactivate misbehaving automations, and answer questions like 'what failed last night?' without the developer wiring each call by hand. Through Jentic the X-N8N-API-KEY stays in the encrypted vault and the agent picks the right operation from the 40-endpoint surface via intent search.

Example prompt: On a Slack '/n8n status' command, search Jentic for 'list n8n workflows', execute GET /workflows, and reply with active counts and the last execution status per workflow.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /workflows | List workflows on the instance |
| POST | /workflows | Create a new workflow |
| POST | /workflows/{id}/activate | Activate a workflow |
| POST | /workflows/{id}/deactivate | Deactivate a workflow |
| GET | /executions | List execution history with filters |
| POST | /source-control/pull | Pull workflow definitions from connected Git remote |
| POST | /credentials | Create a credential for use in workflow nodes |
| POST | /audit | Generate an audit report |

## Key resources

- **Workflows** — Create, update, activate, deactivate, transfer, and tag workflow definitions
- **Executions** — List and delete execution runs for debugging and retention management
- **Credentials** — Provision and remove credentials referenced by workflow nodes
- **Users** — Invite, list, update role, and remove users
- **Projects** — Manage projects and per-project user memberships
- **Tags and Variables** — Manage workflow tags and instance-level variables
- **Source Control** — Trigger Git pulls to sync workflow definitions
- **Audit** — Generate audit reports for compliance and security review

## Why Jentic

- **Setup:** Wiring the n8n Public API by hand means holding its X-N8N-API-KEY, setting the header on every call against your own n8n instance domain and version path, and mapping the workflow, execution, and credential calls yourself. Through Jentic you install once, import the n8n Public API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** n8n puts the workflow id in the URL path (/workflows/{id}/activate, /workflows/{id}/deactivate), so a rule can pin your agent to one workflow. You choose the operations it may call, so state-changing ones like activating or deactivating a workflow are not included unless you add them.
- **Credential handling:** Your n8n X-N8N-API-KEY is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list n8n workflows' or 'pull workflows from Git', and Jentic returns the matching n8n operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Pipedream API** — Hosted workflow platform with a code-first model rather than n8n's node graph
- **Zapier NLA API** — Hosted no-code automation focused on AI-driven action selection
- **GitHub REST API** — Source of truth for workflow JSON when running n8n in GitOps mode

## FAQ

### What authentication does the n8n Public API use?

The n8n Public API uses an API key passed in the X-N8N-API-KEY header. Keys are issued from each user's profile in the n8n UI and inherit that user's permissions. Through Jentic, the X-N8N-API-KEY is held encrypted in the vault and injected at execution time so the raw key never reaches the agent's prompt.

### Can I activate and deactivate n8n workflows through the API?

Yes. POST /workflows/{id}/activate enables a workflow and POST /workflows/{id}/deactivate disables it. Pair these with PUT /workflows/{id} for definition updates and PUT /workflows/{id}/transfer to move ownership between projects.

### How do I sync n8n workflows from Git through the API?

Call POST /source-control/pull on an instance configured with the source-control feature. The endpoint pulls the latest workflow JSON from the connected Git remote so a CI job after a merge can promote workflows from staging to production without UI clicks.

### What rate limits apply to the n8n Public API?

Self-hosted n8n does not enforce a fixed rate limit; throughput depends on your instance's resources. n8n Cloud applies plan-specific limits - check your plan's quotas in the n8n Cloud dashboard. Build clients with exponential backoff on HTTP 429 responses regardless.

### Can I list and clean up n8n execution history through the API?

Yes. GET /executions returns the run history with filters for workflowId and status, GET /executions/{id} returns the full run, and DELETE /executions/{id} removes it. Most teams script a retention window with a daily DELETE pass against runs older than the threshold.

### How do I orchestrate n8n from an AI agent through Jentic?

Install the Jentic SDK with pip install jentic. Use SearchRequest with a query like 'list n8n workflows' or 'deactivate an n8n workflow' to find the right operation, LoadRequest for its schema, and ExecutionRequest to call it. Get an agent API key through Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the n8n Public API?

Yes. Because you run Jentic One yourself, your own rules decide which n8n operations and credentials the agent can use, so you can allow read-only calls like GET /workflows and GET /executions while withholding state-changing ones such as POST /workflows/{id}/activate or /deactivate unless you explicitly add them. Since n8n carries the workflow id in the URL path, a rule can also pin the agent to a single workflow. The X-N8N-API-KEY is stored once by your own instance and injected at execution time, so it never reaches the agent's prompt.