domma-cms 1.6.59 → 1.7.0

package/docs/api-reference.md

@@ -0,0 +1,1667 @@
+# API Reference
+
+All API endpoints are served under the `/api` prefix. Unless noted otherwise:
+
+- **Auth required** means the request must include `Authorization: Bearer <access_token>`
+- Responses use `Content-Type: application/json`
+- Error responses have the shape `{ "error": "message" }`
+- Rate limiting applies to sensitive auth endpoints (noted per endpoint)
+
+---
+
+## Public SEO endpoints
+
+These are unauthenticated, served at the root rather than under `/api`, and intended for search engines.
+
+### GET `/sitemap.xml`
+
+Auto-generated XML sitemap of indexable pages.
+
+**Auth required:** No
+**Content-Type:** `application/xml`
+**Caching:** Cached with tag `sitemap`; invalidated automatically on page create, update, rename, or delete.
+
+Pages enter the sitemap based on the rules in `server/services/sitemap.js` → `shouldIncludeInSitemap()` - typically `status: published`, `visibility: public`, and `seo.noindex` not set. Entries include `<loc>` and `<lastmod>` (from the page's `updatedAt`). Absolute URLs are derived from the request's host and protocol automatically - set `TRUST_PROXY` when behind a reverse proxy so `X-Forwarded-*` headers are honoured - use `loopback` for a proxy on the same machine (or the proxy's addresses/CIDRs), not `true`, which trusts every hop and lets visitors spoof their IP address. `site.baseUrl` can be set in `config/site.json` to override this if your infrastructure doesn't forward Host correctly.
+
+### GET `/robots.txt`
+
+Auto-generated robots policy referencing the sitemap.
+
+**Auth required:** No
+**Content-Type:** `text/plain`
+
+Default body:
+
+```
+User-agent: *
+Allow: /
+Disallow: /admin/
+Disallow: /api/
+
+Sitemap: <request-origin>/sitemap.xml
+```
+
+The sitemap URL uses the same origin auto-derivation as `/sitemap.xml`. Append additional directives via `site.seo.robotsExtra` in `config/site.json`.
+
+---
+
+## Authentication (`/api/auth/*`)
+
+### GET `/api/auth/setup-status`
+
+Check whether the initial admin account has been created.
+
+**Auth required:** No
+
+**Response**
+
+```json
+{ "needsSetup": true, "siteTitle": "My Site", "resetByEmail": true, "resetExpiresIn": "1 hour" }
+```
+
+`resetByEmail` is `false` when no mail server is set up - "Forgot your password?" cannot send anything then.
+
+---
+
+### POST `/api/auth/setup`
+
+Create the very first administrator account. Returns `403` if any users already exist.
+
+**Auth required:** No
+
+**Request body**
+
+```json
+{
+  "name": "Admin User",
+  "email": "admin@example.com",
+  "password": "secret123"
+}
+```
+
+**Response** `201`
+
+```json
+{
+  "token": "<access_token>",
+  "refreshToken": "<refresh_token>",
+  "user": { "id": "uuid", "name": "Admin User", "email": "admin@example.com", "role": "admin" }
+}
+```
+
+---
+
+### POST `/api/auth/login`
+
+Exchange credentials for tokens. Rate limited to **5 requests per minute**.
+
+**Auth required:** No
+
+**Request body**
+
+```json
+{ "email": "admin@example.com", "password": "secret123" }
+```
+
+**Response** `200`
+
+```json
+{
+  "token": "<access_token>",
+  "refreshToken": "<refresh_token>",
+  "user": { "id": "uuid", "name": "Admin User", "email": "admin@example.com", "role": "admin" }
+}
+```
+
+---
+
+### POST `/api/auth/refresh`
+
+Exchange a refresh token for a new access token.
+
+**Auth required:** No
+
+**Request body**
+
+```json
+{ "refreshToken": "<refresh_token>" }
+```
+
+**Response** `200`
+
+```json
+{ "token": "<new_access_token>" }
+```
+
+---
+
+### POST `/api/auth/logout`
+
+Blacklist a refresh token. Safe to call without authentication.
+
+**Auth required:** No
+
+**Request body**
+
+```json
+{ "refreshToken": "<refresh_token>" }
+```
+
+**Response** `200`
+
+```json
+{ "ok": true }
+```
+
+---
+
+### GET `/api/auth/me`
+
+Return the authenticated user's profile.
+
+**Auth required:** Yes
+
+**Response** `200`
+
+```json
+{
+  "id": "uuid",
+  "name": "Admin User",
+  "email": "admin@example.com",
+  "role": "admin",
+  "isActive": true,
+  "lastLogin": "2026-01-01T00:00:00.000Z",
+  "profile": {}
+}
+```
+
+---
+
+### PUT `/api/auth/me`
+
+Update the authenticated user's own name, email, password, or profile data.
+
+**Auth required:** Yes
+
+**Request body** (all fields optional)
+
+```json
+{
+  "name": "New Name",
+  "email": "new@example.com",
+  "password": "newpassword",
+  "profile": { "bio": "Hello" }
+}
+```
+
+**Response** `200` - updated user object with `profile`
+
+---
+
+### GET `/api/auth/permissions`
+
+Return the permissions for every role the authenticated user holds, with the admin scope and home.
+
+**Auth required:** Yes
+
+**Response** `200`
+
+```json
+{
+  "permissions": ["pages.read", "pages.create", "..."],
+  "adminScope": null,
+  "adminHome": "/plugins/site-manager/dashboard"
+}
+```
+
+`adminScope` is `null` for the whole admin, or `{home, allow}` for a confined role. `adminHome` is the
+route `#/` opens for this user: a confined role's home, else the site's `adminHome` if the user may use
+it and the sidebar knows it, else `/`.
+
+---
+
+### GET `/api/auth/permissions-registry`
+
+Return the full permissions registry (all resources and their role assignments).
+
+**Auth required:** Yes
+
+**Response** `200`
+
+```json
+{ "groups": [...], "resources": { ... } }
+```
+
+---
+
+### POST `/api/auth/forgot-password`
+
+Trigger a password reset email. Answers at once and identically whether or not the address has an account - the lookup and the send happen after the reply, so neither the answer nor its timing says whether an account exists. Rate limited to **3 requests per hour**.
+
+The link in the email points at `site.baseUrl` when it is set; otherwise at the address the request came from only if someone has signed in there, otherwise at the address signed in at most recently. With none of those (or no mail server) nothing is sent and the admins get a notification. Emits `auth:resetRequested` `{email, userId, ip, ua, sent, reason}`.
+
+**Auth required:** No
+
+**Request body**
+
+```json
+{ "email": "user@example.com" }
+```
+
+**Response** `200`
+
+```json
+{ "ok": true, "expiresIn": "1 hour" }
+```
+
+---
+
+### POST `/api/auth/reset-password`
+
+Consume a reset token and set a new password. Rate limited to **5 requests per minute**.
+
+**Auth required:** No
+
+**Request body**
+
+```json
+{ "token": "<reset_token>", "password": "newpassword" }
+```
+
+**Response** `200`
+
+```json
+{ "ok": true }
+```
+
+The link is used up before the password is set, the account is signed out everywhere, and the holder is emailed that
+their password changed. A link for an account made inactive since it was sent no longer works. `400` with
+`"expired": true` for a link that is unknown, used, withdrawn or out of time; with `problems` when the site's password
+rules refuse the password.
+
+---
+
+### POST `/api/auth/reset-password/check`
+
+Is a reset link still good - and, with a password, what the site's password rules make of it. The reset screen calls
+it on opening (so a dead link says so before anything is typed) and as the new password is typed. Rate limited to
+**60 requests per minute**.
+
+**Auth required:** No (the token is the credential)
+
+**Request body**
+
+```json
+{ "token": "<reset_token>", "password": "optional - to check against the rules" }
+```
+
+**Response** `200`
+
+```json
+{ "email": "user@example.com", "expiresAt": "2026-09-27T09:00:00.000Z", "minutesLeft": 58, "problems": [] }
+```
+
+`400` `{ "error": "Invalid or expired reset link", "expired": true }` otherwise.
+
+---
+
+## Pages (`/api/pages/*`)
+
+All pages endpoints require the relevant `pages` permission.
+
+### GET `/api/pages`
+
+List all pages (summary fields only).
+
+**Auth required:** Yes (`pages:read`)
+
+**Response** `200` - array of page summaries
+
+```json
+[
+  {
+    "urlPath": "/about",
+    "title": "About",
+    "slug": "about",
+    "status": "published",
+    "layout": "default",
+    "showInNav": true,
+    "sortOrder": 1,
+    "category": null,
+    "visibility": "public",
+    "tags": [],
+    "updatedAt": "2026-01-01T00:00:00.000Z",
+    "createdAt": "2026-01-01T00:00:00.000Z"
+  }
+]
+```
+
+---
+
+### GET `/api/pages/tags`
+
+Return a sorted, deduplicated list of all tags used across pages.
+
+**Auth required:** Yes (`pages:read`)
+
+**Response** `200`
+
+```json
+{ "tags": ["blog", "news", "tutorial"] }
+```
+
+---
+
+### GET `/api/pages/*`
+
+Get a single page by URL path. The wildcard maps to the URL path, e.g. `GET /api/pages/about` retrieves `/about`.
+
+**Auth required:** Yes (`pages:read`)
+
+**Response** `200` - full page object including `frontmatter`, `body` (raw Markdown), and `html`
+
+---
+
+### POST `/api/pages`
+
+Create a new page.
+
+**Auth required:** Yes (`pages:create`)
+
+**Request body**
+
+```json
+{
+  "urlPath": "/about",
+  "frontmatter": {
+    "title": "About Us",
+    "layout": "default",
+    "status": "draft"
+  },
+  "body": "## Hello\n\nWelcome to our site."
+}
+```
+
+**Response** `201` - created page object
+
+---
+
+### POST `/api/pages/preview`
+
+Render Markdown (with shortcodes) to HTML without persisting anything.
+
+**Auth required:** Yes (`pages:read`)
+
+**Request body**
+
+```json
+{ "markdown": "## Hello\n\n[card title=\"Example\"]Body[/card]" }
+```
+
+**Response** `200`
+
+```json
+{ "html": "<h2>Hello</h2>..." }
+```
+
+---
+
+### PUT `/api/pages/*`
+
+Update a page. Optionally rename it to a new URL path.
+
+**Auth required:** Yes (`pages:update`)
+
+**Request body**
+
+```json
+{
+  "frontmatter": { "title": "Updated Title", "status": "published" },
+  "body": "Updated content.",
+  "newUrlPath": "/about-us"
+}
+```
+
+`newUrlPath` is optional. If supplied and different from the current path, the page file is renamed and any navigation items pointing to the old URL are updated automatically.
+
+**Response** `200` - updated page object
+
+---
+
+### DELETE `/api/pages/*`
+
+Delete a page.
+
+**Auth required:** Yes (`pages:delete`)
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+## List tags (`/api/list-tags/:kind`)
+
+Admin-only tags that link pages or blocks together, so the admin lists can be narrowed to one tag. `:kind` is `pages` or `blocks`. A page stores its tags as `adminTags` in its frontmatter, and a block in `meta.adminTags`. The names are kept in `config/list-tags.json`. Nothing on the public site reads them. Every change applies only to the items the caller's projects allow.
+
+| Method | Path | Body | Auth |
+|--------|------|------|------|
+| GET | `/api/list-tags/:kind` | - | `pages:read` - `{tags: [{name, count}]}` |
+| POST | `/api/list-tags/:kind` | `{name}` | `pages:update` - creates a tag |
+| PUT | `/api/list-tags/:kind/item` | `{id, tags}` | `pages:update` - `id` is the page's urlPath or the block's name; adds no page revision |
+| POST | `/api/list-tags/:kind/rename` | `{from, to}` | `pages:update` - `{name, changed}`; renaming onto an existing tag merges the two |
+| POST | `/api/list-tags/:kind/delete` | `{name}` | `pages:update` - `{changed}`; the items stay |
+
+---
+
+## Media (`/api/media/*`)
+
+### GET `/api/media`
+
+List all uploaded media files.
+
+**Auth required:** Yes (`media:read`)
+
+**Response** `200` - array of media objects with `name`, `url`, `size`, `mime`, `updatedAt`
+
+---
+
+### POST `/api/media`
+
+Upload one or more files. Uses `multipart/form-data`. Allowed types: images (JPEG, PNG, GIF, WebP, SVG, BMP, TIFF, ICO), documents (PDF, TXT, CSV, DOC, DOCX, XLS, XLSX), video (MP4, WebM, OGG), audio (MP3, OGG, WAV, WebM).
+
+**Auth required:** Yes (`media:create`)
+
+**Response** `201` - single media object, or array if multiple files uploaded
+
+---
+
+### PATCH `/api/media/:name`
+
+Rename a media file.
+
+**Auth required:** Yes (`media:update`)
+
+**Request body**
+
+```json
+{ "newName": "new-filename.jpg" }
+```
+
+**Response** `200` - updated media object
+
+---
+
+### DELETE `/api/media/:name`
+
+Delete a media file.
+
+**Auth required:** Yes (`media:delete`)
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+### GET `/api/media/:name/info`
+
+Get image metadata (dimensions, format, size) for editable image formats (JPEG, PNG, WebP, TIFF).
+
+**Auth required:** Yes (`media:read`)
+
+**Response** `200` - image metadata object
+
+---
+
+### POST `/api/media/:name/transform`
+
+Apply image transformations (resize, crop, rotate, watermark, convert format) using Sharp.
+
+**Auth required:** Yes (`media:update`)
+
+**Request body**
+
+```json
+{
+  "operations": {
+    "resize": { "width": 800, "height": 600, "fit": "cover" },
+    "rotate": 90,
+    "format": "webp",
+    "quality": 85
+  },
+  "saveAs": "resized-image.webp"
+}
+```
+
+`saveAs` is optional; omit it to overwrite the original.
+
+**Response** `200` - updated media object
+
+---
+
+## Navigation (`/api/navigation`)
+
+### GET `/api/navigation`
+
+Return the full navigation config object.
+
+**Auth required:** Yes (`navigation:read`)
+
+**Response** `200` - navigation config (see `config/navigation.json` in [Configuration](configuration.md))
+
+---
+
+### PUT `/api/navigation`
+
+Replace the navigation config.
+
+**Auth required:** Yes (`navigation:update`)
+
+**Request body** - navigation config object (same shape as the file). The server normalises `children` keys to `items` before saving.
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+## Sidebar (`/api/sidebar/*`)
+
+### GET `/api/sidebar/registered-items`
+
+Return the array of `{parent, folder, group?, item}` entries currently registered via `hooks.registerSidebarItem(...)` (and plugin manifests' `admin.sidebar`) by core and enabled plugins. `folder` is the Tool's default folder key (`tools` unless it names another); `group`, when present, is the sub-folder inside it (`Core` for the built-in Tools). Read-only snapshot of in-memory state - not persisted, regenerated on each server boot.
+
+**Auth required:** Yes (`menus:read`)
+
+**Response** `200`
+
+```json
+{
+  "items": [
+    {
+      "parent": null,
+      "folder": "system",
+      "item": {
+        "text":       "My Plugin",
+        "url":        "#/plugins/my-plugin",
+        "icon":       "puzzle",
+        "permission": "my-plugin"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Settings (`/api/settings`)
+
+### GET `/api/settings`
+
+Return the site config. The SMTP password is stripped from the response.
+
+**Auth required:** Yes (`settings:read`)
+
+**Response** `200` - site config object (see `config/site.json` in [Configuration](configuration.md))
+
+---
+
+### PUT `/api/settings`
+
+Update site settings. Only the following keys are accepted: `title`, `tagline`, `description`, `logo`, `favicon`, `theme`, `smtp`, `footer`, `analytics`, `social`, `locale`, `layoutOptions`.
+
+**Auth required:** Yes (`settings:update`)
+
+**Request body** - partial or full site config object
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+### POST `/api/settings/test-email`
+
+Send a test email using the stored SMTP configuration.
+
+**Auth required:** Yes (`settings:read`)
+
+**Request body** (optional)
+
+```json
+{ "to": "test@example.com" }
+```
+
+If `to` is omitted, the `fromAddress` from SMTP config is used.
+
+**Response** `200`
+
+```json
+{ "success": true, "message": "Test email sent to test@example.com" }
+```
+
+---
+
+### GET `/api/settings/custom-css`
+
+Return the current custom CSS content.
+
+**Auth required:** Yes (`settings:update`)
+
+**Response** `200`
+
+```json
+{ "css": "/* custom styles */" }
+```
+
+---
+
+### PUT `/api/settings/custom-css`
+
+Save custom CSS to `content/custom.css`. Maximum 100 KB.
+
+**Auth required:** Yes (`settings:update`)
+
+**Request body**
+
+```json
+{ "css": "body { background: red; }" }
+```
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+## Users (`/api/users/*`)
+
+Role hierarchy enforced: a user cannot create, edit, or delete users with an equal or higher role level.
+
+### GET `/api/users`
+
+List all users (includes profile data).
+
+**Auth required:** Yes (`users:read`)
+
+**Response** `200` - array of user objects with `profile` merged in
+
+---
+
+### GET `/api/users/:id`
+
+Get a single user. Users with the `users` read permission (Super Admin and Admin by default) can view any user; all other users can only view themselves.
+
+**Auth required:** Yes
+
+**Response** `200` - user object with `profile`
+
+---
+
+### POST `/api/users`
+
+Create a new user.
+
+**Auth required:** Yes (`users:create`)
+
+**Request body**
+
+```json
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "password": "password123",
+  "role": "user"
+}
+```
+
+Optional: `additionalRoles` (array), `projects` (array of project slugs - the user's access scope; empty =
+unrestricted), `meta` (object, e.g. `{"project": "shop"}` for the owning project), `isActive` (boolean,
+default `true`) and `profile` (object of profile field values). Send them here rather than in a follow-up
+PUT, so a failure cannot leave the account unrestricted and switched on.
+
+`role` defaults to `user`. You can only create users whose role is less senior than your own.
+
+**Response** `201` - created user object (password stripped)
+
+---
+
+### PUT `/api/users/:id`
+
+Update a user's details. Cannot escalate a user to a role higher than the actor's own role.
+
+**Auth required:** Yes (`users:update`)
+
+**Request body** (all fields optional)
+
+```json
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "role": "admin",
+  "isActive": true,
+  "profile": { "bio": "Site editor" }
+}
+```
+
+**Response** `200` - updated user object with `profile`
+
+---
+
+### DELETE `/api/users/:id`
+
+Delete a user. Cannot delete your own account.
+
+**Auth required:** Yes (`users:delete`)
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+### POST `/api/users/:id/password-reset`
+
+An administrator's password reset: email the user a link to choose a new password, or get one to pass on yourself
+(a site with no mail server, a mailbox that is not receiving). Their current password keeps working until the link is
+used; a newer link replaces an older one. Not for your own account (use My Profile), and only for someone your role is
+more senior to, on an active account.
+
+**Auth required:** Yes (`users:update`)
+
+**Request body**
+
+```json
+{ "via": "email" }
+```
+
+**Response** `200` - `via: "email"`: `{ "sent": true, "expiresAt": "…", "expiresIn": "1 hour" }`;
+`via: "link"`: `{ "link": "https://example.com/admin/#/reset-password?token=…", "expiresAt": "…", "expiresIn": "1 hour" }`.
+
+`409` with `code`: `NO_SMTP` (emailing with no mail server), `INACTIVE`, `NO_ORIGIN`. `403` for yourself or someone
+not junior to you. The list (`GET /api/users`) shows an open link as `resetLinkExpires` - the time only, never the token.
+
+---
+
+### DELETE `/api/users/:id/password-reset`
+
+Withdraw an unused reset link: it stops working at once. Same permissions as above.
+
+**Response** `200` `{ "ok": true }`
+
+---
+
+## Collections (`/api/collections/*`)
+
+**Number fields are stored as numbers.** Every entry write - admin, `/api/v1`, form submissions,
+import, Actions - converts a `number` field sent as plain decimal text (`"42"`, `" 9.5 "`) to a
+number, so it comes back as `42`. Text that is not a number (`""`, `"abc"`) is stored as sent, not
+refused; a required number field sent as `""` is still refused as missing.
+
+### Schema management
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/collections` | `collections:read` | List all collections (schemas) |
+| `POST` | `/api/collections` | `collections:create` | Create a collection |
+| `GET` | `/api/collections/:slug` | `collections:read` | Get a collection schema |
+| `PUT` | `/api/collections/:slug` | `collections:update` | Update a collection schema |
+| `DELETE` | `/api/collections/:slug` | `collections:delete` | Delete a collection and all its data |
+
+**Create collection request body**
+
+```json
+{
+  "title": "Blog Posts",
+  "slug": "blog-posts",
+  "description": "Optional description",
+  "fields": [
+    { "name": "title", "type": "text", "required": true },
+    { "name": "body", "type": "textarea" }
+  ],
+  "api": {
+    "read": { "enabled": true, "access": "public" },
+    "create": { "enabled": false }
+  }
+}
+```
+
+### Entry CRUD
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/collections/:slug/entries` | `collections:read` | List entries (paginated, searchable) |
+| `GET` | `/api/collections/:slug/entries/:id` | `collections:read` | Get a single entry |
+| `POST` | `/api/collections/:slug/entries` | `collections:create` | Create an entry |
+| `PUT` | `/api/collections/:slug/entries/:id` | `collections:update` | Update an entry |
+| `DELETE` | `/api/collections/:slug/entries/:id` | `collections:delete` | Delete an entry |
+| `DELETE` | `/api/collections/:slug/entries` | `collections:delete` | Clear all entries |
+
+**List entries query parameters**
+
+| Parameter            | Default      | Description                                                          |
+|----------------------|--------------|----------------------------------------------------------------------|
+| `page`               | `1`          | Page number                                                          |
+| `limit`              | `50`         | Results per page (`0` falls back to the default - ask for a larger number instead) |
+| `sort`               | `"createdAt"`| Field to sort by                                                     |
+| `order`              | `"desc"`     | Sort direction (`"asc"` or `"desc"`)                                 |
+| `search`             | -            | Full-text substring match across all field values                    |
+| `filter[<field>]`    | -            | Structured filter - defaults to equality                             |
+| `filter[<field>_op]` | -            | Structured filter with explicit operator (see below)                 |
+
+**Structured filter operators**
+
+| Suffix      | Meaning                            | Example                                          |
+|-------------|------------------------------------|--------------------------------------------------|
+| (none) / `_eq` | equal                           | `?filter[status]=open`                           |
+| `_ne`       | not equal                          | `?filter[status_ne]=closed`                      |
+| `_gt`       | greater than                       | `?filter[salary_gt]=40000`                       |
+| `_gte`      | greater than or equal              | `?filter[salary_gte]=50000`                      |
+| `_lt`       | less than                          | `?filter[salary_lt]=100000`                      |
+| `_lte`      | less than or equal                 | `?filter[postedAt_lte]=2026-06-01`               |
+| `_in`       | value in comma-separated list      | `?filter[type_in]=full-time,contract`            |
+| `_nin`      | value not in list                  | `?filter[status_nin]=archived,withdrawn`         |
+| `_contains` | substring match (case-insensitive) | `?filter[title_contains]=engineer`               |
+| `_starts`   | starts-with (case-insensitive)     | `?filter[title_starts]=Senior`                   |
+| `_ends`     | ends-with (case-insensitive)       | `?filter[email_ends]=@example.com`               |
+| `_exists`   | field is present and non-null      | `?filter[remote_exists]=true`                    |
+
+Predicates AND together. Pseudo-fields: `createdBy` (matches `meta.createdBy`), `id` (top-level entry id).
+Dot-paths into nested data are supported - `?filter[address.city]=London`.
+
+For MongoDB-backed collections the filter is translated to a native query (`$gte`, `$in`, regex with `^…$/i`, etc.)
+and pushed down to the database. File-mode collections apply the same operators in memory - semantics are identical.
+
+**Create/update entry request body**
+
+```json
+{ "data": { "title": "My Post", "body": "Content here." } }
+```
+
+### Export / Import
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/collections/:slug/export` | `collections:read` | Export entries (`?format=json` or `?format=csv`) |
+| `POST` | `/api/collections/:slug/import` | `collections:create` | Import entries from JSON |
+
+**Import request body**
+
+```json
+{ "entries": [{ "data": { "title": "Post 1" } }] }
+```
+
+### Public access endpoints
+
+When a collection has its `api` settings configured, entries can be accessed without admin authentication:
+
+| Method   | Path                                  | Access                                           |
+|----------|---------------------------------------|--------------------------------------------------|
+| `GET`    | `/api/collections/:slug/public`       | Determined by `api.read.access`                  |
+| `GET`    | `/api/collections/:slug/public/:id`   | Determined by `api.read.access`                  |
+| `POST`   | `/api/collections/:slug/public`       | Determined by `api.create.access`                |
+| `PUT`    | `/api/collections/:slug/public/:id`   | Determined by `api.update.access`                |
+| `DELETE` | `/api/collections/:slug/public/:id`   | Determined by `api.delete.access`                |
+| `POST`   | `/api/collections/render-scope`       | Authenticated; renders `[collection scope="mine"]` |
+
+Access values: `"public"` (no auth), `"token"` (requires a project-scoped API token - see
+[External API & API tokens](#external-api--api-tokens-apiv1)), or a role name (requires a JWT for that role or higher).
+
+`api.read` additionally accepts a `fields` array - when non-empty, public/external read responses
+include only the listed `data` fields (admin endpoints are unaffected).
+
+The public `GET` list endpoint accepts all the same query parameters as the admin list endpoint
+(`page`, `limit`, `sort`, `order`, `search`, `filter[…]`) plus:
+
+| Parameter | Description |
+|---|---|
+| `scope=mine` | Restrict to the current user's own entries (`createdBy = <user.id>`). Requires a JWT. Bypasses the `api.read` gate - users can always view their own data. |
+
+**`POST /api/collections/render-scope`** - renders a `[collection scope="mine"]` placeholder server-side with the
+current user's id injected. Called by the public site JS when it encounters `.dm-collection-hydrate` placeholders.
+An interactive block (`searchable`, `sortable`, `filterable` or `paginate`) comes back as a Collection Browser shell
+with `scope: "mine"` in its config (so `transitions` works); anything else as the static fragment.
+
+Request body:
+```json
+{ "attrs": "<base64-encoded JSON of the original shortcode attributes>" }
+```
+
+Response:
+```json
+{ "html": "<div class=\"dm-collection-cards\">...</div>" }
+```
+
+The endpoint never trusts the client's choice of user - the JWT is verified server-side and the `createdBy` filter
+is appended before rendering.
+
+### Pro: Connections
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/collections/pro-status` | `collections:read` | Check if Pro MongoDB mode is active |
+| `GET` | `/api/collections/connections` | Admin only | List configured connections |
+| `PUT` | `/api/collections/connections` | Admin only | Save connection config |
+
+---
+
+## External API & API tokens (`/api/v1/*`)
+
+The external API is a stable, versioned alias of the public collection endpoints - the documented
+surface for third-party integrations:
+
+| Method   | Path               | Equivalent                              |
+|----------|--------------------|------------------------------------------|
+| `GET`    | `/api/v1/:slug`     | `GET /api/collections/:slug/public`     |
+| `GET`    | `/api/v1/:slug/:id` | `GET /api/collections/:slug/public/:id` |
+| `POST`   | `/api/v1/:slug`     | `POST /api/collections/:slug/public`    |
+| `PUT`    | `/api/v1/:slug/:id` | `PUT /api/collections/:slug/public/:id` |
+| `DELETE` | `/api/v1/:slug/:id` | `DELETE /api/collections/:slug/public/:id` |
+
+Both paths share handlers, access rules, and query parameters (`page`, `limit`, `sort`, `order`,
+`search`, `filter[…]`, `resolveRefs`).
+
+### API tokens
+
+API tokens are machine credentials for external callers - created in the admin under
+**System → API Tokens** (or by a scaffolder recipe). Format: `dcms_` + 64 hex characters.
+Only a SHA-256 hash is stored; the plaintext is shown **once**, at creation.
+
+A collection verb opts into token auth with `api.<verb>.access: "token"`. Callers then send:
+
+```
+Authorization: Bearer dcms_<64 hex>
+```
+
+**Strictness:** a token is accepted *only* where the access mode is `"token"` - it is never a
+substitute for a role-name mode, and a JWT is never accepted in token mode.
+
+**Project binding:** every token belongs to one project and only works on collections whose
+resolved project matches (the collection's `meta.project`, or `core` when untagged).
+
+**Scopes (optional):** a token may carry `scopes: [{ "collection": "jobs", "verbs": ["read"] }]`.
+Empty scopes = every collection in the token's project. A scoped token is refused (403) outside
+its scope list. The verb must still be enabled with `access: "token"` on the collection itself.
+A scope may instead be a Content API scope, `{ "content": "pages" | "menus" | "site" | "search" }`
+(`@pages` in the token editor) - see [Content API](#content-api-apicontentv1).
+
+Failure responses: `401` (missing/invalid/disabled/expired token), `403` (wrong project or scope,
+or the verb is disabled).
+
+Entries created via token auth are attributed `meta.createdBy: "token:<token-id>"`, `meta.source: "api"`.
+
+### Token management (`/api/api-tokens/*`)
+
+| Method   | Path                  | Auth                | Description |
+|----------|-----------------------|---------------------|-------------|
+| `GET`    | `/api/api-tokens`     | `api-tokens:read`   | List tokens visible to the caller (project scope applies). Never includes the hash. |
+| `POST`   | `/api/api-tokens`     | `api-tokens:create` | Create a token. The response's `plaintext` field is the **only** time the token value appears. |
+| `PUT`    | `/api/api-tokens/:id` | `api-tokens:update` | Update `name`, `enabled`, `scopes`, `expiresAt`. The project binding and hash are immutable. |
+| `DELETE` | `/api/api-tokens/:id` | `api-tokens:delete` | Revoke - external callers lose access immediately. |
+
+**Create request body**
+
+```json
+{
+  "name": "mobile-app",
+  "project": "core",
+  "scopes": [{ "collection": "jobs", "verbs": ["read", "create"] }],
+  "expiresAt": "2027-01-01T00:00:00.000Z"
+}
+```
+
+**Create response (201)**
+
+```json
+{
+  "token": { "id": "…", "name": "mobile-app", "project": "core", "tokenHint": "ab12", "enabled": true },
+  "plaintext": "dcms_<64 hex - shown once, store it now>"
+}
+```
+
+> Existing roles are **not** back-filled with the `api-tokens` permission family - grant it via the
+> role editor. The level-0 root role self-heals at boot.
+
+---
+
+## Content API (`/api/content/v1/*`)
+
+Read-only, headless access to what the site publishes - pages, menus, the site settings public pages
+already show, and search - as JSON. Where `/api/v1` exposes collection **data**, the Content API exposes
+**content**. It has its own prefix because `/api/v1/:slug` matches any collection slug, and a
+collection called `pages` would otherwise be shadowed.
+
+**Off by default.** Turn it on at **System → Content API** (stored in `config/content-api.json`); until
+then every address answers `404`.
+
+| Method | Path                               | Returns |
+|--------|------------------------------------|---------|
+| `GET`  | `/api/content/v1/pages`            | `{pages, total, page, limit}` - page summaries, no bodies |
+| `GET`  | `/api/content/v1/pages/<path>`     | One page (`/pages/` is the home page; a directory path serves its `index`) |
+| `GET`  | `/api/content/v1/menus/:location`  | `{location, slug, name, items}` - the menu bound to a location |
+| `GET`  | `/api/content/v1/site`             | Title, brand, footer, social links, SEO defaults, theme |
+| `GET`  | `/api/content/v1/search?q=`        | `{results: [{urlPath, title, description, tags, snippet, score}]}` |
+
+### Which pages
+
+A page the API serves is exactly a page the site would serve the same caller: both call
+`resolvePublishedPage()` (`server/services/pagePublishing.js`), and a test pins them together.
+
+- Only `status: published` - drafts, scheduled and status-less pages are `404`.
+- Visibility follows `checkVisibility()`: a role-gated page is `403` to a caller who could not open it.
+- A page in a switched-off project is `404`.
+- Front matter **`api: false`** keeps a page off the API (`404`, not listed, not searched); it still
+  shows on the site.
+
+### Page list - query parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `page` | `1` | Page number |
+| `limit` | `50` | Page size, capped at the site's `maxLimit` (default 200). `0` or nonsense means the default |
+| `prefix` | - | Only pages whose path starts with this, e.g. `/services` |
+| `tag` / `category` | - | Only pages with this tag / in this category |
+| `project` | - | Only pages in this project |
+| `sort` / `order` | site order | `title`, `updatedAt` or `createdAt`; `order=desc` reverses |
+
+Summaries carry `urlPath`, `title`, `description`, `tags`, `category`, `layout`, `updatedAt`. A site can
+turn the list off (`listable: false`) and keep single pages, so callers must know a path.
+
+### A page
+
+```
+GET /api/content/v1/pages/about?format=html|markdown|both
+```
+
+```json
+{
+  "urlPath": "/about", "title": "About", "description": "…", "tags": ["company"], "category": "general",
+  "layout": "default", "createdAt": "…", "updatedAt": "…",
+  "seo": {"title": "…", "description": "…", "image": "…"},
+  "html": "<section>…</section>",
+  "requires": {"domma": true, "components": ["tabs", "effects"]},
+  "perViewer": false
+}
+```
+
+- `html` is the page **body** (no navbar or footer), shortcodes already rendered. `markdown` is the
+  source, shortcodes included. A format the site does not offer answers `400`; HTML is always offered.
+- `requires.components` names the Domma behaviour the HTML relies on - the markup `site.js` and
+  `effects.js` initialise (tabs, accordion, carousel, countdown, tooltip, reveal, effects, forms…) plus
+  any custom `[component]`s. Without Domma's CSS and JS those parts are inert.
+- Front matter is **allowlisted**: only the keys above appear. `seo` keeps `title`, `description`,
+  `image`, `canonical`, `noindex`.
+- `perViewer: true` means the body was rendered for this caller (a row-scoped `[view]`) and must not be
+  shared between users.
+- **Drafts:** in role mode only, `?preview=1` from a caller holding `pages.read` returns unpublished pages
+  (`Cache-Control: no-store`). Ignored in public and token mode.
+
+### Menus, site settings, search
+
+- **Menus** - `?page=/about` resolves page-bound menus as they would be on that page. Items are
+  allowlisted (`type`, `text`, `url`, `icon`, `target`, `size`, `badge`, `items`) and filtered for the
+  caller; structural items (`separator`, `spacer`) are kept. The `admin-sidebar` and `overlay` slots, and
+  any slot starting `admin`, are never served.
+- **Site** - `title`, `brand` (`text`, `logo`, `url`), `footer` (hidden links removed), `social`, `seo`
+  (`defaultTitle`, `titleSeparator`, `defaultDescription`), `theme`. Never `smtp`, `url`, `tagline` or
+  admin settings.
+- **Search** - the site's own search (`q` at least the site's minimum length, else `400`; `limit` up to its
+  max results). `404` when search is switched off in System → Search.
+
+### Access
+
+`access` in `config/content-api.json`, one mode for the whole API:
+
+| `access` | Who may call | Rendered as |
+|----------|--------------|-------------|
+| `public` | Anyone, no credentials | Anonymous visitor |
+| `token` (default) | A project API token (`Authorization: Bearer dcms_…`). A JWT is refused | Anonymous visitor |
+| a role name | A Bearer **access** JWT holding that role or a more senior one. A role the site does not have admits level 0 only. The site's `dm_session` cookie is never accepted | That user |
+
+**Tokens and projects.** A token reads only the pages of its own project - single pages, the list and
+search results; a page in another project is `404`. Menus and site settings are site-wide and readable by
+any valid token. Scopes narrow a token with content scopes - `{"content": "pages"}`, written `@pages` in
+the token editor (`@pages`, `@menus`, `@site`, `@search`; read-only, no verbs). A token with no scopes
+covers everything in its project; a token whose scopes name only collections gets **no** content.
+
+### Responses and caching
+
+| Case | Status | `Cache-Control` |
+|------|--------|-----------------|
+| Public mode | `200` | `public, max-age=60` + weak `ETag` (page mtime) |
+| Token mode | `200` | `private, no-cache` |
+| Role mode, or a draft | `200` | `no-store` |
+| API or resource off, page missing / unpublished / disabled project / `api: false`, slot not served | `404` | `no-store` |
+| No or invalid credential, refresh token, JWT in token mode | `401` | `no-store` |
+| Role too junior, scope does not allow it, visibility refuses | `403` | `no-store` |
+| Format not offered, search query too short | `400` | `no-store` |
+
+### Calling from another domain
+
+A browser on another origin can call the API only when that origin is allowed by `cors.origin` in
+`config/server.json` (see `docs/configuration.md`). Token and role modes send an `Authorization` header,
+so the browser preflights the request; `@fastify/cors` answers it for allowed origins. Server-to-server
+callers are unaffected.
+
+```bash
+curl 'https://example.com/api/content/v1/pages?prefix=/blog&limit=10'
+curl -H 'Authorization: Bearer dcms_0123…cdef' 'https://example.com/api/content/v1/pages/about?format=both'
+```
+
+### Admin endpoints (`/api/content-api/*`)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/api/content-api/settings` | `settings:read` | The normalised settings |
+| `PUT` | `/api/content-api/settings` | `settings:update` | Save; a role the site does not have is `400` |
+| `GET` | `/api/content-api/_count` | `settings:read` | Sidebar badge: pages served to an anonymous caller |
+| `GET` | `/api/content-api/preview?path=&format=&as=anon` | `settings:read` | What an anonymous caller would get, even while the API is off; `offered: false` flags a format the site does not offer |
+
+---
+
+## Custom endpoints (`/api/x/*`)
+
+Named, curated REST endpoints over collection data, built in the admin (**Data → API Builder**)
+or by scaffolder recipes. A definition binds a clean URL to a fixed collection query - definitions
+are data, never code.
+
+**URL anatomy:** `/api/x/<project><path>` - e.g. `/api/x/world-cup/fixtures-day/2026-06-11` for a
+definition in the `world-cup` project with `path: /fixtures-day/:date`.
+
+**Definition:**
+
+```json
+{
+  "name": "Fixtures by day",
+  "project": "world-cup",
+  "path": "/fixtures-day/:date",
+  "collection": "wc-schedule",
+  "auth": "public",
+  "mode": "list",
+  "filter": { "date": "{{params.date}}" },
+  "sort": "seq", "order": "asc", "limit": 0,
+  "fields": ["seq", "date", "title", "stage"],
+  "enabled": true
+}
+```
+
+- **`path`** - lowercase/hyphen segments or `:param` placeholders. Two endpoints in one project
+  cannot share a path *shape* (`/a/:x` and `/a/:y` collide). Static segments beat `:param`
+  matches (`/m/latest` wins over `/m/:day`).
+- **`auth`** - `"public"`, `"token"` (a project API token whose project matches the endpoint's),
+  or a role name (JWT). Same strictness rules as the collections API.
+- **`mode`** - `"list"` returns the standard `{entries, total, page, limit}` payload;
+  `"single"` returns the first matching entry, or 404.
+- **`filter`** - `{field_op: value}` clauses using the standard 12 filter operators. Values may
+  embed `{{params.<name>}}` (from a `:name` path segment - missing at request time → 400) or
+  `{{query.<name>}}` (optional - the clause is dropped when the query param is absent, so query
+  placeholders act as refinements). Substituted values only ever feed the filter engine.
+- **`fields`** - read allowlist; empty = all fields.
+- An endpoint grants access to exactly its own query - independent of the underlying collection's
+  `api` settings. System-managed collections cannot be exposed.
+
+Public-auth responses are cached and invalidated automatically when the collection's entries or
+the endpoint definition change.
+
+**Example:**
+
+```bash
+curl https://example.com/api/x/world-cup/fixtures-day/Thu%2011%20Jun
+curl -H 'Authorization: Bearer dcms_…' https://example.com/api/x/world-cup/squad/:team
+```
+
+### Endpoint management (`/api/api-endpoints/*`)
+
+| Method   | Path                     | Auth                   | Description |
+|----------|--------------------------|------------------------|-------------|
+| `GET`    | `/api/api-endpoints`     | `api-endpoints:read`   | List definitions visible to the caller (project scope applies) |
+| `GET`    | `/api/api-endpoints/:id` | `api-endpoints:read`   | Single definition |
+| `POST`   | `/api/api-endpoints`     | `api-endpoints:create` | Create (400 validation; 409 duplicate path shape) |
+| `PUT`    | `/api/api-endpoints/:id` | `api-endpoints:update` | Update - the `project` binding is immutable |
+| `DELETE` | `/api/api-endpoints/:id` | `api-endpoints:delete` | Delete - external callers get 404 immediately |
+
+Known v1 limits: GET-only; no `resolveRefs`; endpoints survive project deletion (delete them
+explicitly); a project with endpoints refuses deletion until they are removed.
+
+---
+
+## Views (`/api/views/*`)
+
+Saved Views - reusable queries over collection data, rendered in content with `[view slug="…" /]`.
+Works on every storage adapter (native aggregation on MongoDB-backed collections, built-in pipeline
+evaluator on file-backed ones). Admin endpoints require the `views` permission.
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/views` | List all view configs |
+| POST | `/api/views` | Create a view config |
+| GET | `/api/views/:slug` | Get a view config |
+| PUT | `/api/views/:slug` | Update a view config |
+| DELETE | `/api/views/:slug` | Delete a view config |
+| GET | `/api/views/:slug/execute?page&limit` | Execute a view (admin) → `{results, total, page, limit}` |
+| GET | `/api/views/collection/:collectionSlug` | List views targeting a collection |
+| GET | `/api/views/:slug/public?page&limit` | Execute a view publicly (role-checked per the view's `access` config) |
+
+View config shape: `{id, slug, title, description, connection, pipeline: {source, stages: [{type, config}]},
+display: {mode, columns, pageSize, block}, access: {roles, public, rowLevel}, meta}`. Configs are stored as
+JSON files in `content/views/`. Allowed stage types: `$match`, `$lookup`, `$sort`, `$project`, `$unwind`,
+`$limit`, `$skip`, `$count`, `$addFields`, `$group`.
+
+## Forms (`/api/forms/*`)
+
+Form definitions are JSON files in `content/forms/`; every submission is stored as an entry in the form's
+target collection (its collection action's `slug` when enabled, else a collection named after the form).
+Admin routes use the `collections` permission family - there is no separate forms permission. The list, get
+and submissions routes also apply the caller's project scope.
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/forms` | `collections:read` | List forms with `submissionCount`, `submissionsThisWeek`, `lastSubmissionAt` |
+| `POST` | `/api/forms` | `collections:create` | Create (`title` required; `201`, `409` slug taken). Also creates a same-slug collection if none exists |
+| `GET` | `/api/forms/:slug` | `collections:read` | Full definition, including `actions` |
+| `GET` | `/api/forms/:slug/public` | None | Definition without `actions` (what the `[form]` embed renders) |
+| `PUT` | `/api/forms/:slug` | `collections:update` | Shallow-merge the body over the definition; `slug`/`createdAt` fixed |
+| `DELETE` | `/api/forms/:slug` | `collections:delete` | Delete the definition (submissions stay in the collection) |
+| `POST` | `/api/forms/submit/:slug` | None (JWT optional) | Submit - see below |
+| `GET` | `/api/forms/:slug/submissions` | `collections:read` | This form's submissions, newest first |
+| `GET` | `/api/forms/:slug/submissions/export` | `collections:read` | CSV download |
+| `GET` | `/api/forms/:slug/submissions/export/json` | `collections:read` | JSON download |
+| `DELETE` | `/api/forms/:slug/submissions` | `collections:delete` | Delete all of this form's submissions |
+| `DELETE` | `/api/forms/:slug/submissions/:id` | `collections:delete` | Delete one |
+| `POST` | `/api/forms/:slug/submissions/:id/spam` | `collections:update` | `{ "spam": true \| false }` - flag or unflag |
+| `POST` | `/api/forms/test-email` | Admin (level 0-1) | Send a test email to `to` via the site SMTP settings |
+
+Create and update responses carry `warnings: [...]` when the form and its target collection disagree
+(missing collection, required collection fields the form does not collect, form fields the collection lacks).
+
+### POST `/api/forms/submit/:slug`
+
+JSON (field names as keys) or `multipart/form-data` for file fields. A valid access token, when sent,
+becomes the entry's `meta.createdBy` and the `{{user.*}}` of any Action; otherwise the submission is anonymous.
+
+**Response** `200`
+
+```json
+{ "ok": true, "entryId": "uuid", "ended": false, "message": "Thank you for your submission.", "redirect": null }
+```
+
+Order of checks:
+
+1. Honeypot (`settings.honeypot`, default on): a filled `_hp`, or `_t` (render time in ms) less than 2 s
+   ago, gets an ordinary success and nothing is stored.
+2. Triggers are resolved server-side from the same engine as the browser: `block-submit` → `400`;
+   `hide-fields` / `disable-fields` / `end-form` masking excuse fields (their values are dropped);
+   `require-fields` makes fields required.
+3. Visible fields are checked for required/validation rules → `400` `{ "error": "Required fields missing: ..." }`.
+4. Rate limit per form and IP (`settings.rateLimitPerMinute`, default 3 a minute, in memory) → `429`.
+5. The entry is stored with `meta.source: "form:<slug>"` (a missing collection is provisioned from the form).
+   An `end-form` with `record: false` stores nothing.
+6. Email, webhook (`POST {form, data}`), `settings.actionSlug` and trigger events (`run-action`, `notify`,
+   `redirect`) run after the store; their failures are logged and notified, never returned.
+
+File parts are checked against the field's `file.maxSize` (default 5 MB) and `file.accept` (MIME list,
+`image/*` wildcards), saved to the media library and stored as `{url, name, size, mime}`. There is no CAPTCHA.
+`{{entryId}}` in `settings.successRedirect` (or a trigger redirect, which wins) is replaced with the new id.
+
+---
+
+## Actions (`/api/actions/*`)
+
+Actions are configured step lists run against a collection entry. They need MongoDB (Pro): without a
+connection the admin routes answer `503` (`/api/actions/_count` answers a zero badge instead). Configs are
+stored in `cms__actions`.
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/actions` | `actions:read` | List configs (project scope applies) |
+| `POST` | `/api/actions` | `actions:create` | Create (`201`; `409` slug exists) |
+| `GET` | `/api/actions/collection/:collectionSlug` | `actions:read` | Configs targeting one collection |
+| `GET` | `/api/actions/:slug` | `actions:read` | One config |
+| `PUT` | `/api/actions/:slug` | `actions:update` | Update |
+| `DELETE` | `/api/actions/:slug` | `actions:delete` | Delete |
+| `POST` | `/api/actions/:slug/execute` | `actions:read` | Run on `{ "entryId": "..." }` |
+| `POST` | `/api/actions/:slug/check-access` | `actions:read` | `{ "entryIds": [...] }` → `{ "allowed": [...] }` after row-level rules |
+| `POST` | `/api/actions/:slug/public` | JWT + role in `access.roles` (or more senior) | Run from the public site; optional `scope: "mine"` refuses rows the user did not create (`403`) |
+| `GET` | `/api/actions/transitions?collection=&entryId=` | JWT optional | Transitions this user may run on the entry (`{ "transitions": [...] }`; none when anonymous) |
+
+**Config shape**
+
+```json
+{
+  "title": "Approve", "slug": "approve-application", "collection": "applications",
+  "trigger": { "type": "manual", "label": "Approve", "icon": "check-circle", "confirmMessage": "Approve?" },
+  "transition": { "field": "status", "from": ["pending"], "to": "approved" },
+  "steps": [
+    { "type": "updateField", "config": { "field": "status", "value": "approved" } },
+    { "type": "email", "config": { "to": "{{entry.data.email}}", "subject": "Approved" } }
+  ],
+  "access": { "roles": ["admin"], "rowLevel": null }
+}
+```
+
+**Execute response** `{ "success": true, "stepsCompleted": 2, "results": [...] }`. Errors: `400` bad input,
+`403` row-level denial or `scope: "mine"` on someone else's row, `404` missing action or entry, `409` the
+entry's `transition.field` is not in `from`.
+
+---
+
+## Scaffold (`/api/scaffold/*`)
+
+Builds a working system from a bundled recipe (`server/services/recipes/*.json`) in one call. All routes need
+`collections:create` - and nothing else, although a recipe can also create roles, users, menus, API tokens and
+endpoints. Recipe format: `docs/scaffolding.md`.
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/scaffold/recipes` | `collections:create` | `{ "recipes": [{slug, name, description, icon, options}] }` |
+| `GET` | `/api/scaffold/recipes/:slug` | `collections:create` | The full recipe, unresolved (`404` unknown) |
+| `POST` | `/api/scaffold/apply` | `collections:create` | Apply: `{ "recipe": "contact-list", "options": { "collectionSlug": "leads" } }` |
+
+Option values sent in `options` are slugified. Apply creates, in order: the project (from the `namespace`
+option, if the recipe has a `project` block), then pre-flights - an existing collection, form, Action or menu
+answers `409` with `conflicts: [...]` - then roles, menus, collection, form, users, Actions (skipped with a
+warning without MongoDB), API tokens and API endpoints.
+
+**Response** `200`
+
+```json
+{
+  "created": { "collection": "leads", "form": "contact-quick-add", "actions": ["contact-followup"],
+               "roles": [], "users": [], "menus": [], "apiTokens": [], "apiEndpoints": [] },
+  "skipped": [],
+  "warnings": [],
+  "snippet": "[form name=\"contact-quick-add\" /]\n\n..."
+}
+```
+
+Apply is not transactional: after pre-flight, anything that fails becomes a `warnings` entry and the rest
+continues. `created.apiTokens[].token` is the only time a generated token's plaintext is shown; re-applying
+never re-issues a token or overwrites an endpoint with the same path shape.
+
+---
+
+## Plugins (`/api/plugins/*`)
+
+### GET `/api/plugins`
+
+List all discovered plugins with their enabled state and settings.
+
+**Auth required:** Yes (`plugins:read`)
+
+**Response** `200` - array of plugin objects
+
+```json
+[
+  {
+    "name": "analytics",
+    "displayName": "Analytics",
+    "version": "1.0.0",
+    "description": "...",
+    "author": "...",
+    "date": "2026-03-01",
+    "icon": "chart-bar",
+    "enabled": true,
+    "settings": {}
+  }
+]
+```
+
+---
+
+### PUT `/api/plugins/:name`
+
+Enable/disable a plugin or update its settings.
+
+**Auth required:** Yes (`plugins:update`)
+
+**Request body**
+
+```json
+{ "enabled": true, "settings": { "myOption": "value" } }
+```
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+### GET `/api/plugins/admin-config`
+
+Return the merged admin sidebar items, routes, and view registrations for all enabled plugins. Used by the admin SPA on startup.
+
+**Auth required:** Yes
+
+**Response** `200`
+
+```json
+{
+  "sidebar": [...],
+  "routes": [...],
+  "views": { ... }
+}
+```
+
+---
+
+## Projects (`/api/projects/*`)
+
+Projects group related artefacts (Pages, Collections, Forms, Actions, Menus, Blocks, Views, Roles, Users) under a named slug. See `docs/configuration.md` → Projects for the data model and `meta.project` tag.
+
+All endpoints require the relevant `projects` permission. List/get results are filtered by the requesting user's `projects: []` access scope (super-admins bypass).
+
+### GET `/api/projects`
+
+List projects the user can see (scoped by `user.projects`).
+
+**Auth required:** Yes (`projects:read`)
+
+**Response** `200` - array of project records
+
+```json
+[
+  {
+    "slug":        "members",
+    "name":        "Members Area",
+    "description": "Curated members-only zone.",
+    "icon":        "users",
+    "rootUrl":     "/members",
+    "sortOrder":   10,
+    "createdAt":   "2026-05-25T10:00:00.000Z",
+    "updatedAt":   "2026-05-25T10:00:00.000Z"
+  }
+]
+```
+
+---
+
+### GET `/api/projects/:slug`
+
+Return a single project record.
+
+**Auth required:** Yes (`projects:read`)
+
+**Response** `200` - full project record (404 if not found)
+
+---
+
+### POST `/api/projects`
+
+Create a new project.
+
+**Auth required:** Yes (`projects:create`)
+
+**Request body**
+
+```json
+{
+  "slug":        "members",
+  "name":        "Members Area",
+  "description": "Members-only zone",
+  "icon":        "users",
+  "rootUrl":     "/members",
+  "sortOrder":   10
+}
+```
+
+**Response** `201` - created project record. `409` on slug collision.
+
+---
+
+### PUT `/api/projects/:slug`
+
+Update a project. The slug is immutable.
+
+**Auth required:** Yes (`projects:update`)
+
+**Request body** - any of `name`, `description`, `icon`, `rootUrl`, `sortOrder`
+
+**Response** `200` - updated project record
+
+---
+
+### DELETE `/api/projects/:slug`
+
+Delete a project. Refuses with `409` if any artefacts still carry `meta.project: <slug>`.
+
+**Auth required:** Yes (`projects:delete`)
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+**Response** `409` - conflict body includes a per-type artefact count breakdown:
+
+```json
+{
+  "error":     "Cannot delete project - tagged artefacts exist",
+  "artefacts": {
+    "pages":       3,
+    "collections": 2,
+    "forms":       1,
+    "actions":     3,
+    "menus":       1,
+    "blocks":      0,
+    "views":       0,
+    "roles":       1,
+    "users":       2
+  }
+}
+```
+
+Clear the artefacts first (manually, or via `POST /api/projects/:slug/untag-all`).
+
+---
+
+### GET `/api/projects/:slug/artefacts`
+
+Return all artefacts tagged with this project, grouped by type. Used by the sidebar and the project detail view.
+
+**Auth required:** Yes (`projects:read`)
+
+**Response** `200` - nine keys, each an array (empty arrays included):
+
+```json
+{
+  "pages":       [ ... ],
+  "collections": [ ... ],
+  "forms":       [ ... ],
+  "actions":     [ ... ],
+  "menus":       [ ... ],
+  "blocks":      [ ... ],
+  "views":       [ ... ],
+  "roles":       [ ... ],
+  "users":       [ ... ]
+}
+```
+
+---
+
+### POST `/api/projects/:slug/untag-all`
+
+Escape hatch - sets `meta.project: null` on every artefact currently tagged with the slug. Used before deleting a project when the admin doesn't want to retag artefacts individually.
+
+**Auth required:** Yes (`projects:delete`)
+
+**Response** `200`
+
+```json
+{ "success": true, "untagged": { "pages": 3, "collections": 2, "forms": 1, "actions": 3, "menus": 1, "blocks": 0, "views": 0, "roles": 1, "users": 2 } }
+```
+
+---
+
+## Layouts (`/api/layouts`)
+
+### GET `/api/layouts`
+
+Return all layout presets.
+
+**Auth required:** Yes (`layouts:read`)
+
+**Response** `200` - presets object (see `config/presets.json` in [Configuration](configuration.md))
+
+---
+
+### PUT `/api/layouts`
+
+Replace layout presets. Each preset must be an object with at least a `label` field.
+
+**Auth required:** Yes (`layouts:update`)
+
+**Response** `200`
+
+```json
+{ "success": true }
+```
+
+---
+
+### GET `/api/layouts/options`
+
+Return layout display options (e.g. spacer size).
+
+**Auth required:** Yes (`layouts:read`)
+
+**Response** `200`
+
+```json
+{ "spacerSize": 40 }
+```
+
+---
+
+### PUT `/api/layouts/options`
+
+Update layout display options.
+
+**Auth required:** Yes (`layouts:update`)
+
+**Request body**
+
+```json
+{ "spacerSize": 32 }
+```
+
+**Response** `200`
+
+```json
+{ "success": true }
+```