# N8n Core Api

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-n8n-claude-skill-package-n8n-core-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/n8n-Claude-Skill-Package/tree/main/skills/source/n8n-core/n8n-core-api

## Install

```sh
agentstack add skill-impertio-studio-n8n-claude-skill-package-n8n-core-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# n8n-core-api

## Quick Reference

### API Fundamentals

| Aspect | Value |
|--------|-------|
| Base URL | `://api/v1/` |
| Authentication | `X-N8N-API-KEY` header |
| Content-Type | `application/json` |
| Pagination | Cursor-based (`nextCursor` field) |
| Max page size | 250 results |
| Default page size | 100 results |
| API Playground | `/api/v1/docs` (Scalar UI) |
| Availability | Requires a paid plan (not available during free trial) |

### Resource Endpoints Overview

| Resource | CRUD | Special Operations |
|----------|------|--------------------|
| Workflows | GET, POST, PUT, DELETE | activate, deactivate, transfer, tags, versions |
| Executions | GET, DELETE | retry, stop, stop-bulk, tags |
| Credentials | GET, POST, PUT, DELETE | transfer, credential-type schema |
| Users | GET | role management |
| Tags | GET, POST, PUT, DELETE | — |
| Variables | GET, POST, PUT, DELETE | — |
| Projects | GET, POST, PUT, DELETE | user management |
| Audit | POST | security audit |
| Source Control | POST | pull from source control |

### Critical Warnings

**NEVER** use offset-based pagination -- n8n uses cursor-based pagination exclusively. ALWAYS use the `nextCursor` value from the response to fetch the next page.

**NEVER** hardcode API keys in source code or commit them to version control. ALWAYS use environment variables or secret management systems to store API keys.

**NEVER** use `limit` values greater than 250 -- the API silently caps at 250 results per page. ALWAYS implement cursor-based pagination for large result sets.

**NEVER** attempt to delete a running execution -- the API returns an error. ALWAYS stop the execution first with `POST /executions/:id/stop`, then delete it.

**NEVER** assume API access is available on free trial instances -- the public REST API requires a paid plan.

---

## Authentication

### API Key Creation

1. Navigate to **Settings > n8n API** in the n8n UI
2. Select **Create API Key**
3. Provide a label and set an expiration period
4. On enterprise plans, select specific scopes for resource access
5. Copy the generated key immediately (it is shown only once)

### Header Format

ALWAYS include the API key in every request:

```
X-N8N-API-KEY: 
```

### Scope System (Enterprise Only)

Non-enterprise API keys grant full access to all account resources. Enterprise instances support scope-based restrictions per key. Scopes follow the pattern `resource:action`:

| Scope Pattern | Example |
|---------------|---------|
| `workflow:list` | List workflows |
| `workflow:create` | Create workflows |
| `workflow:read` | Read single workflow |
| `workflow:update` | Update workflow content |
| `workflow:delete` | Delete workflow |
| `workflow:activate` | Activate workflow |
| `workflow:deactivate` | Deactivate workflow |
| `workflow:move` | Transfer workflow to another project |
| `execution:list` | List executions |
| `execution:read` | Read single execution |
| `execution:delete` | Delete execution |
| `execution:retry` | Retry failed execution |
| `execution:stop` | Stop running execution |
| `credential:list` | List credentials |
| `credential:create` | Create credentials |
| `credential:update` | Update credentials |
| `credential:delete` | Delete credentials |
| `credential:move` | Transfer credentials |

---

## Cursor-Based Pagination

### How It Works

1. First request: specify `limit` (default 100, max 250)
2. Response contains `data` array and `nextCursor` string
3. Pass `nextCursor` as `cursor` parameter in the next request
4. When `nextCursor` is `null` or absent, you have reached the last page

### Pagination Pattern

```
Request 1:  GET /api/v1/workflows?limit=100
Response 1: { "data": [...], "nextCursor": "MTIzNA==" }

Request 2:  GET /api/v1/workflows?limit=100&cursor=MTIzNA==
Response 2: { "data": [...], "nextCursor": "NTY3OA==" }

Request 3:  GET /api/v1/workflows?limit=100&cursor=NTY3OA==
Response 3: { "data": [...], "nextCursor": null }  // Last page
```

ALWAYS check for `nextCursor` being `null` or absent to detect the final page. NEVER assume a fixed number of pages.

---

## Essential Patterns

### Pattern 1: List Active Workflows

```bash
curl -X GET \
  '/api/v1/workflows?active=true&limit=100' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: '
```

### Pattern 2: Create and Activate a Workflow

1. `POST /api/v1/workflows` with workflow JSON body
2. `POST /api/v1/workflows/:id/activate` to activate

ALWAYS create the workflow first, then activate in a separate call. There is no single-step create-and-activate endpoint.

### Pattern 3: Retry a Failed Execution

```bash
curl -X POST \
  '/api/v1/executions//retry' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: '
```

ALWAYS verify the execution status is `error` or `crashed` before retrying. Retrying a successful execution has no effect.

### Pattern 4: Transfer Workflow Between Projects

```bash
curl -X POST \
  '/api/v1/workflows//transfer' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-N8N-API-KEY: ' \
  -d '{ "destinationProjectId": "" }'
```

### Pattern 5: Paginate Through All Executions

```bash
cursor=""
while true; do
  if [ -z "$cursor" ]; then
    response=$(curl -s '/api/v1/executions?limit=250' \
      -H 'X-N8N-API-KEY: ')
  else
    response=$(curl -s "/api/v1/executions?limit=250&cursor=$cursor" \
      -H 'X-N8N-API-KEY: ')
  fi
  # Process $response data...
  cursor=$(echo "$response" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done
```

---

## API Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `N8N_PUBLIC_API_DISABLED` | `false` | Disable the public API entirely |
| `N8N_PUBLIC_API_ENDPOINT` | `api` | Path prefix for public API endpoints |
| `N8N_PUBLIC_API_SWAGGERUI_DISABLED` | `false` | Disable Scalar UI API playground |

### API Playground

The interactive API documentation (Scalar UI) is available at:

```
/api/v1/docs
```

This is available on self-hosted instances by default. Set `N8N_PUBLIC_API_SWAGGERUI_DISABLED=true` to disable it in production.

---

## Decision Trees

### Which Endpoint to Use?

```
Need to manage workflow definitions?
├── List/search workflows → GET /workflows (with query filters)
├── Create new workflow   → POST /workflows
├── Update workflow JSON  → PUT /workflows/:id
├── Delete workflow       → DELETE /workflows/:id
├── Toggle activation     → POST /workflows/:id/activate or /deactivate
└── Move to project       → POST /workflows/:id/transfer

Need to inspect or manage executions?
├── List executions       → GET /executions (filter by status, workflowId)
├── Get execution detail  → GET /executions/:id?includeData=true
├── Retry failed          → POST /executions/:id/retry
├── Stop running          → POST /executions/:id/stop
└── Bulk stop             → POST /executions/stop

Need to manage credentials?
├── List credentials      → GET /credentials
├── Create credential     → POST /credentials
├── Update credential     → PUT /credentials/:id
├── Delete credential     → DELETE /credentials/:id
├── Get type schema       → GET /credential-types/:typeName
└── Move to project       → POST /credentials/:id/transfer

Need organizational resources?
├── Tags                  → /tags (CRUD)
├── Variables             → /variables (CRUD)
├── Projects              → /projects (CRUD + user management)
└── Users                 → /users (list, get, role)
```

### Should You Use the API or the CLI?

```
Running n8n in Docker/remote?
├── YES → Use REST API (only option for remote management)
└── NO (local access to n8n process)
    ├── Need programmatic integration? → REST API
    ├── One-off admin task?            → CLI (n8n export, n8n import)
    └── Backup automation?             → CLI for export, API for monitoring
```

---

## Reference Links

- [references/methods.md](references/methods.md) -- Complete endpoint reference with methods, paths, and scopes
- [references/examples.md](references/examples.md) -- curl examples for each major resource type with authentication and pagination
- [references/anti-patterns.md](references/anti-patterns.md) -- Common API usage mistakes and how to avoid them

### Official Sources

- https://docs.n8n.io/api/ -- n8n Public REST API documentation
- https://docs.n8n.io/api/authentication/ -- API authentication guide
- https://docs.n8n.io/api/pagination/ -- Pagination documentation
- https://docs.n8n.io/hosting/configuration/environment-variables/ -- Environment variables reference

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/n8n-Claude-Skill-Package](https://github.com/Impertio-Studio/n8n-Claude-Skill-Package)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-n8n-claude-skill-package-n8n-core-api
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.