Shares
Public, optionally password-protected share links for documents.
Description
Share links let a document owner hand out a public, read-only URL to a static content snapshot without exposing the live document. Each document can have at most one active share link at a time — creating a new one replaces the existing one.
Links can optionally be password-protected (scrypt-hashed, verified with a timing-safe comparison — the hash itself is never returned by any response) and/or set to expire.
Creating a link requires the owner to have claimed a username first, since it forms the public
URL (/{username}/{slug}); without one the request fails with 400.
Authentication
| Method | Access Level | Requirement |
|---|---|---|
/shares/public/* | No session | An API key, or a whitelisted first-party origin. |
| All other routes | Authenticated | Session cookie, or API key with resume:read/resume:write. |
“Public” means no user session, not no credentials
The /shares/public/* routes do not require a logged-in user, but they are not open to
anonymous callers — a request carrying neither an API key nor a whitelisted first-party
Origin/Referer is rejected with 401.
The password-verification route is additionally rate limited to 3 attempts per 5 minutes per IP, far tighter than the rest of the API, to make protected links impractical to brute-force.
Available Endpoints
POST /shares— Create Share LinkGET /shares/documents/shared-ids— List Shared Document IDsGET /shares/documents/{documentId}— List Share Links For DocumentDELETE /shares/documents/{documentId}/links/{shareLinkId}— Revoke Share LinkGET /shares/public/{username}/{slug}— Get Public Share LinkPOST /shares/public/{username}/{slug}/verify— Verify Public Share Link Password
Delete DocumentDELETE
Soft-deletes a document by setting `deletedAt`. The document is immediately excluded from list/get responses. Hard delete and restore exist at the service layer but are not exposed through any public route. `data` is `null` on success — the deleted document is not echoed back.
Create Share LinkPOST
Creates (or replaces, if one already exists for this document) a public share link for a document. Optionally password-protected — passwords are scrypt-hashed and never returned in any response — and optionally set to expire. The caller **must have claimed a username first**, since it forms the public URL (`/{username}/{slug}`); without one the request fails with `400`. Requires the `resume:write` scope when called with an API key.