Documents API

Household-scoped search, correction, lifecycle, and reprocessing

📄️Search and browse household documents

Filters and the opaque keyset cursor are bound together. Full-text search uses the current canonical search projection; direct detail and original access remain available when an index warning is reported.

📄️Apply one organization action atomically

One to one hundred unique document/revision pairs are preflighted in the authenticated household before any new canonical generation is written. A stale or invalid target rolls back the entire request.

📄️Permanently delete one explicitly trashed document

Shared blobs and externally referenced derived data are protected. Physical blob candidates remain subject to a reference recheck.

📄️Read authorized document detail

Requires documents.read and the current document ACL. Unknown and unauthorized identifiers are indistinguishable; the response includes canonical detail and history with a strong revision ETag.

📄️Publish authoritative household corrections

Requires documents.update, document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. A successful patch publishes a new canonical generation; immutable original bytes are never rewritten.

📄️Archive a document

Requires documents.archive, document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. Only an active document can transition to archived.

📄️Read an integrity-checked immutable original

Defaults to a forced download. Passing `disposition=inline` asks the browser to render the same authenticated, already-refused-if-dangerous bytes in place instead, for a household previewing its own document.

📄️Read a bounded safe derived preview

Only UTF-8 plain text or an explicitly registered integrity-checked AVIF/JPEG/PNG/WebP artifact is returned. Active PDF, HTML, and SVG are never embedded.

📄️Queue a new durable core processing run

The current canonical generation remains authoritative until the new run publishes N+1. Repeating the same scoped Idempotency-Key returns the same receipt; a compatible active run may be coalesced.

📄️Restore a trashed or archived document

Requires document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. Restoring an archived document requires documents.archive; restoring a trashed document requires documents.trash and returns it to its saved active or archived state.

📄️Retry the latest terminally failed search projection

The authorized, same-origin recovery command is fenced by the current strong document revision. It keeps the canonical generation and original directly available while a durable projection job retries.

📄️Move a document to recoverable trash

Requires documents.trash, document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. Active and archived documents may enter trash, and their prior lifecycle is retained for restoration.

📄️Read bounded material differences after publication

Requires documents.read and current read access to the run's document. Results exist only after successful publication; unknown, foreign-household, and no-longer-accessible run identifiers are indistinguishable as 404.