domma-cms 0.93.0 → 0.94.0

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

@@ -0,0 +1,225 @@
+<div class="view-header">
+  <h1><span data-icon="code"></span> API · External API</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>The external API is the stable surface for other systems: <code>/api/v1/:slug</code> reads and writes a
+    collection's entries under that collection's own access rules. It shares its handlers with
+    <code>/api/collections/:slug/public</code>, so both behave identically. For fixed, named queries at clean
+    URLs see <a href="#/docs/api/builder">API Builder</a>.</p>
+
+<h2>Endpoints</h2>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Method</th><th>Path</th><th>Verb checked</th><th>Success</th></tr>
+    </thead>
+    <tbody>
+    <tr><td><code>GET</code></td><td><code>/api/v1/:slug</code></td><td><code>read</code></td><td><code>{ entries, total, page, limit }</code></td></tr>
+    <tr><td><code>GET</code></td><td><code>/api/v1/:slug/:id</code></td><td><code>read</code></td><td>The entry</td></tr>
+    <tr><td><code>POST</code></td><td><code>/api/v1/:slug</code></td><td><code>create</code></td><td><code>201</code> + the entry</td></tr>
+    <tr><td><code>PUT</code></td><td><code>/api/v1/:slug/:id</code></td><td><code>update</code></td><td>The entry</td></tr>
+    <tr><td><code>DELETE</code></td><td><code>/api/v1/:slug/:id</code></td><td><code>delete</code></td><td><code>{ "success": true }</code></td></tr>
+    </tbody>
+</table>
+<p>Write bodies are <code>{ "data": { ... } }</code>. <strong>PUT replaces</strong> the entry's <code>data</code>
+    wholesale - send every field, not just the changed ones. Entries are validated against the collection's fields
+    (<code>400</code> with the reason); number fields sent as decimal text are stored as numbers.</p>
+
+<h3>List query parameters</h3>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Parameter</th><th>Default</th><th>Description</th></tr>
+    </thead>
+    <tbody>
+    <tr><td><code>page</code></td><td><code>1</code></td><td>Page number</td></tr>
+    <tr><td><code>limit</code></td><td><code>50</code></td><td>Page size. <code>0</code> is treated as the default, not as "everything"; ask for a larger number instead.</td></tr>
+    <tr><td><code>sort</code> / <code>order</code></td><td><code>createdAt</code> / <code>desc</code></td><td>Sort field and direction (<code>asc</code> or <code>desc</code>)</td></tr>
+    <tr><td><code>search</code></td><td>-</td><td>Substring match across all field values</td></tr>
+    <tr><td><code>filter[&lt;field&gt;]</code></td><td>-</td><td>Equality filter; add an operator suffix: <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>. Filters AND together; dot paths reach nested data.</td></tr>
+    <tr><td><code>resolveRefs</code></td><td>-</td><td><code>true</code> or <code>1</code> adds referenced entries under <code>_refs</code> (list only)</td></tr>
+    <tr><td><code>scope=mine</code></td><td>-</td><td>Only the caller's own entries. Needs a JWT and skips the <code>read</code> access rule.</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code class="language-bash">curl 'https://example.com/api/v1/jobs?filter[status]=open&amp;filter[salary_gte]=40000&amp;sort=postedAt&amp;order=desc&amp;limit=20'</code></pre>
+
+<h2>Access rules</h2>
+<p>Each verb is set on the collection under <strong>API &amp; Export</strong> in the collection editor, stored as
+    <code>schema.api.&lt;verb&gt;</code>:</p>
+<pre class="code-block"><code class="language-json">"api": {
+  "read":   { "enabled": true,  "access": "public", "fields": ["title", "location", "salary"] },
+  "create": { "enabled": true,  "access": "token" },
+  "update": { "enabled": true,  "access": "admin" },
+  "delete": { "enabled": false }
+}</code></pre>
+<table class="table table-sm">
+    <thead>
+    <tr><th><code>access</code></th><th>Who may call</th></tr>
+    </thead>
+    <tbody>
+    <tr><td><code>public</code></td><td>Anyone, no credentials.</td></tr>
+    <tr><td><code>token</code></td><td>Only a valid project API token (below). A JWT is refused.</td></tr>
+    <tr><td>a role name</td><td>A signed-in user (JWT) holding that role or a more senior one, across all their roles. A name that is not a role on the site admits only the level-0 role. An API token is refused.</td></tr>
+    </tbody>
+</table>
+<ul>
+    <li>A verb that is not <code>enabled</code> answers <code>403</code>.</li>
+    <li><code>read.fields</code> is an allowlist of <code>data</code> fields returned by external reads; empty
+        means every field. Admin endpoints are unaffected. <code>_refs</code> is not filtered.</li>
+    <li>If the collection's project is switched off, every <code>/api/v1</code> call on it answers
+        <code>404</code>.</li>
+    <li>Role and token modes grant the verb on every entry - there is no per-row ownership check on update or
+        delete.</li>
+    <li>Entries created here get <code>meta.source: "api"</code> and <code>meta.createdBy</code> set to the user's
+        id, <code>token:&lt;token id&gt;</code> for a token, or <code>null</code>.</li>
+</ul>
+
+<h2>API tokens</h2>
+<p>Tokens are machine credentials, created under <strong>System &gt; API Tokens</strong> (permission family
+    <code>api-tokens.*</code>) or by a scaffolder recipe. They are stored as entries in the file-based
+    <code>api-tokens</code> preset collection; only a SHA-256 hash and the last four characters are kept.</p>
+<ol>
+    <li>Open System &gt; API Tokens and choose <strong>New token</strong>.</li>
+    <li>Give it a <strong>name</strong> and pick its <strong>project</strong>. The project cannot be changed
+        later.</li>
+    <li>Optionally add <strong>scopes</strong>, one line per collection: <code>jobs: read</code>,
+        <code>enquiries: create, read</code>. No lines means every collection in the project; a collection with no
+        verbs means all four.</li>
+    <li>Optionally set <strong>expires</strong>. From then on every call with it is refused; the sidebar badge warns
+        14 days ahead and turns red once one has expired.</li>
+    <li>Save and <strong>copy the token now</strong> - <code>dcms_</code> followed by 64 hex characters. It is never
+        shown again; if it is lost, revoke it and make another.</li>
+</ol>
+<p>From the list you can switch a token off (refused until switched back on), edit its name, scopes and expiry, or
+    revoke it (deleted, refused at once). <code>lastUsedAt</code> is updated at most once a minute.</p>
+<p>A call with a token is accepted only when all of these hold, otherwise it is refused:</p>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Check</th><th>Refusal</th></tr>
+    </thead>
+    <tbody>
+    <tr><td>The verb's <code>access</code> is <code>token</code></td><td>role mode: <code>401</code> (a token is not a JWT); public mode ignores it</td></tr>
+    <tr><td>Header is exactly <code>Authorization: Bearer dcms_&lt;64 lower-case hex&gt;</code></td><td><code>401</code> <code>API token required</code></td></tr>
+    <tr><td>Token exists, is switched on and has not expired</td><td><code>401</code> <code>Invalid, disabled or expired API token</code></td></tr>
+    <tr><td>Token's project is the collection's project (untagged collections are <code>core</code>)</td><td><code>403</code> <code>Token is not valid for this collection's project</code></td></tr>
+    <tr><td>Scopes list this collection and verb (or the token has no scopes)</td><td><code>403</code> <code>Token scope does not permit this operation</code></td></tr>
+    </tbody>
+</table>
+
+<h2>Sending a token</h2>
+<pre class="code-block"><code class="language-bash"># Read (collection "jobs" has read.access = "token")
+curl -H 'Authorization: Bearer dcms_0123...cdef' \
+  'https://example.com/api/v1/jobs?filter[status]=open'
+# Create
+curl -X POST https://example.com/api/v1/enquiries \
+  -H 'Authorization: Bearer dcms_0123...cdef' \
+  -H 'Content-Type: application/json' \
+  -d '{"data":{"name":"Ada","email":"ada@example.com","message":"Hello"}}'
+# Replace an entry (send every field)
+curl -X PUT https://example.com/api/v1/jobs/3f2c... \
+  -H 'Authorization: Bearer dcms_0123...cdef' \
+  -H 'Content-Type: application/json' \
+  -d '{"data":{"title":"Engineer","status":"closed"}}'
+# Delete
+curl -X DELETE https://example.com/api/v1/jobs/3f2c... \
+  -H 'Authorization: Bearer dcms_0123...cdef'</code></pre>
+<p>A role-mode verb takes a user's access token instead (from <code>POST /api/auth/login</code>). Keep tokens on the
+    server: anything shipped to a browser can be read by its user.</p>
+
+<h2>Managing tokens over HTTP</h2>
+<p>All need a JWT; project scope applies (a user confined to projects sees and manages only their tokens, and gets
+    <code>403</code> for others).</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-tokens</code></td><td><code>api-tokens.read</code></td><td>List tokens (never the hash)</td></tr>
+    <tr><td><code>POST</code></td><td><code>/api/api-tokens</code></td><td><code>api-tokens.create</code></td><td>Create; <code>201</code> with <code>{ token, plaintext }</code></td></tr>
+    <tr><td><code>PUT</code></td><td><code>/api/api-tokens/:id</code></td><td><code>api-tokens.update</code></td><td>Change <code>name</code>, <code>enabled</code>, <code>scopes</code>, <code>expiresAt</code></td></tr>
+    <tr><td><code>DELETE</code></td><td><code>/api/api-tokens/:id</code></td><td><code>api-tokens.delete</code></td><td>Revoke</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code class="language-json">// POST /api/api-tokens
+{ "name": "mobile-app", "project": "core",
+  "scopes": [{ "collection": "jobs", "verbs": ["read", "create"] }],
+  "expiresAt": "2027-01-01T00:00:00.000Z" }
+// Response 201 - plaintext appears here and nowhere else
+{ "token": { "id": "uuid", "name": "mobile-app", "project": "core", "tokenHint": "cdef",
+             "scopes": [...], "enabled": true, "expiresAt": "2027-01-01T00:00:00.000Z",
+             "lastUsedAt": null, "createdBy": "Alice", "meta": {...} },
+  "plaintext": "dcms_..." }</code></pre>
+<p>The base <code>super-admin</code> and <code>admin</code> roles hold <code>api-tokens.*</code>. Custom roles are
+    not given it automatically - grant it in the role editor.</p>
+<p>Every route shares the site-wide rate limit of 500 requests a minute per IP. Browser calls from another origin
+    also need that origin allowed in <code>cors</code> in <code>config/server.json</code>.</p>
+
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,268 @@
+<div class="view-header">
+  <h1><span data-icon="code"></span> API · Forms API</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>Forms are JSON definitions stored in <code>content/forms/</code>. Every submission is stored as an entry in a
+    collection - the form's collection action target when that is switched on, otherwise a collection with the
+    form's own slug. The admin endpoints below use the <strong>collections</strong> permission family (there is no
+    separate forms permission); the submit endpoint is public.</p>
+
+<h2>Form definitions</h2>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/forms</span></h3>
+<p class="auth-note">Requires: <code>collections.read</code></p>
+<p>List form definitions the caller's project scope allows, each with <code>submissionCount</code>,
+    <code>submissionsThisWeek</code> and <code>lastSubmissionAt</code>.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/forms</span></h3>
+<p class="auth-note">Requires: <code>collections.create</code></p>
+<p>Create a form. <code>title</code> is required; <code>slug</code> is derived from it when omitted. Returns
+    <code>201</code>, or <code>409</code> when the slug is taken. A collection with the same slug is created
+    alongside it (admin-only API access) unless one already exists.</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</td></tr>
+    <tr><td><code>slug</code></td><td>string</td><td>Optional; slugified</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 (<code>name</code>, <code>label</code>, <code>type</code>, <code>required</code>, <code>logic</code>, <code>triggers</code>, <code>file</code> ...)</td></tr>
+    <tr><td><code>settings</code></td><td>object</td><td>Merged over the defaults below</td></tr>
+    <tr><td><code>actions</code></td><td>object</td><td><code>email</code>, <code>webhook</code> and <code>collection</code> blocks</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code class="language-json">{
+  "title": "Contact",
+  "fields": [
+    { "name": "name",    "label": "Name",    "type": "text",     "required": true },
+    { "name": "email",   "label": "Email",   "type": "email",    "required": true },
+    { "name": "message", "label": "Message", "type": "textarea" }
+  ],
+  "settings": {
+    "submitText": "Submit",
+    "successMessage": "Thank you for your submission.",
+    "successRedirect": "/thanks?id=&#123;&#123;entryId&#125;&#125;",
+    "layout": "grid",
+    "columns": 2,
+    "honeypot": true,
+    "rateLimitPerMinute": 3,
+    "actionSlug": ""
+  },
+  "actions": {
+    "email":      { "enabled": true, "recipients": "office@example.com", "subjectPrefix": "[Contact]" },
+    "webhook":    { "enabled": false, "url": "", "method": "POST" },
+    "collection": { "enabled": true, "slug": "contact" }
+  }
+}</code></pre>
+<p>The create and update responses carry a <code>warnings</code> array when the form and its target collection
+    disagree - the collection is missing, requires a field the form does not collect, or lacks a field the form
+    sends. Saving still succeeds.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/forms/:slug</span></h3>
+<p class="auth-note">Requires: <code>collections.read</code></p>
+<p>The full definition, including <code>actions</code>. <code>403</code> when the form belongs to a project outside
+    the caller's scope.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/forms/:slug/public</span></h3>
+<p class="auth-note">No authentication required.</p>
+<p>The definition without its <code>actions</code> block (recipients and webhook URLs stay private). This is what the
+    public <code>[form]</code> embed renders from.</p>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/forms/:slug</span></h3>
+<p class="auth-note">Requires: <code>collections.update</code></p>
+<p>Shallow-merges the body over the stored definition (send whole <code>fields</code>, <code>settings</code> and
+    <code>actions</code> objects). <code>slug</code> and <code>createdAt</code> cannot be changed.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/forms/:slug</span></h3>
+<p class="auth-note">Requires: <code>collections.delete</code></p>
+<p>Deletes the definition. Its submissions collection is left in place. Returns <code>{ "ok": true }</code>.</p>
+
+<h2>Submitting a form</h2>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/forms/submit/:slug</span></h3>
+<p class="auth-note">No authentication required. A valid access token, when sent, is recorded as the submitter.</p>
+<p>Accepts <code>application/json</code> (field names as keys) or <code>multipart/form-data</code> when the form
+    has file fields. With a JWT the entry's <code>meta.createdBy</code> is the user's id and actions receive the user
+    as <code>&#123;&#123;user.*&#125;&#125;</code>; without one the submission is anonymous.</p>
+<pre class="code-block"><code class="language-bash">curl -X POST https://example.com/api/forms/submit/contact \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Ada","email":"ada@example.com","message":"Hello"}'</code></pre>
+<pre class="code-block"><code class="language-json">// Response 200
+{ "ok": true, "entryId": "uuid", "ended": false,
+  "message": "Thank you for your submission.", "redirect": "/thanks?id=uuid" }
+// Error 400 - missing or invalid answers, or a trigger blocked the submit
+{ "error": "Required fields missing: Email." }
+// Error 404
+{ "error": "Form not found." }
+// Error 429
+{ "error": "Too many submissions. Please try again later." }</code></pre>
+<p>What happens, in order:</p>
+<ol>
+    <li>Spam checks (honeypot and timing - see Spam protection and limits).</li>
+    <li>Triggers are resolved from the answers; a <code>block-submit</code> in force answers <code>400</code>
+        with its message.</li>
+    <li>Each field that is visible (field logic) and not hidden, disabled or masked by a trigger is checked for
+        required and validation rules. Trigger-required fields count as required.</li>
+    <li>The per-IP rate limit is applied.</li>
+    <li>The visible answers are stored in the target collection with <code>meta.source: "form:&lt;slug&gt;"</code>.
+        A missing target collection is created from the form's fields rather than losing the submission. A
+        collection validation failure answers <code>400</code>.</li>
+    <li>Email, webhook (<code>{ "form": slug, "data": {...} }</code> as JSON) and the <code>settings.actionSlug</code>
+        Action run. Their failures are logged and raised as admin notifications; they never fail the
+        submission.</li>
+    <li>Trigger events run: <code>run-action</code>, <code>notify</code> and <code>redirect</code> (the first
+        redirect wins over <code>settings.successRedirect</code>). <code>&#123;&#123;entryId&#125;&#125;</code> in the redirect is
+        replaced with the new entry's id.</li>
+</ol>
+
+<h3>File uploads</h3>
+<p>Send <code>multipart/form-data</code>. A file part whose name matches a <code>type: "file"</code> field is checked
+    against that field's <code>file.maxSize</code> (bytes, default 5 MB) and <code>file.accept</code> (comma-separated
+    MIME types, wildcards such as <code>image/*</code> allowed), saved to the media library under a prefixed safe name,
+    and stored on the entry as <code>{ "url", "name", "size", "mime" }</code>. A file part for an unknown field is
+    ignored; an empty file input is skipped. The server-wide upload limit (<code>uploads.maxFileSize</code> in
+    <code>config/server.json</code>) still applies.</p>
+<pre class="code-block"><code class="language-bash">curl -X POST https://example.com/api/forms/submit/apply \
+  -F name='Ada Lovelace' \
+  -F email=ada@example.com \
+  -F 'cv=@cv.pdf;type=application/pdf'</code></pre>
+
+<h2>Spam protection and limits</h2>
+<table class="table table-sm">
+    <thead>
+    <tr><th>Check</th><th>Setting</th><th>Behaviour</th></tr>
+    </thead>
+    <tbody>
+    <tr><td>Honeypot</td><td><code>settings.honeypot</code> (default on)</td><td>A non-empty <code>_hp</code> field is answered with an ordinary success and nothing is stored.</td></tr>
+    <tr><td>Timing</td><td><code>settings.honeypot</code></td><td><code>_t</code> is the time (ms since epoch) the form was rendered. A submit under 2 seconds later is answered with success and nothing is stored.</td></tr>
+    <tr><td>Rate limit</td><td><code>settings.rateLimitPerMinute</code> (default 3)</td><td>Per form and IP address, over a rolling minute. Counted only for submissions that pass validation. <code>429</code> when exceeded. Kept in memory, so a restart resets it.</td></tr>
+    <tr><td>Global limit</td><td>-</td><td>Every route shares the site-wide limit of 500 requests a minute per IP.</td></tr>
+    </tbody>
+</table>
+<p>There is no CAPTCHA in core.</p>
+
+<h2>Triggers on the server</h2>
+<p>Field triggers (<code>field.triggers[]</code>) run in the browser, but anything they decide about submission is
+    decided again on the server from the same engine (<code>public/js/form-logic-engine.js</code>), so disabling a
+    button in the browser changes nothing:</p>
+<ul>
+    <li><strong>block-submit</strong> - refused with <code>400</code> and the trigger's message.</li>
+    <li><strong>hide-fields / disable-fields</strong> - those fields are excused from required checks and any value posted for them is
+        dropped.</li>
+    <li><strong>require-fields</strong> - those fields become required.</li>
+    <li><strong>end-form</strong> - the answers so far are the submission; masked fields are excused (also in the
+        collection's own required check) and the entry gets <code>meta.outcome</code>. With
+        <code>record: false</code> nothing is stored and email, webhook and Actions do not run. The response has
+        <code>ended: true</code> and the trigger's done message.</li>
+    <li><strong>run-action</strong>, <strong>notify</strong>, <strong>redirect</strong> - performed after the entry is
+        stored. <code>notify</code> exists only on the server (notification source
+        <code>core:form-triggers</code>).</li>
+</ul>
+
+<h2>Submissions</h2>
+<p>All submissions routes read and write the form's target collection, and only this form's entries in it (in a
+    shared collection, the ones stamped <code>meta.source: "form:&lt;slug&gt;"</code>). A form in a project outside
+    the caller's scope answers <code>404</code>.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/forms/:slug/submissions</span></h3>
+<p class="auth-note">Requires: <code>collections.read</code></p>
+<p>An array of entries, newest first. <code>[]</code> when the collection does not exist yet.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/forms/:slug/submissions/export</span></h3>
+<p class="auth-note">Requires: <code>collections.read</code></p>
+<p>CSV download (<code>&lt;slug&gt;-submissions.csv</code>): one column per field label plus <code>Date</code>.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/forms/:slug/submissions/export/json</span></h3>
+<p class="auth-note">Requires: <code>collections.read</code></p>
+<p>JSON download of the raw entries.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/forms/:slug/submissions</span></h3>
+<p class="auth-note">Requires: <code>collections.delete</code></p>
+<p>Delete every submission of this form. A shared collection keeps other forms' entries.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/forms/:slug/submissions/:id</span></h3>
+<p class="auth-note">Requires: <code>collections.delete</code></p>
+<p>Delete one submission. <code>404</code> when the entry is not this form's.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/forms/:slug/submissions/:id/spam</span></h3>
+<p class="auth-note">Requires: <code>collections.update</code></p>
+<p>Flag (<code>{ "spam": true }</code>, the default) or unflag (<code>{ "spam": false }</code>) a submission. Sets
+    <code>data.spam</code> and answers <code>{ "entry": {...}, "spam": true }</code>.</p>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/forms/test-email</span></h3>
+<p class="auth-note">Requires: an admin-level role (level 0 or 1).</p>
+<p>Send a sample submission email through the site's SMTP settings to <code>to</code> (defaults to the SMTP from
+    address). Answers <code>{ "ok": true, "message": "Test email sent to ..." }</code> or <code>500</code> with the
+    transport error.</p>
+
+    </div>
+  </div>
+</div>

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

@@ -69,53 +69,78 @@
   <div class="col-12">
     <div class="docs-body">
 
-<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/layouts</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>layouts</code> permission.</p>
-                  <p>Return all layout presets from <code>config/presets.json</code>.</p>
-                  <pre class="code-block"><code>// Response 200
-{
-  "default": { "label": "Default", "sections": [...] },
-  "full-width": { "label": "Full Width", "sections": [...] }
-}</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/layouts</span>
-                  </h3>
-                  <p class="auth-note">Requires Bearer token + <code>layouts</code> permission.</p>
-                  <p>Replace the entire layout presets object.</p>
-                  <pre class="code-block"><code>// Response 200
+<p>Layouts are the page frames a page picks with <code>layout:</code> in its frontmatter (navbar, footer, sidebar,
+    width, background). They are stored in <code>config/presets.json</code> and edited at System &gt; Layouts. The
+    endpoints need the <code>layouts</code> permission (read, or update for any change).</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/layouts</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> read permission.</p>
+<p>Every layout, keyed by name. Nine are built in: default, landing, blank, with-sidebar, minimal, article,
+    product, dashboard and wide.</p>
+<pre class="code-block"><code>// Response 200
+{ "default": { "key": "default", "label": "Default", "description": "Standard page with navbar and footer.",
+               "builtin": true, "navbar": true, "footer": true, "sidebar": false, "width": "normal",
+               "bgColor": "", "bgImage": "", "class": "" }, ... }</code></pre>
+
+<h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/layouts</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> update permission.</p>
+<p>Add a layout. Its key is made from the label.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>label</code></td><td>string</td><td>Required. Up to 60 characters</td></tr>
+    <tr><td><code>description</code></td><td>string</td><td>Up to 200 characters</td></tr>
+    <tr><td><code>navbar</code>, <code>footer</code></td><td>boolean</td><td>Show them (default true)</td></tr>
+    <tr><td><code>sidebar</code></td><td>boolean</td><td>Show a sidebar (default false)</td></tr>
+    <tr><td><code>width</code></td><td>string</td><td><code>narrow</code>, <code>normal</code> (default),
+        <code>wide</code> or <code>full</code></td></tr>
+    <tr><td><code>bgColor</code>, <code>bgImage</code>, <code>class</code></td><td>string</td><td>Background colour,
+        background picture and extra CSS classes</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 200
+{ "success": true, "key": "landing-wide", "preset": { ... } }
+// Error 409
+{ "error": "A preset with this key already exists" }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/layouts/:key</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> update permission.</p>
+<p>Change a layout (same fields; <code>label</code> is required). A built-in layout can be changed but stays
+    built in.</p>
+
+<h3><span class="method-badge method-delete">DELETE</span><span class="endpoint-path">/api/layouts/:key</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> update permission.</p>
+<p>Delete a layout you added. Built-in layouts cannot be deleted (400). A page that names a missing layout is shown
+    with <code>default</code>.</p>
+
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/layouts/_usage</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> read permission.</p>
+<p>Which pages use each layout, and which pages name a layout that does not exist.</p>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/layouts</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> update permission.</p>
+<p>Replace every layout at once. Each must be an object with a non-empty <code>label</code>; prefer the per-layout
+    routes above.</p>
+<pre class="code-block"><code>// Response 200
 { "success": true }</code></pre>
 
-                  <h3><span class="method-badge method-get">GET</span><span
-                          class="endpoint-path">/api/layouts/options</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>layouts</code> permission.</p>
-                  <p>Return layout display options stored in <code>config/site.json</code> under
-                      <code>layoutOptions</code>.</p>
-                  <pre class="code-block"><code>// Response 200
-{ "spacerSize": 8 }</code></pre>
-
-                  <h3><span class="method-badge method-put">PUT</span><span
-                          class="endpoint-path">/api/layouts/options</span></h3>
-                  <p class="auth-note">Requires Bearer token + <code>layouts</code> permission.</p>
-                  <p>Merge layout option updates into the existing options. Existing keys not included are
-                      preserved.</p>
-                  <table class="table table-sm">
-                      <thead>
-                      <tr>
-                          <th>Field</th>
-                          <th>Type</th>
-                          <th>Description</th>
-                      </tr>
-                      </thead>
-                      <tbody>
-                      <tr>
-                          <td><code>spacerSize</code></td>
-                          <td>number</td>
-                          <td>Default spacer block size in pixels</td>
-                      </tr>
-                      </tbody>
-                  </table>
-                  <pre class="code-block"><code>// Response 200
+<h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/layouts/options</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> read permission.</p>
+<p>Layout options, kept in <code>config/site.json</code> under <code>layoutOptions</code>.</p>
+<pre class="code-block"><code>// Response 200
+{ "spacerSize": 40 }</code></pre>
+
+<h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/layouts/options</span></h3>
+<p class="auth-note">Requires Bearer token + <code>layouts</code> update permission.</p>
+<p>Merge option changes; keys you leave out are kept.</p>
+<table class="table table-sm">
+    <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+    <tbody>
+    <tr><td><code>spacerSize</code></td><td>number</td><td>Default <code>[spacer]</code> size in pixels (0-500)</td></tr>
+    <tr><td><code>spacerClass</code></td><td>string</td><td>Extra CSS class on every spacer</td></tr>
+    </tbody>
+</table>
+<pre class="code-block"><code>// Response 200
 { "success": true }</code></pre>
 
     </div>