domma-cms 0.93.0 → 0.94.0

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

@@ -69,278 +69,218 @@
   <div class="col-12">
     <div class="docs-body">
 
-<p>Collections have two access planes: <strong>admin endpoints</strong> (authenticated, role-gated)
-                      and <strong>public
-                          endpoints</strong> (access level configured per collection).</p>
-
-                  <h3 style="margin-top:16px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
-                      Schema Management</h3>
-
-                  <h3><span class="method-badge method-get">GET</span><span
-                          class="endpoint-path">/api/collections</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>List all collection schemas (metadata only, no entries).</p>
-                  <pre class="code-block"><code>// Response 200
-[ { "slug": "blog", "title": "Blog Posts", "description": "...", "fields": [...] } ]</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/pro-status</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Check whether the Pro (MongoDB) storage adapter is available.</p>
-                  <pre class="code-block"><code>// Response 200 (free)
-{ "pro": false, "connections": [] }
-
-// Response 200 (pro)
-{ "pro": true, "connections": ["default", "analytics"] }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/connections</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + admin role.</p>
-                  <p>Return configured MongoDB connections from <code>config/connections.json</code>.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "default": { "type": "mongodb", "uri": "mongodb://localhost:27017", "database": "my_cms" } }</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/collections/connections</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + admin role.</p>
-                  <p>Save MongoDB connection definitions. Each connection requires <code>type</code>, <code>uri</code>,
-                      and <code>database</code>.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "success": true }
-
-// Error 400
-{ "error": "Connection \"default\" requires type, uri, and database" }</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span
-                          class="endpoint-path">/api/collections</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Create a new collection. A <code>slug</code> is auto-generated from the title if not provided.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>title</code></td>
-                          <td>string</td>
-                          <td>Required. Human-readable collection name</td>
-                      </tr>
-                      <tr>
-                          <td><code>slug</code></td>
-                          <td>string</td>
-                          <td>Optional. URL-safe identifier. Auto-generated if omitted.</td>
-                      </tr>
-                      <tr>
-                          <td><code>description</code></td>
-                          <td>string</td>
-                          <td>Optional description</td>
-                      </tr>
-                      <tr>
-                          <td><code>fields</code></td>
-                          <td>array</td>
-                          <td>Field definitions</td>
-                      </tr>
-                      <tr>
-                          <td><code>api</code></td>
-                          <td>object</td>
-                          <td>Public API access config per operation</td>
-                      </tr>
-                      <tr>
-                          <td><code>storage</code></td>
-                          <td>object</td>
-                          <td>Optional Pro: <code>{ "adapter": "mongodb", "connection": "default" }</code></td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 201 - returns the created schema object
-
+<p>Collections have two access planes: <strong>admin endpoints</strong> (<code>/api/collections/...</code>, signed-in,
+    gated by the <code>collections</code> permission for the action named - read, create, update, delete) and
+    <strong>public endpoints</strong>, gated per collection and per verb by the collection's API settings (the
+    collection editor's API &amp; Export tab). The same public endpoints are also served at <code>/api/v1/:slug</code>
+    for external programs - see <a href="#/docs/api/external">External API &amp; tokens</a>.</p>
+<p>An entry looks like this on every storage adapter:</p>
+<pre class="code-block"><code>{ "id": "uuid", "data": { "title": "..." },
+  "meta": { "createdAt": "...", "updatedAt": "...", "createdBy": "user-id", "source": "admin" } }</code></pre>
+
+<h3 style="margin-top:16px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
+    Schema Management</h3>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> read permission.</p>
+<p>Every collection schema you may see (no entries), each with its entry count.</p>
+<pre class="code-block"><code>// Response 200
+[ { "slug": "jobs", "title": "Jobs", "description": "...", "fields": [...], "entryCount": 12 } ]</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> create permission.</p>
+<p>Create a collection. The <code>slug</code> is made from the title if left out.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>title</code></td><td>string</td><td>Required. The collection's name</td></tr>
+    <tr><td><code>slug</code></td><td>string</td><td>Optional. URL-safe identifier</td></tr>
+    <tr><td><code>description</code></td><td>string</td><td>Optional</td></tr>
+    <tr><td><code>fields</code></td><td>array</td><td>Field definitions</td></tr>
+    <tr><td><code>api</code></td><td>object</td><td>Public access per verb - see Public Access below</td></tr>
+    <tr><td><code>export</code></td><td>object</td><td>Who may export from the public site's right-click menu</td></tr>
+    <tr><td><code>storage</code></td><td>object</td><td>Optional, needs MongoDB (Pro):
+        <code>{ "adapter": "mongodb", "connection": "default" }</code>. Files otherwise.</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 201 - the created schema
 // Error 409
 { "error": "A collection with that slug already exists" }</code></pre>
 
-                  <h3><span class="method-badge method-get">GET</span><span
-                          class="endpoint-path">/api/collections/:slug</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Return the schema for a single collection by slug.</p>
-
-                  <h3><span class="method-badge method-put">PUT</span><span
-                          class="endpoint-path">/api/collections/:slug</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Update a collection schema.</p>
-
-                  <h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Delete a collection and all its entries. Preset collections cannot be deleted.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "success": true }
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> read permission.</p>
+<p>One collection's schema.</p>
 
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/collections/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> update permission.</p>
+<p>Update a schema. To move a collection between file and MongoDB storage, use
+    <code>migrate-storage</code> below rather than editing <code>storage</code>, so the entries move with it.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> delete permission.</p>
+<p>Delete a collection and all its entries. Built-in (preset) collections cannot be deleted.</p>
+<pre class="code-block"><code>// Response 200
+{ "success": true }
 // Error 403
 { "error": "Cannot delete a preset collection" }</code></pre>
 
-                  <h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
-                      Admin Entry CRUD</h3>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/entries</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>List entries with pagination, sorting, and full-text search.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Query param</th>
-                          <th>Default</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>page</code></td>
-                          <td>1</td>
-                          <td>Page number</td>
-                      </tr>
-                      <tr>
-                          <td><code>limit</code></td>
-                          <td>50</td>
-                          <td>Entries per page</td>
-                      </tr>
-                      <tr>
-                          <td><code>sort</code></td>
-                          <td>createdAt</td>
-                          <td>Field to sort by</td>
-                      </tr>
-                      <tr>
-                          <td><code>order</code></td>
-                          <td>desc</td>
-                          <td><code>asc</code> or <code>desc</code></td>
-                      </tr>
-                      <tr>
-                          <td><code>search</code></td>
-                          <td>-</td>
-                          <td>Full-text search query</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
-{ "entries": [ { "id": "uuid", "data": { ... }, "createdAt": "...", "updatedAt": "..." } ], "total": 42, "page": 1, "limit": 50 }</code></pre>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/entries/:id</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Return a single entry by ID.</p>
-
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/entries</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Create a new entry. Data is validated against the collection schema.</p>
-                  <pre class="code-block"><code>// Response 201 - returns the created entry</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/collections/:slug/entries/:id</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Update an entry. Data is validated against the schema.</p>
-
-                  <h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug/entries/:id</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Delete a single entry.</p>
-                  <pre class="code-block"><code>// Response 200
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/migrate-storage</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> update permission.</p>
+<p>Move a collection's entries to file or MongoDB storage (the collection editor's Storage tab). Each entry is copied
+    as it is - the same id, data and <code>meta</code> (created and updated dates, who created it) - so references,
+    links and row ownership keep working. Nothing is moved, and nothing changes, if the target already holds an
+    entry with one of the ids or the source holds an id twice (409, with the ids in <code>collisions</code>).
+    The old copy is set aside, never deleted: <code>data.json</code> becomes <code>data.json.bak</code>, and a
+    MongoDB collection is renamed <code>cms_&lt;slug&gt;__moved_&lt;time&gt;</code>. System collections (roles, user
+    profiles, projects, notifications, API tokens and endpoints) always use files and cannot be moved (400).</p>
+<pre class="code-block"><code>// Request body
+{ "storage": { "adapter": "mongodb", "connection": "default" } }   // or { "adapter": "file" }
+// Response 200
+{ "migrated": 42, "total": 42, "archived": "..." }
+// Error 409
+{ "error": "The target storage already holds 3 of these entries ...", "collisions": ["id-1", "id-2", "id-3"] }
+// Error 503 - the MongoDB connection is not available</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/pro-status</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> read permission.</p>
+<p>Whether any database connection is set up (MongoDB storage is a Pro feature).</p>
+<pre class="code-block"><code>// Response 200
+{ "pro": true, "connections": ["default"] }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/connections</span></h3>
+<p class="auth-note">Requires Bearer token + an admin role (level 0 or 1).</p>
+<p>The MongoDB connections in <code>config/connections.json</code>. <code>PUT</code> saves them; each needs
+    <code>type</code>, <code>uri</code> and <code>database</code>.</p>
+<pre class="code-block"><code>// Response 200
+{ "default": { "type": "mongodb", "uri": "mongodb://localhost:27017", "database": "my_cms" } }
+// PUT - Error 400
+{ "error": "Connection \"default\" requires type, uri, and database" }</code></pre>
+
+<h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
+    Admin Entry CRUD</h3>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/entries</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> read permission.</p>
+<p>List entries with paging, sorting, search and filters.</p>
+<table class="table table-sm">
+    <thead><tr><th>Query param</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>page</code></td><td>1</td><td>Page number</td></tr>
+    <tr><td><code>limit</code></td><td>50</td><td>Entries per page</td></tr>
+    <tr><td><code>sort</code></td><td>createdAt</td><td>Field to sort by</td></tr>
+    <tr><td><code>order</code></td><td>desc</td><td><code>asc</code> or <code>desc</code></td></tr>
+    <tr><td><code>search</code></td><td>-</td><td>Text found in any field</td></tr>
+    <tr><td><code>filter[&lt;field&gt;]</code>, <code>filter[&lt;field&gt;_&lt;op&gt;]</code></td><td>-</td><td>Structured
+        filters, ANDed. 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>. <code>createdBy</code> and <code>id</code> work as
+        field names.</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// GET /api/collections/jobs/entries?filter[location]=London&amp;filter[salary_gte]=50000
+// Response 200
+{ "entries": [ { "id": "uuid", "data": { ... }, "meta": { ... } } ], "total": 42, "page": 1, "limit": 50 }</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/entries/:id</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> read permission.</p>
+<p>One entry.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/entries</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> create permission.</p>
+<p>Create an entry. Its <code>data</code> is checked against the schema (required fields, and that every reference
+    points at an entry that exists).</p>
+<pre class="code-block"><code>// Request body
+{ "data": { "title": "Senior Developer", "location": "London" } }
+// Response 201 - the created entry</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/collections/:slug/entries/:id</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> update permission.</p>
+<p>Update an entry. <code>data</code> replaces the stored data as a whole, so send every field.
+    <code>POST /api/collections/:slug/entries/:id/spam</code> flags one entry as spam without touching the rest.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug/entries/:id</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> delete permission.</p>
+<p>Delete one entry. Entries that referenced it are not changed; they show the reference as missing.</p>
+<pre class="code-block"><code>// Response 200
 { "success": true }</code></pre>
 
-                  <h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug/entries</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Clear all entries from a collection. Irreversible.</p>
-                  <pre class="code-block"><code>// Response 200
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug/entries</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> delete permission.</p>
+<p>Delete every entry in a collection. Cannot be undone.</p>
+<pre class="code-block"><code>// Response 200
 { "success": true }</code></pre>
 
-                  <h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
-                      Export &amp; Import</h3>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/export</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Download all entries as a file attachment.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Query param</th>
-                          <th>Values</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>format</code></td>
-                          <td><code>json</code> (default), <code>csv</code></td>
-                          <td>Export format</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200 - file download
-// Content-Disposition: attachment; filename="blog-entries.json"</code></pre>
-
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/import</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>collections</code> permission.</p>
-                  <p>Bulk-import entries from a JSON array. Existing entries are not removed.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>entries</code></td>
-                          <td>array</td>
-                          <td>Array of entry objects with a <code>data</code> field each</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Request body
+<h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
+    Export &amp; Import</h3>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/export</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> read permission.</p>
+<p>Download every entry as <code>?format=json</code> (default) or <code>?format=csv</code>.</p>
+<pre class="code-block"><code>// Response 200 - file download
+// Content-Disposition: attachment; filename="jobs-entries.json"</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/import</span></h3>
+<p class="auth-note">Requires Bearer token + <code>collections</code> create permission.</p>
+<p>Add entries from a JSON array (JSON only). Existing entries are kept. Each entry is checked like any other save -
+    required fields, and references to entries that must exist - and one that fails is skipped and reported.
+    Fields the collection does not define are stored as given.</p>
+<pre class="code-block"><code>// Request body
 { "entries": [ { "data": { "title": "Post 1" } }, { "data": { "title": "Post 2" } } ] }
-
 // Response 201
-{ "imported": 2, "skipped": 0 }</code></pre>
-
-                  <h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
-                      Public Access</h3>
-
-                  <p>Public endpoints respect the per-collection <code>api</code> config. Each operation can be <strong>disabled</strong>,
-                      <strong>public</strong> (no auth), or restricted to a minimum role level.</p>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/public</span>
-                  </h3>
-                  <p class="auth-note">Access level: per collection <code>api.read</code> config.</p>
-                  <p>List entries publicly. Supports the same pagination and search query params as the admin
-                      endpoint.</p>
-
-                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/public/:id</span>
-                  </h3>
-                  <p class="auth-note">Access level: per collection <code>api.read</code> config.</p>
-                  <p>Return a single entry publicly by ID.</p>
-
-                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/public</span>
-                  </h3>
-                  <p class="auth-note">Access level: per collection <code>api.create</code> config.</p>
-                  <p>Create an entry publicly (e.g. form submissions). Entry is tagged with <code>source: "api"</code>.
-                  </p>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/collections/:slug/public/:id</span>
-                  </h3>
-                  <p class="auth-note">Access level: per collection <code>api.update</code> config.</p>
-                  <p>Update an entry publicly.</p>
-
-                  <h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug/public/:id</span>
-                  </h3>
-                  <p class="auth-note">Access level: per collection <code>api.delete</code> config.</p>
-                  <p>Delete an entry publicly.</p>
+{ "imported": 2, "skipped": 0, "errors": [] }</code></pre>
+
+<h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
+    Public Access</h3>
+
+<p>Each verb (<code>read</code>, <code>create</code>, <code>update</code>, <code>delete</code>) has its own setting
+    in the schema's <code>api</code> block: switched off (403), <code>public</code> (no sign-in),
+    <code>token</code> (a project API token only - see <a href="#/docs/api/external">External API &amp; tokens</a>),
+    or a role name, which admits a signed-in user whose role is that senior or more. A role name the site does not
+    have admits only the level-0 role. <code>api.read.fields</code>, when set, limits which fields are returned. A
+    collection in a disabled project answers 404 on every public route.</p>
+<pre class="code-block"><code>"api": {
+  "read":   { "enabled": true,  "access": "public", "fields": ["title", "location"] },
+  "create": { "enabled": true,  "access": "user" },
+  "update": { "enabled": false, "access": "admin" },
+  "delete": { "enabled": false, "access": "admin" }
+}</code></pre>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/public</span></h3>
+<p class="auth-note">Access level: the collection's <code>api.read</code> setting.</p>
+<p>List entries. The same <code>page</code>, <code>limit</code>, <code>sort</code>, <code>order</code>,
+    <code>search</code> and <code>filter[...]</code> params as the admin endpoint, plus <code>resolveRefs=true</code>
+    to fill in referenced entries. <code>scope=mine</code> returns only the entries the signed-in user created (401
+    without a sign-in); it does not need <code>api.read</code> switched on.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/collections/:slug/public/:id</span></h3>
+<p class="auth-note">Access level: the collection's <code>api.read</code> setting.</p>
+<p>One entry.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/:slug/public</span></h3>
+<p class="auth-note">Access level: the collection's <code>api.create</code> setting.</p>
+<p>Create an entry (<code>{"data": {...&#125;&#125;</code>). It is marked <code>source: "api"</code>, and
+    <code>createdBy</code> is the signed-in user or <code>token:&lt;id&gt;</code>.</p>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/collections/:slug/public/:id</span></h3>
+<p class="auth-note">Access level: the collection's <code>api.update</code> setting.</p>
+<p>Update an entry (<code>{"data": {...&#125;&#125;</code>).</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/collections/:slug/public/:id</span></h3>
+<p class="auth-note">Access level: the collection's <code>api.delete</code> setting.</p>
+<p>Delete an entry.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/collections/render-scope</span></h3>
+<p class="auth-note">Requires a signed-in user (JWT).</p>
+<p>Used by the public site to draw a <code>[collection scope="mine"]</code> block for the signed-in visitor: only
+    their own entries. An interactive block (<code>searchable</code>, <code>sortable</code>, <code>filterable</code>
+    or <code>paginate</code>) comes back as the Collection Browser, with transition buttons when the block asks for
+    <code>transitions</code>. <code>POST /api/collections/render-fragment</code> does the same for other block-display
+    pages of the Browser, gated by <code>api.read</code>. Both take the block's attributes as base64 JSON in
+    <code>attrs</code> and answer <code>{"html": "..."}</code>.</p>
+
+<p><strong>See also:</strong> <a href="#/docs/api/external">External API &amp; tokens</a> for <code>/api/v1/:slug</code>
+    and project-scoped API tokens, and <a href="#/docs/api/builder">API Builder</a> for your own endpoints at
+    <code>/api/x/...</code>.</p>
 
     </div>
   </div>