domma-cms 0.93.0 → 0.94.0

package/admin/js/templates/docs/api-authentication.html

@@ -69,133 +69,169 @@
   <div class="col-12">
     <div class="docs-body">
 
-<h3><span class="method-badge method-get">GET</span><span
-                          class="endpoint-path">/api/auth/setup-status</span></h3>
-                  <p class="auth-note">No authentication required.</p>
-                  <p>Check whether the CMS has been set up. Returns <code>{ needsSetup: true }</code> when no users
-                      exist.</p>
-                  <pre class="code-block"><code>// Response
-{ "needsSetup": false }</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span
-                          class="endpoint-path">/api/auth/setup</span></h3>
-                  <p class="auth-note">No authentication required. Only succeeds when zero users exist.</p>
-                  <p>Create the initial admin account. Blocked once any user exists (returns 403).</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>name</code></td>
-                          <td>string</td>
-                          <td>Display name</td>
-                      </tr>
-                      <tr>
-                          <td><code>email</code></td>
-                          <td>string</td>
-                          <td>Email address</td>
-                      </tr>
-                      <tr>
-                          <td><code>password</code></td>
-                          <td>string</td>
-                          <td>Minimum 8 characters</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 201
-{ "token": "eyJ...", "refreshToken": "eyJ...", "user": { "id": "...", "name": "...", "email": "...", "role": "admin" } }</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span
-                          class="endpoint-path">/api/auth/login</span></h3>
-                  <p class="auth-note">No authentication required.</p>
-                  <p>Authenticate with email and password. Returns access and refresh tokens.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>email</code></td>
-                          <td>string</td>
-                          <td>User email</td>
-                      </tr>
-                      <tr>
-                          <td><code>password</code></td>
-                          <td>string</td>
-                          <td>User password</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
-{ "token": "eyJ...", "refreshToken": "eyJ...", "user": { "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin" } }
-
+<p>The admin signs in with a short-lived <strong>access token</strong> (sent as
+    <code>Authorization: Bearer &lt;token&gt;</code>) and a longer <strong>refresh token</strong> that gets a new
+    access token. The lifetimes are set in <code>config/auth.json</code> (default 15 minutes and 7 days). Each sign-in
+    is a <strong>session</strong> kept on disk, so signing out holds across a restart, and a new password ends the
+    account's other sessions. External programs should use an API token instead - see
+    <a href="#/docs/api/external">External API &amp; tokens</a>.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/auth/setup-status</span></h3>
+<p class="auth-note">No authentication required.</p>
+<p>Whether the site still needs its first account, plus what the sign-in screen needs to know.</p>
+<pre class="code-block"><code>// Response 200
+{ "needsSetup": false, "siteTitle": "My Site", "resetByEmail": true, "resetExpiresIn": "1 hour" }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/setup</span></h3>
+<p class="auth-note">No authentication required. Only succeeds while the site has no users.</p>
+<p>Create the first account, as the level-0 role (<code>super-admin</code>), and sign it in. Refused with 403 once
+    any user exists.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>name</code></td><td>string</td><td>Display name</td></tr>
+    <tr><td><code>email</code></td><td>string</td><td>Email address</td></tr>
+    <tr><td><code>password</code></td><td>string</td><td>At least 8 characters, and whatever further rules a plugin
+        such as Security adds</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 201
+{ "token": "eyJ...", "refreshToken": "eyJ...", "user": { "id": "...", "name": "...", "email": "...", "role": "super-admin" } }
+// Error 400 - a missing field, a bad email address or a password the rules refuse
+{ "error": "Password must be at least 8 characters" }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/login</span></h3>
+<p class="auth-note">No authentication required. Limited to 5 attempts a minute per address.</p>
+<p>Sign in with email and password. Usually answers with tokens. When a plugin adds a second step (two-factor from
+    Security, for example) it answers with a <code>challenge</code> and a five-minute <code>ticket</code> instead,
+    which is completed at <code>/api/auth/login/verify</code>.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>email</code></td><td>string</td><td>User email</td></tr>
+    <tr><td><code>password</code></td><td>string</td><td>User password</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 200 - signed in
+{ "token": "eyJ...", "refreshToken": "eyJ...",
+  "user": { "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "additionalRoles": [], "level": 1 } }
+// Response 200 - a second step is needed
+{ "challenge": { "kind": "code", "title": "Two-factor code", "label": "Code", "inputMode": "numeric", ... }, "ticket": "eyJ..." }
 // Error 401
 { "error": "Invalid credentials" }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/auth/me</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token.</p>
-                  <p>Return the authenticated user's profile.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "isActive": true }</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span
-                          class="endpoint-path">/api/auth/logout</span></h3>
-                  <p class="auth-note">No authentication required. Safe to call without a token.</p>
-                  <p>Blacklists the provided refresh token. The in-memory blacklist is cleared on server restart.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>refreshToken</code></td>
-                          <td>string</td>
-                          <td>The refresh token to revoke (optional)</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
-{ "ok": true }</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span
-                          class="endpoint-path">/api/auth/refresh</span></h3>
-                  <p class="auth-note">No authentication required. Provide a valid refresh token.</p>
-                  <p>Exchange a refresh token for a new access token.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>refreshToken</code></td>
-                          <td>string</td>
-                          <td>A valid, non-revoked refresh token</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
+<p>A successful sign-in also sets a session cookie, used only so the public site can recognise a signed-in visitor
+    (role-gated pages, draft previews). No API route accepts it in place of the Bearer token.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/login/verify</span></h3>
+<p class="auth-note">No authentication required. Provide the ticket from <code>/api/auth/login</code>.</p>
+<p>Answer a sign-in challenge. Five wrong answers end the ticket; sign in again.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>ticket</code></td><td>string</td><td>The ticket from the login response</td></tr>
+    <tr><td><code>response</code></td><td>string</td><td>The code (or recovery code)</td></tr>
+    <tr><td><code>mode</code></td><td>string</td><td><code>code</code> (default) or <code>recovery</code></td></tr>
+    <tr><td><code>trust</code></td><td>boolean</td><td>Remember this browser, where the challenge offers it</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 200 - the same as a successful /api/auth/login
+// Error 401
+{ "error": "...", "triesLeft": 4 }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/refresh</span></h3>
+<p class="auth-note">No authentication required. Provide a valid refresh token.</p>
+<p>Exchange a refresh token for a new access token. Refused once the session behind it has ended (signed out, a
+    password change, or the account made inactive).</p>
+<pre class="code-block"><code>// Request body
+{ "refreshToken": "eyJ..." }
+// Response 200
 { "token": "eyJ..." }
-
 // Error 401
-{ "error": "Invalid or expired refresh token" }</code></pre>
+{ "error": "This session has ended. Sign in again." }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/logout</span></h3>
+<p class="auth-note">No authentication required. Safe to call without a token.</p>
+<p>Ends the session the refresh token belongs to (sessions are stored on disk, so this survives a restart) and
+    clears the session cookie.</p>
+<pre class="code-block"><code>// Request body (optional)
+{ "refreshToken": "eyJ..." }
+// Response 200
+{ "ok": true }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/auth/me</span></h3>
+<p class="auth-note">Requires Bearer token.</p>
+<p>Your own account, with your profile fields (the <code>user-profiles</code> collection).</p>
+<pre class="code-block"><code>// Response 200
+{ "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "additionalRoles": [],
+  "isActive": true, "profile": { "phone": "..." } }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/auth/me</span></h3>
+<p class="auth-note">Requires Bearer token.</p>
+<p>Update your own name, email, password or profile (My Profile). A new password is checked against the site's
+    password rules and ends your other sessions. Your role cannot be changed here.</p>
+<pre class="code-block"><code>// Request body - any of
+{ "name": "Alice B", "email": "alice@example.com", "password": "...", "profile": { "phone": "..." } }
+// Response 200 - the updated account, as GET /api/auth/me
+// Error 409 - the email is already used by another account</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/me/avatar</span></h3>
+<p class="auth-note">Requires Bearer token.</p>
+<p>Upload your picture (multipart, one file; JPEG, PNG, WebP or GIF, up to 8 MB). It is stored as a 256 px WebP.
+    <code>DELETE /api/auth/me/avatar</code> removes it. Pictures are served at
+    <code>GET /api/auth/avatar/:name</code>.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/auth/permissions</span></h3>
+<p class="auth-note">Requires Bearer token.</p>
+<p>What you may do: the permissions of every role you hold combined (a bare name such as <code>pages</code> means every action on it; <code>resource.action</code> one action), whether your roles confine you to a few admin
+    screens (<code>adminScope</code>, <code>null</code> for the whole admin), and the screen the admin opens on.</p>
+<pre class="code-block"><code>// Response 200
+{ "permissions": ["pages", "media", "contacts.read", ...], "adminScope": null, "adminHome": "#/" }</code></pre>
+<p><code>GET /api/auth/permissions-registry</code> lists every permission the role editor can grant, including
+    those added by plugins.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/auth/sessions</span></h3>
+<p class="auth-note">Requires Bearer token.</p>
+<p>Your sessions - where and when you are signed in - with the one you are using marked <code>current</code>.
+    <code>DELETE /api/auth/sessions/:sid</code> ends one; <code>POST /api/auth/sessions/revoke-others</code> signs you
+    out everywhere else.</p>
+<pre class="code-block"><code>// Response 200
+[ { "sid": "...", "createdAt": "...", "lastUsedAt": "...", "expiresAt": "...", "ip": "...", "ua": "...", "current": true } ]
+// POST /api/auth/sessions/revoke-others - Response 200
+{ "ok": true, "ended": 2 }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/forgot-password</span></h3>
+<p class="auth-note">No authentication required. Limited to 3 requests an hour.</p>
+<p>Ask for a password reset email. It answers at once and the same way whether or not the address has an account;
+    the email is sent afterwards, and at most 3 an hour go to any one account. The link is built on the Site URL
+    (Site Settings, General).</p>
+<pre class="code-block"><code>// Request body
+{ "email": "alice@example.com" }
+// Response 200
+{ "ok": true, "expiresIn": "1 hour" }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/reset-password/check</span></h3>
+<p class="auth-note">No authentication required. Provide the token from the reset link.</p>
+<p>Is the link still good, and (with a <code>password</code>) what the password rules make of a new password as it
+    is typed.</p>
+<pre class="code-block"><code>// Request body
+{ "token": "...", "password": "optional" }
+// Response 200
+{ "email": "alice@example.com", "expiresAt": "...", "minutesLeft": 42, "problems": [] }
+// Error 400
+{ "error": "Invalid or expired reset link", "expired": true }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/auth/reset-password</span></h3>
+<p class="auth-note">No authentication required. Provide the token from the reset link.</p>
+<p>Set a new password. The link is used up, every session of the account ends, and the account holder is emailed
+    that the password changed.</p>
+<pre class="code-block"><code>// Request body
+{ "token": "...", "password": "new password" }
+// Response 200
+{ "ok": true }
+// Error 400
+{ "error": "Invalid or expired reset link", "expired": true }</code></pre>
+<p>Administrators send, copy or withdraw reset links for other users with
+    <a href="#/docs/api/users">the Users API</a>.</p>
 
     </div>
   </div>

package/admin/js/templates/docs/api-builder.html

@@ -0,0 +1,197 @@
+<div class="view-header">
+  <h1><span data-icon="code"></span> API · API Builder</h1>
+  <a href="#/api-reference" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> API overview</a>
+</div>
+<style>
+    .method-badge {
+        display: inline-block;
+        font-size: 11px;
+        font-weight: 700;
+        letter-spacing: 0.5px;
+        padding: 2px 7px;
+        border-radius: 4px;
+        font-family: var(--dm-font-mono, monospace);
+        margin-right: 6px;
+        vertical-align: middle;
+    }
+
+    .method-get {
+        background: color-mix(in srgb, var(--dm-success) 15%, transparent);
+        color: var(--dm-success);
+    }
+
+    .method-post {
+        background: color-mix(in srgb, var(--dm-primary) 15%, transparent);
+        color: var(--dm-primary);
+    }
+
+    .method-put {
+        background: color-mix(in srgb, var(--dm-warning) 15%, transparent);
+        color: var(--dm-warning-dark);
+    }
+
+    .method-patch {
+        background: color-mix(in srgb, var(--dm-info) 15%, transparent);
+        color: var(--dm-info);
+    }
+
+    .method-delete {
+        background: color-mix(in srgb, var(--dm-danger) 15%, transparent);
+        color: var(--dm-danger);
+    }
+
+    .endpoint-path {
+        font-family: var(--dm-font-mono, monospace);
+        font-size: 14px;
+    }
+
+    .auth-note {
+        font-size: 12px;
+        color: var(--dm-text-muted, #6b7280);
+        margin: 4px 0 12px;
+    }
+
+    .auth-note code {
+        font-size: 11px;
+    }
+
+    .docs-body h3 {
+        margin-top: 24px;
+        margin-bottom: 8px;
+    }
+
+    .docs-body h3:first-child {
+        margin-top: 0;
+    }
+</style>
+
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>API Builder publishes named, read-only endpoints over collection data at
+    <code>/api/x/&lt;project&gt;&lt;path&gt;</code> - for example <code>/api/x/world-cup/fixtures-day/:date</code>.
+    A definition is data, never code: it binds a path to one fixed collection query. An endpoint grants access to
+    exactly that query, whatever the collection's own <a href="#/docs/api/external">external API</a> settings say.</p>
+
+<h2>How it works</h2>
+<ul>
+    <li>Definitions are entries in the file-based <code>api-endpoints</code> preset collection, edited under
+        <strong>Data &gt; API Builder</strong> (permission family <code>api-endpoints.*</code>) or created by a
+        scaffolder recipe (<code>apiEndpoints: [...]</code>).</li>
+    <li>The first URL segment after <code>/api/x/</code> is the endpoint's project; the rest is matched against
+        its <code>path</code>. Static segments beat <code>:param</code> segments, so <code>/m/latest</code> wins
+        over <code>/m/:day</code>.</li>
+    <li>An endpoint may only expose a collection in its own project or in <code>core</code>, and never a
+        system-managed or preset collection (roles, users, API tokens and so on).</li>
+    <li>Only <code>GET</code> is served. An unknown project, unknown path or switched-off endpoint answers
+        <code>404</code> identically; so does every endpoint of a switched-off project.</li>
+    <li>Endpoints are project artefacts: a project that still has endpoints cannot be deleted.</li>
+</ul>
+
+<h2>The API Builder screen</h2>
+<p><strong>Data &gt; API Builder</strong> lists the endpoints you can see (your project scope applies), with the
+    public ones counted on the sidebar badge. The editor has three tabs and a try-it console:</p>
+<ul>
+    <li><strong>Definition</strong> - name, project (fixed once saved), path, collection, auth and mode.</li>
+    <li><strong>Query</strong> - filter rows (field, operator, value; a value can use a <code>:param</code> or a
+        query placeholder), sort, order and limit.</li>
+    <li><strong>Response fields</strong> - tick the fields the endpoint returns. None ticked returns every
+        field.</li>
+    <li><strong>Try it</strong> - calls the <em>saved</em> definition with the path parameters and query you enter,
+        keeps a history, and copies a request as curl. Save first to test a change. For a token endpoint, paste a
+        token.</li>
+</ul>
+
+<h2>Definition</h2>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Field</th><th>Default</th><th>Rules</th></tr>
+    </thead>
+    <tbody>
+    <tr><td><code>name</code></td><td>-</td><td>Required</td></tr>
+    <tr><td><code>project</code></td><td>-</td><td>Required, must exist; cannot be changed after creation</td></tr>
+    <tr><td><code>path</code></td><td>-</td><td>Starts with <code>/</code>; segments are lower-case letters, digits and hyphens, or <code>:name</code>. Two endpoints in one project cannot share a path shape (<code>/a/:x</code> and <code>/a/:y</code> collide - <code>409</code>).</td></tr>
+    <tr><td><code>collection</code></td><td>-</td><td>Required; own project or <code>core</code>; not system-managed</td></tr>
+    <tr><td><code>auth</code></td><td><code>public</code></td><td><code>public</code>, <code>token</code> or an existing role name</td></tr>
+    <tr><td><code>mode</code></td><td><code>list</code></td><td><code>list</code> returns <code>{ entries, total, page, limit }</code>; <code>single</code> returns the first match or <code>404</code></td></tr>
+    <tr><td><code>filter</code></td><td><code>{}</code></td><td><code>{ "field_op": value }</code> with the standard operators (<code>_eq</code>, <code>_ne</code>, <code>_gt</code>, <code>_gte</code>, <code>_lt</code>, <code>_lte</code>, <code>_in</code>, <code>_nin</code>, <code>_contains</code>, <code>_starts</code>, <code>_ends</code>, <code>_exists</code>). Values are strings, numbers or booleans.</td></tr>
+    <tr><td><code>sort</code> / <code>order</code></td><td><code>createdAt</code> / <code>desc</code></td><td>Order is <code>asc</code> or <code>desc</code></td></tr>
+    <tr><td><code>limit</code></td><td><code>50</code></td><td>Integer 0-500; <code>0</code> means no limit</td></tr>
+    <tr><td><code>fields</code></td><td><code>[]</code></td><td>Response allowlist of <code>data</code> fields; empty returns all</td></tr>
+    <tr><td><code>enabled</code></td><td><code>true</code></td><td>Off answers <code>404</code></td></tr>
+    </tbody>
+</table>
+<p>Filter values may carry placeholders:</p>
+<ul>
+    <li><code>&#123;&#123;params.name&#125;&#125;</code> - from a <code>:name</code> path segment. It must exist in the path (checked on
+        save); empty at request time answers <code>400</code>.</li>
+    <li><code>&#123;&#123;query.name&#125;&#125;</code> - from <code>?name=</code>. When absent, the whole clause is dropped, so it works
+        as an optional refinement.</li>
+</ul>
+<pre class="code-block"><code class="language-json">{
+  "name": "Fixtures by day",
+  "project": "world-cup",
+  "path": "/fixtures-day/:date",
+  "collection": "wc-schedule",
+  "auth": "public",
+  "mode": "list",
+  "filter": { "date": "&#123;&#123;params.date&#125;&#125;", "stage": "&#123;&#123;query.stage&#125;&#125;" },
+  "sort": "seq", "order": "asc", "limit": 0,
+  "fields": ["seq", "date", "title", "stage"],
+  "enabled": true
+}</code></pre>
+
+<h2>Calling an endpoint</h2>
+<p>List-mode endpoints also accept, within the definition's bounds:</p>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Query</th><th>Effect</th></tr>
+    </thead>
+    <tbody>
+    <tr><td><code>page</code></td><td>Page number</td></tr>
+    <tr><td><code>limit</code></td><td>Smaller pages; never above the definition's <code>limit</code> (or 500 when that is 0)</td></tr>
+    <tr><td><code>sort</code> / <code>order</code></td><td>Sort by any field the endpoint returns</td></tr>
+    <tr><td><code>&lt;field&gt;_&lt;op&gt;=value</code></td><td>Extra filters on fields the endpoint returns (no <code>filter[...]</code> wrapper). A field the definition already filters on cannot be overridden.</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code class="language-bash"># Public, list mode
+curl 'https://example.com/api/x/world-cup/fixtures-day/2026-06-11?stage=group&amp;limit=10'
+# Token auth
+curl -H 'Authorization: Bearer dcms_0123...cdef' \
+  https://example.com/api/x/world-cup/squad/eng
+# Role auth - a user's access token
+curl -H 'Authorization: Bearer eyJ...' https://example.com/api/x/members/directory</code></pre>
+<p>Auth follows the same rules as the <a href="#/docs/api/external">external API</a>:</p>
+<ul>
+    <li><strong>public</strong> - anyone. These responses are cached and refreshed automatically when the
+        collection's entries or the definition change.</li>
+    <li><strong>token</strong> - a project API token whose project is the endpoint's project. Scopes are checked
+        against the endpoint's collection with the <code>read</code> verb. A JWT is refused.</li>
+    <li><strong>role name</strong> - a signed-in user with that role or a more senior one.</li>
+</ul>
+<p>Errors: <code>401</code>/<code>403</code> from auth, <code>400</code> for a missing path parameter,
+    <code>404</code> for no such endpoint or no match in single mode.</p>
+
+<h2>Managing endpoints over HTTP</h2>
+<p>All need a JWT; project scope applies to the endpoint and to the collection it queries (<code>403</code>
+    otherwise).</p>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Method</th><th>Path</th><th>Permission</th><th>Description</th></tr>
+    </thead>
+    <tbody>
+    <tr><td><code>GET</code></td><td><code>/api/api-endpoints</code></td><td><code>api-endpoints.read</code></td><td>List definitions</td></tr>
+    <tr><td><code>GET</code></td><td><code>/api/api-endpoints/:id</code></td><td><code>api-endpoints.read</code></td><td>One definition</td></tr>
+    <tr><td><code>POST</code></td><td><code>/api/api-endpoints</code></td><td><code>api-endpoints.create</code></td><td>Create; <code>201</code>, <code>400</code> invalid, <code>409</code> duplicate path shape</td></tr>
+    <tr><td><code>PUT</code></td><td><code>/api/api-endpoints/:id</code></td><td><code>api-endpoints.update</code></td><td>Update the fields sent; <code>project</code> is ignored</td></tr>
+    <tr><td><code>DELETE</code></td><td><code>/api/api-endpoints/:id</code></td><td><code>api-endpoints.delete</code></td><td>Delete; the URL answers <code>404</code> at once</td></tr>
+    </tbody>
+</table>
+<p>The base <code>super-admin</code> and <code>admin</code> roles hold <code>api-endpoints.*</code>; custom roles
+    need it granted in the role editor.</p>
+
+    </div>
+  </div>
+</div>