Index of every page on this site: llms.txt
All skills
n8n-io avatar

/public-api

@273d130 official
by n8n - Workflow Automationn8n-io/n8n211k stars
61,599
Run it yourself

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.

  • 2 files
  • 23.5 KB
  • Updated last week
  • GitHub
Use this Skill: https://skilld.dev/gh/n8n-io/n8n/public-api

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈75 tokens for metadata: the name and description. ≈3.1k when used: this file. ≈2.8k more on demand in 1 file.

Description uses 3.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈303 characters, or 3.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
  • 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).
  • 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

  • Write code that acts as its own documentation. The schema, the decorator, and the test should make the rule clear on their own without a comment.
  • 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). Translate to skip/take only inside a repository, at the TypeORM find call. The public query string is still cursor + limit; offset is the decoded cursor field passed into the service, never a client-facing param.
  • Updates: full-object PUT, not PATCH. A successful GET body should be acceptable as a PUT body for the same resource (round-trip), aside from server-managed/immutable fields.
  • Strict input DTOs; output DTOs are an allowlist of public fields.
  • Never return real secrets/tokens in responses or error details — mask with the resource's sentinel/placeholder (or omit). Echoing that sentinel on PUT means keep; any other value replaces. Detail: Updates and write-only secrets.
  • "Test connection/config" endpoints validate the request body (test-before-save).

Architecture

Public and internal are sibling routes over one shared, HTTP-agnostic service; neither calls the other.

GET /rest/tags    → TagsController         ┐  JWT auth, internal shape
                                            ├─→ TagService
GET /api/v1/tags  → TagsPublicController   ┘  API-key auth, public DTO

Reuse the service behavior. Reuse a DTO only when public and internal contracts are intentionally identical; otherwise make a public-specific DTO that doesn't depend on a UI-oriented internal shape.

Before editing

Open these — they are the source of truth, not this skill:

  • v1/controllers/ — copy structure from tags.public.controller.ts (list + cursor) or workflows.public.controller.ts (@Param + @ProjectScope), and index.ts for the barrel.
  • Decorators in packages/@n8n/decorators/src/controller/: public-api-controller.ts, api-key-scope.ts, api-response.ts, api-error-response.ts, api-summary.ts, api-description.ts, api-tags.ts, route.ts, scoped.ts, args.ts, licensed.ts.
  • The OpenAPI generator (reads the decorators above, no hand-written YAML needed for a controller route): v1/openapi-gen/generate.ts, v1/openapi-gen/decorator-routes.ts.
  • Pagination helpers: v1/shared/services/pagination.service.ts (decodeCursor, encodeNextCursor).
  • DTOs: packages/@n8n/api-types/src/dto/.
  • Gating tests: v1/__tests__/public-api-controllers.test.ts, v1/__tests__/scope-parity.test.ts, v1/openapi-gen/__tests__/generated-spec-drift.test.ts.
  • The internal controller for this resource and its neighboring functional tests.

Declaring a controller

A controller is a class marked @PublicApiController('/base') that injects the shared service via its constructor and delegates to it. Copy the shape from an existing controller in v1/controllers/ with the same operation type and auth model; reuse only what applies. Decorators, all from @n8n/decorators:

Decorator Use
@PublicApiController('/base') Class marker; mounts routes at /api/v1/base.
@Get/@Post/@Put/@Patch/@Delete('/path') Route method.
@ApiKeyScope('res:action') API-key grant check.
@ProjectScope/@GlobalScope('res:action') User RBAC check.
@ApiResponse(status) / @ApiResponse(status, Dto) Success status + (optional) output DTO; registry .parse()s + strips the return value. Exactly one per route — a second @ApiResponse throws. 204 can't carry a DTO or a binary body — throws. For a binary response body (returned as { body, headers? }), use @ApiResponse(status, { mediaType, description?, headers? }) — see Binary response bodies.
@ApiErrorResponse(status) Declares an additional documented non-2xx status (e.g. 404, 409). Stack multiple for more than one. 400/401/403 are added automatically (body/query present, always, and @ApiKeyScope present, respectively) — don't declare those yourself.
@ApiSummary(text) / @ApiDescription(text) / @ApiTags([...]) OpenAPI summary/description/tags. @ApiTags sorts alphabetically regardless of the order you pass. All optional but expected on every real route.
@Query / @Body / @Param('name') Bind + validate via a Z.class DTO / path param. @Body is JSON by default; @Body({ mediaType: 'multipart/form-data', uploadLimits }) takes a multipart/form-data body instead — see Request body media types.
@Licensed('feat') Gates the route on a single BooleanLicenseFeature; PublicApiControllerRegistry runs its own license middleware (after auth/@ApiKeyScope/@ProjectScope

Authorization (easy to get wrong)

  • @ApiKeyScope (what the API key is granted) and @ProjectScope/@GlobalScope (what the user may do) are independent. Use both when the model needs both.
  • Name every path param {resource}Id (e.g. workflowId, credentialId, projectId, …) — never a generic :id / {id}. This is the Public API's naming convention: it keeps the API self-documenting and gives typed SDK codegen a real argument name instead of id. @ProjectScope also reads req.params as-is and does not remap id — it resolves authorization by exact key name (workflowId, credentialId, projectId, dataTableId, …), so a generic id on a @ProjectScope route often fails outright; a @GlobalScope or unscoped route won't fail the same way, but still follow the convention.
  • @ApiKeyScope takes a string, { anyOf: [...] }, or { allOf: [...] } — never a bare array. The scope must exist in the permissions registry (API_KEY_RESOURCES in @n8n/permissions); scope-parity.test.ts fails on an orphan scope.

DTOs

  • Build the public response shape explicitly; don't return an ORM entity and lean on @ApiResponse stripping to hide fields.
  • Treat the output DTO as an allowlist. Re-check nested relations, ownership fields, tokens, and encrypted values.
  • An output DTO restricts which fields you return, not which values they may hold. The registry parses the handler's return value against it, so a value the schema rejects becomes a 500. Keep the schema loose enough for anything an existing row may contain.
  • Build the response from the relations the route loaded, not from the entity type. TypeORM relations are opt-in, so two routes over the same entity can return different shapes.
  • Make input DTOs strict so unknown/partial fields aren't silently accepted: Z.class(shape, { strict: true }).
  • Secrets: never return a real secret; use the resource's sentinel/placeholder (or omit). See Updates and write-only secrets.

List endpoints (cursor pagination)

Copy the cursor flow from tags.public.controller.ts. The input DTO takes limit: publicApiPaginationSchema.limit plus cursor: z.string().optional() — pick limit off the schema, never spread the whole publicApiPaginationSchema (it also exports offset, which must never be a Public API query param). Use decodeCursor / encodeNextCursor from the shared pagination service; the cursor is opaque; return { data, nextCursor } (never a bare array) with nextCursor: null on the last page; an invalid cursor is a 400. Preserve an existing endpoint's cursor semantics as-is — but an offset param is a defect to remove, not a contract to preserve. Detail: List endpoints and cursor pagination.

Wiring checklist

  1. v1/controllers/<feature>.public.controller.ts + side-effect import in v1/controllers/index.ts.
  2. Public DTO in @n8n/api-types + export from the barrel (src/dto/).
  3. @ApiKeyScope value exists in the permissions registry.
  4. Don't hand-write the OpenAPI path or x-required-scope for a controller route — the generator (v1/openapi-gen/generate.ts) builds it from your decorators (@ApiSummary/@ApiDescription/@ApiTags/@ApiKeyScope/ @ApiResponse/@ApiErrorResponse). The generator automatically suffixes the description with a sentence indicating which API Key scopes are required for the operation, do not repeat these in the @ApiDescription. Run the full pnpm build and commit the regenerated handlers/<feature>/spec/paths/*.generated.yml fragment(s) and openapi.decorator-routes.generated.yml — generated-spec-drift.test.ts fails CI if they're stale. pnpm run build:data alone is not enough after touching a controller: it runs the generator against the already-compiled dist/, so a new/changed controller silently doesn't show up unless tsc ran first.
  5. If the route uses a new tag in @ApiTags, declare that tag in the tags: array of v1/openapi.yml. Give it an x-displayName and an x-parent that names one of the parent tags. Keep the child tags in alphabetical order. GitBook builds the page URL from the display name, so do not change an existing x-displayName without checking the docs URLs. openapi-tags.test.ts fails if the tag is not declared or is out of order.
  6. Add the route to packages/nodes-base/nodes/N8n/n8n-api-coverage.json.
  7. Tests.

Testing

Always cover: happy path, input-validation failure, missing API-key scope, RBAC denial. Prefer covering the business path in packages/cli/test/integration/public-api/ (real HTTP + DB); mocked-service unit tests don't replace that. Add the cases that apply (cursor pages, not-found/conflict, no sensitive fields, credential keep/replace, migration contract) — see Testing matrix. Match the nearest existing tests.

More detail (reference.md)

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 273d130. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week

README badge

README badge for n8n-io/n8n/public-api