API Reference

NocoBase v2 — REST API reference

This is a reference-only skill. It is not auto-triggered; load it manually when you need an exact endpoint or schema. The single source of truth is the bundled OpenAPI spec.

Spec location

${CLAUDE_PLUGIN_ROOT}/references/openapi/nocobase.json

• OpenAPI version: 3.0.3
• API version: 2.1.0-beta.29
• Endpoints: 272 paths
• Server: /api/ (relative to NocoBase host)

Base URL and auth

${NB_URL}/api/{resource}:{action}
Authorization: Bearer <token>

Get the token via POST ${NB_URL}/api/auth:signIn with NB_USER + NB_PASSWORD (primary), or use a long-lived NB_TOKEN from the API Keys plugin — see the auth skill.

Endpoint convention

NocoBase exposes a resource-action style API rather than CRUD over verbs:

Both reads and writes accept a filter query/body parameter using the JSON filter language ($eq, $in, $and, $or, etc.). The nocobase-data-modeling skill has the full grammar.

Association resources

For relations, the path nests the parent record:

GET  /api/{collection}/{recordKey}/{associationField}:list
POST /api/{collection}/{recordKey}/{associationField}:add
POST /api/{collection}/{recordKey}/{associationField}:set
POST /api/{collection}/{recordKey}/{associationField}:remove
POST /api/{collection}/{recordKey}/{associationField}:toggle  // m2m only

recordKey is normally the primary key (often id).

Tag groups (where to look first)

Top groups by operation count — see references/tags-overview.md for the full listing:

How to look up an endpoint

When you need an endpoint path, schema, or parameter list, do not guess — query the OpenAPI file directly.

SPEC="${CLAUDE_PLUGIN_ROOT}/references/openapi/nocobase.json"

# 1. List every path containing a keyword
jq -r '.paths | keys[] | select(test("workflow"; "i"))' "$SPEC"

# 2. Show methods + summary for a path
jq '.paths["/workflows:create"]' "$SPEC"

# 3. List all operations in a tag
jq -r '.paths | to_entries[]
       | .key as $p
       | .value | to_entries[]
       | select(.value.tags[0]? == "flowSurfaces")
       | "\(.key | ascii_upcase) \($p)"' "$SPEC"

# 4. Resolve a schema reference
jq '.components.schemas.WorkflowDto' "$SPEC"

Always feed the path you derived back to the user as ${NB_URL}/api{path} — the OpenAPI server is /api/, so paths in the spec are relative to that.

Distilled summaries

• references/tags-overview.md — every tag, one line each, with the matching skill in this plugin.
• references/common-endpoints.md — copy-paste curl recipes for the 12 highest-traffic operations.

Notes and gotchas

• POST for non-creates is normal. Most write actions (:update, :destroy, :move, :set, :remove) use POST even when conceptually they're updates or deletes — this is intentional, do not retry as PUT/DELETE.
• filterByTk vs filter. filterByTk selects exactly one record by primary key; filter is the general-purpose JSON filter language. Read endpoints accept both.
• Pagination. page (1-indexed) and pageSize (default 20) on any :list. The response wraps results in { data, meta: { count, page, pageSize, totalPage } }.
• appends. Pass appends=relName (repeat for each relation) on :list / :get to eager-load relations; otherwise relations are not embedded.
• Errors. 4xx/5xx return { errors: [{ message, code? }] }. 401 is auth (see auth skill); 403 is ACL (see nocobase-acl-manage).
• OpenAPI completeness. The spec covers core + bundled plugins shipping with NocoBase v2.1.0-beta.29. Custom plugins add their own routes that are not in this file — load nocobase-plugin-development to learn how plugins register routes.