Skip to main content

​
Introduction

n8n provides a comprehensive REST API that allows you to programmatically manage workflows, executions, credentials, and other resources. The API is designed to be intuitive and follows RESTful principles.

​
Base URL

The API is accessible at your n8n instance URL: 
https://your-n8n-instance.com/api/v1

​
API Versions

n8n currently supports:
  • Public API (v1): /api/v1/* - Designed for external integrations
  • Internal API: Used by the n8n frontend application
This documentation focuses on the Public API endpoints that are stable and recommended for external use.

​
Core Resources

The n8n API provides access to these core resources:

​
Workflows

Create, read, update, and delete workflows. Activate and deactivate workflow automation. 
POST   /api/v1/workflows          # Create workflow
GET    /api/v1/workflows          # List workflows
GET    /api/v1/workflows/:id      # Get workflow
PATCH  /api/v1/workflows/:id      # Update workflow
DELETE /api/v1/workflows/:id      # Delete workflow
Learn more about Workflows API →

​
Executions

Monitor workflow executions, check their status, and manage running workflows. 
GET    /api/v1/executions         # List executions
GET    /api/v1/executions/:id     # Get execution
POST   /api/v1/executions/:id/retry   # Retry execution
POST   /api/v1/executions/:id/stop    # Stop execution
Learn more about Executions API →

​
Credentials

Manage credentials used by workflow nodes for authentication. 
POST   /api/v1/credentials        # Create credential
GET    /api/v1/credentials        # List credentials
GET    /api/v1/credentials/:id    # Get credential
PATCH  /api/v1/credentials/:id    # Update credential
DELETE /api/v1/credentials/:id    # Delete credential
Learn more about Credentials API →

​
API Features

​
Pagination

List endpoints support cursor-based pagination: 
{
  "data": [...],
  "nextCursor": "eyJsYXN0SWQiOiIxMjM0NSIsImxpbWl0IjoxMDB9"
}
Use the nextCursor value in subsequent requests: 
GET /api/v1/workflows?cursor=eyJsYXN0SWQiOiIxMjM0NSIsImxpbWl0IjoxMDB9

​
Filtering

Many endpoints support filtering by various parameters: 
# Filter workflows by name
GET /api/v1/workflows?name=customer

# Filter by active status
GET /api/v1/workflows?active=true

# Filter by project
GET /api/v1/workflows?projectId=abc123

​
Response Format

All API responses use JSON format: 
{
  "id": "workflow123",
  "name": "My Workflow",
  "active": true,
  "nodes": [...],
  "connections": {...}
}

​
Error Handling

The API uses standard HTTP status codes:
Status CodeDescription
200Success
201Resource created
400Bad request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Resource not found
409Conflict - Resource state conflict
500Internal server error

​
Error Response Format

{
  "message": "Workflow with ID \"workflow123\" does not exist",
  "code": "NOT_FOUND"
}

​
Rate Limiting

n8n implements rate limiting to ensure fair usage:
  • IP-based limits: 1000 requests per 5 minutes
  • Key-based limits: Varies by endpoint and operation
Exceeding rate limits returns a 429 Too Many Requests status code.

​
Scopes and Permissions

API keys can have specific scopes that control access:
  • workflow:read - Read workflow data
  • workflow:create - Create new workflows
  • workflow:update - Update existing workflows
  • workflow:delete - Delete workflows
  • workflow:execute - Execute workflows
  • credential:read - Read credentials
  • credential:create - Create credentials
  • credential:update - Update credentials
  • credential:delete - Delete credentials
  • execution:read - Read execution data
  • execution:list - List executions
Learn more about API Authentication →

​
Getting Started

1

Generate an API Key

Navigate to Settings → API in your n8n instance and create a new API key with the required scopes.
2

Make Your First Request

Use the API key to authenticate your requests:
curl -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/workflows
3

Explore the API

Browse the documentation for specific endpoints and try different operations.

​
Best Practices

Only grant the minimum required scopes to your API keys. This follows the principle of least privilege and enhances security.
Always check HTTP status codes and handle errors appropriately in your application.
For transient errors (5xx), implement exponential backoff retry logic.
Cache workflow and credential data when appropriate to reduce API calls.
For real-time updates, consider using n8n’s webhook functionality instead of polling.

​
Next Steps

Authentication

Learn how to authenticate API requests

Workflows

Manage workflows via API

Executions

Monitor and control workflow executions

Credentials

Manage credentials programmatically