Reference → Documents — Reference

Documents — Reference

The Documents surface is the platform's file-asset management plane for non-image attachments. It owns the lifecycle of PDFs, contracts, white-papers, brochures, terms documents, gated downloads, and other binary files that the site serves to visitors directly rather than rendering as media. The surface covers upload, version control, gated-download access, and the public URL generation that makes a document linkable from content pages.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a gated-content workflow. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Documents live under the Documents module in SG-Admin, separate from the Media library (which holds images and other media files that get rendered inline). The module renders three primary views — the document list, the document upload / edit form, and the per-document version history view — and exposes write operations for upload, edit, version replacement, soft delete, restore, and permanent delete.

The Documents surface differs from Media in three load-bearing ways. First, documents carry a version stack — replacing the file produces a new version while the prior version remains addressable, so an integration that linked the old URL still resolves. Second, documents can be gated, meaning the served URL checks an access rule before responding. Third, documents do not appear in image-pickers; they appear in document-picker dialogs on form / page / blog editors where attaching a PDF makes sense.

The module is paired by convention: one half renders the views and prepares the data, the other half handles uploads, version writes, and gated-download authorization. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Documents
URL prefix: /sg-admin/documents/
View templates: application/views/Admin/Documents/

The surface is intentionally scoped to non-rendered files. Image management, video, and audio live in the Media library on the adjacent surface.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Documents [+ Upload] │├──────────────────────────────────────────────────────────────────────┤│ Title Type Size Gate Updated ││ ────────────────────────── ─────── ──────── ────────── ─────── ││ Master Services Agreement PDF 412 KB Authed only 2 d ago ││ Q2 White Paper PDF 2.1 MB Public 1 w ago ││ Pricing Sheet 2026 PDF 188 KB Email-gated 3 w ago ││ Brand Guide v3 PDF 8.4 MB Public 2 m ago ││ ││ [⋯ Edit] [⋯ Replace file] [⋯ Versions] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Documents surface exposes the following operations. Each is described by what it does to the document store, not by its internal method name.

List and search

Returns the documents visible to the current operator, paginated, with title, type, size, gate setting, and last-updated columns. Supports column sort, free-text filter on title, type filter (PDF / DOCX / XLSX / other), and a gate filter (public / authed / email-gated).

Upload

Accepts a binary file plus metadata (title, description, gate type, category). The surface validates the MIME type against the allow-list configured under Settings, runs a virus scan on the bytes, stores the file under a content-addressed path, and creates a new document record pointing at the first version.

Edit metadata

Loads the document record into the form. Submit updates the title, description, category, and gate setting in place. The file content is not changed by this path — that's a separate Replace file action.

Replace file

Accepts a new binary for an existing document record. The new file is stored as a new version; the prior version is preserved but marked superseded. The document's primary URL continues to resolve to the latest version unless the integration explicitly requested a versioned URL.

Version list

Returns the version stack for a document, oldest to newest, with size, uploader, and timestamp per entry. Used by integrations that need to audit when a contract or terms document changed.

Restore version

Promotes a prior version back to "current." The promoted version becomes the one served at the primary URL. The version stack is preserved — promotion never deletes intermediate versions.

Soft delete

Marks the document inactive without removing the file. Soft-deleted documents disappear from the default list and from document-picker dialogs, but their URLs continue to resolve for a configurable grace period (default 30 days) so in-flight email links and content pages do not break instantly.

Restore

Reverses a soft delete. The document returns to the active list with all versions intact.

Permanent delete

Hard-removes the document and all its versions from storage. Available only after a soft delete plus grace-period expiry. Cited references on content pages and blog posts are flagged but not auto-removed — the platform surfaces an "orphaned link" warning under Tools → Link Audit.

Generate gated link

For email-gated or authed-only documents, generates a single-use or session-bound URL that grants access without exposing the document's permanent URL. Used by marketing automations that want to deliver a white paper after a form submission.

REQUEST /downloads/<slug>│▼┌──────────────────────────────────────┐│ Resolve document by slug │ miss → 404└─────────────────┬────────────────────┘▼┌──────────────────────────────────────┐│ Evaluate gate │└─────────────────┬────────────────────┘┌──────────┼──────────┬────────────┐▼ ▼ ▼ ▼public authed email-gated role-gatedserve session? token valid? role ok?│ yes / no yes / no yes / no▼ ▼ ▼ ▼200 OK 200 OK or 200 OK or 200 OK orredirect redirect redirectto login to capture to access page

Data model

A document record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`id`	integer	Primary key.
`title`	string	Display title. Surfaced in the document picker.
`description`	text	Optional. Used in download landing pages.
`category`	string	Optional folder-style grouping.
`gate`	enum	`public`, `authed`, `email-gated`, `role-gated`.
`gate_config`	object	Gate-specific settings (allowed roles, email-capture form id, etc.).
`current_version_id`	integer	Points into the version table.
`status`	enum	`active`, `inactive` (soft-deleted).
`created_at`	timestamp	First upload.
`updated_at`	timestamp	Last metadata or file change.

Each version carries:

Field	Type	Notes
`id`	integer	Primary key.
`document_id`	integer	Parent record.
`file_path`	string	Content-addressed storage path. Not exposed publicly.
`mime_type`	string	Detected at upload time.
`size_bytes`	integer	File size.
`sha256`	string	Content hash.
`uploaded_by`	integer	User `id`.
`uploaded_at`	timestamp	Set on upload.
`superseded_at`	timestamp	Null on current version.

Gate evaluation: the platform evaluates the gate on every request to the document URL. A public document responds immediately. An authed document checks for a valid session cookie. An email-gated document checks for a token issued by the email-capture form. A role-gated document checks the calling user's role against gate_config.allowed_roles. A failed gate returns a configurable response — either a 404-style miss or a redirect to a "request access" page, depending on the gate config.

DOCUMENT · Master Services Agreement│├── v3 (current)│ uploaded 2026-05-12 · 412 KB · sha256:b401…7d3a│├── v2 (superseded 2026-05-12)│ uploaded 2026-03-08 · 408 KB · sha256:c92f…a118│└── v1 (superseded 2026-03-08)uploaded 2025-11-20 · 395 KB · sha256:5e7d…9c40PRIMARY URL /downloads/master-services-agreement.pdf→ resolves to v3VERSIONED URL /downloads/master-services-agreement.pdf?v=2→ resolves to v2 (still served, never re-issued)

Permissions

Access to the Documents surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Documents surface.

Layer 2 — per-action capability. Within SG-Admin, each Documents action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:

Capability	Administrator	Editor	Viewer
List documents	yes	yes	yes
Upload	yes	yes	no
Edit metadata	yes	yes	no
Replace file	yes	yes	no
View versions	yes	yes	yes
Restore version	yes	yes	no
Generate gated link	yes	yes	no
Soft delete	yes	no	no
Restore	yes	no	no
Permanent delete	yes	no	no

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Self-protection rules. The surface refuses to permanently delete a document that is currently cited by ≥10 content records without an explicit override; the platform surfaces the citation list so the operator can either de-cite first or confirm the cascade impact.

Document-served gate (separate from the admin gates above). A gate on the document itself controls who can fetch the file at its public URL. Public documents serve to anyone. Authed documents require a valid session. Email-gated documents require a token from a form submission. Role-gated documents check the user's role. The four gate types compose with the admin gates, not replace them — an admin always serves a document by going through the admin upload / edit views, never through the public URL.

Audit. Every write — upload, edit, replace, version restore, gate change, delete — emits an Activity Log entry. Gated-link generation is also logged. Activity Log retention is governed by the site's general settings.

Related references

Media — Reference. Owns image / video / audio assets. Documents covers binary attachments that are downloaded, not rendered.
Forms — Reference. Email-gated documents are released by form submissions on the Forms surface. The gate_config.form_id field points there.
Pages — Reference. Pages cite documents via the document picker; the citation list drives the orphan-link warning system.
Posts — Reference. Blog posts cite documents the same way pages do.
Settings — Reference. Owns the MIME allow-list, the gate-page configuration, and Activity Log retention.
Users — Reference. Authed-only and role-gated documents resolve the caller against the user record.

For the corresponding customer-facing walkthrough — uploading a PDF, replacing a contract, gating a white paper behind an email capture — see the Documents section of the customer docs at /docs/documents.

On this page

Guides

Reference

Changelog

Roadmap