Agent skill · software engineering · n8n-io
n8n:public-api
Adds, migrates, or updates n8n Public API v1 endpoints with @PublicApiController — public DTOs, API-key and RBAC scopes, cursor pagination, OpenAPI + coverage wiring, and tests. Use when working under packages/cli/src/public-api/v1/ or when exposing an existing service through /api/v1.
Why this skill is useful
Adds specific patterns and rules for implementing n8n Public API v1 endpoints that the AI wouldn't reliably generate on its own.
What it needs
About 6k tokens when loaded. Last updated 2026-08-07. 199,638 stars on the source repository.
What this skill does
Public API v1 Public API v1 lives in packages/cli/src/public-api/v1/, mounted at /api/v1 with API-key auth and public error formatting via PublicApiControllerRegistry (packages/cli/src/public-api/public-api-controller.registry.ts). Two rule tiers: invariants (never break) and team defaults (follow unless an existing public contract forces otherwise). When this skill and the code disagree on a detail, the code wins — so open the files below. That is a reason to check the code, not license to drop a team default. Non-negotiable rules New endpoints are @PublicApiController classes under v1/controllers/, one .public.controller.ts per feature. A controller is a class — never export = (the legacy tuple style; require-public-api-controller flags it). Public API and internal REST are separate HTTP surfaces. A public controller never calls an internal controller/endpoint; both reuse the same service. Controllers and handlers delegate to a service — never import a repository or Container.get(…Repository) (no-repository-in-public-api-handler). Input/output go through DTOs from @n8n/api-types; every JSON route declares @ApiResponse(Dto). Register each controller via a side-effect import in v1/controllers/index.ts (public-api-controllers.test.ts fails otherwise). Don't add business logic to legacy express-openapi-validator (EOV) handlers. Migrating a legacy endpoint must not change its public contract. These are n8n-local-rules ESLint rules (see packages/cli/eslint.config.mjs) and can't be silenced inline (no-public-api-guardrail-disable). The off allowlist there covers pre-existing legacy files only — it's shrink-only, don't add to it. Team defaults List endpoints: cursor-based pagination (internal API uses both cursor- and page-based — don't copy an internal endpoint's model). Pagination args are always offset and limit — on service methods, handler calls, and repository methods you add. Never skip/take (TypeORM names). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills n8n-io/public-api