Documents API
The Documents API serves versioned content with a publish/unpublish lifecycle. A document is in one of two states:
- Published (
type: "published"): live, public content. - Unpublished (
type: "unpublished"): drafts, pending-review, archived, or trashed content, told apart by astatusstring.
A revision is an immutable snapshot of a document, created with POST /revisions. Its id is the document key and the revision identifier joined by / (posts/hello/v1). Mount a documents repository with buildJsonApi from contentia/documents/api. Like every Contentia API server, it requires an access policy.
| JSON:API type | Domain entity | Description |
|---|---|---|
published | Document | Live published document |
published-summary | DocumentSummary | Published document without content |
unpublished | Unpublished | Draft or otherwise unpublished document |
unpublished-summary | UnpublishedSummary | Unpublished document without content |
revision | Revision | Immutable historical snapshot |
revision-summary | RevisionSummary | Revision without content |
folder | Folder | Folder entry in a records listing |
folder-summary | FolderSummary | Folder entry in a record summaries listing |
documents-capabilities | DocumentsCapabilities | Repository capabilities; returned by GET /capabilities |
Keys and revision identifiers that contain / are percent-encoded in URLs: posts/hello-world becomes posts%2Fhello-world. A document created without a language gets und (undetermined). The API also describes itself at GET /.
Get the underlying documents repository capabilities
/capabilitiesResponses
Capabilities of the backing documents repository.
/capabilitiesSamples
Get an opaque change token for a scope
/sync-tokenReturns a token that changes whenever anything inside the scope (a folder, or the whole store when filter[folder] is omitted) changes. Compare tokens only by equality. Capability-gated: backends without change-signal support answer 501 (consult GET /capabilities, changes).
Parameters
Query Parameters
Scope the token to a folder. Omit for the whole store. Pass the same folder to GET /changes when using the token.
Responses
The current sync token for the scope.
/sync-tokenSamples
List changes since a sync token
/changesLists what changed inside the scope since a previously obtained sync token: one change-summary per changed key, carrying its latest state, not one per change event. The feed is not paginated. meta.syncToken carries the new token to resume from. Capability-gated: backends without a change feed answer 501 (consult GET /capabilities, changes).
Parameters
Query Parameters
A sync token previously obtained from GET /sync-token or a prior GET /changes.
Scope the feed to a folder. Must be the folder the filter[since] token was obtained for; omit both for the whole store.
Responses
Change summary collection; meta.syncToken carries the new token.
/changesSamples
List full records (published and/or unpublished view per key)
/recordsParameters
Query Parameters
Which record variants to list. all lists both published and unpublished. Defaults to published.
"published""unpublished""all"Folder to list: a collection name, or a path inside one such as posts/drafts. Empty or omitted lists the root, which depends on the backend: the catalog backend returns one folder item per document collection; the drizzle and obsidian backends return the records under the root, to filter[depth].
Folder recursion depth. Defaults to 1.
1Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 10 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.
1Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Responses
Record collection with pagination links, meta.page.total when the backend reports a total, and meta.warnings for per-item recoverable errors.
/recordsSamples
List record summaries (lightweight listing without content)
/record-summariesParameters
Query Parameters
Which record variants to list. all lists both published and unpublished. Defaults to published.
"published""unpublished""all"Folder to list: a collection name, or a path inside one such as posts/drafts. Empty or omitted lists the root, which depends on the backend: the catalog backend returns one folder item per document collection; the drizzle and obsidian backends return the records under the root, to filter[depth].
Folder recursion depth. Defaults to 1.
1Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 10 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.
1Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Responses
Record summary collection with pagination links and meta.
/record-summariesSamples
Create a published document
/publishedRequest Body
Responses
Created published document; meta.warnings carries recoverable write warnings.
/publishedSamples
Read a published document
/published/{key}Responses
The published document.
/published/{key}Samples
Remove a published document
/published/{key}Responses
Deletion confirmation; meta.warnings carries recoverable cleanup warnings.
/published/{key}Samples
Update a published document
/published/{key}Request Body
Responses
The updated published document.
/published/{key}Samples
State transition: move a published document to unpublished
/published/{key}/unpublishRequest Body
Responses
The resulting unpublished document.
/published/{key}/unpublishSamples
Create an unpublished draft
/unpublishedRequest Body
Responses
Created unpublished draft.
/unpublishedSamples
Read an unpublished draft
/unpublished/{key}Responses
The unpublished draft.
/unpublished/{key}Samples
Delete an unpublished draft
/unpublished/{key}Deletes the draft permanently; it is not moved to trash.
Responses
Deletion confirmation; meta.warnings carries recoverable cleanup warnings.
/unpublished/{key}Samples
Update an unpublished draft
/unpublished/{key}Request Body
Responses
The updated unpublished draft.
/unpublished/{key}Samples
State transition: publish an unpublished draft
/unpublished/{key}/publishResponses
The resulting published document.
/unpublished/{key}/publishSamples
Create a revision for a document
/revisionsRequest Body
Responses
Created revision.
/revisionsSamples
List revisions for a document
/revisions/{key}Parameters
Query Parameters
Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 10 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.
1Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Responses
Revision summary collection with pagination links and meta.
/revisions/{key}Samples
Read a specific revision of a document
/revisions/{key}/{revisionId}Responses
The revision.
/revisions/{key}/{revisionId}Samples
Batch operations (add/update/remove and publish/unpublish transitions)
/operationsFail-fast batch. Every operation is checked for request shape before any I/O: a shape-invalid op (e.g. an add without data.id, or an unpublished add without data.attributes.status) returns 400 with zero writes. Every operation is then authorized before any write: one denial fails the whole batch with 403 and nothing is written. Ops then run in order, and the first repository failure stops processing; ops applied before it stay applied. This is a fail-fast batch, not a transaction.
Request Body
Responses
Results for all applied operations. Processing stopped if a repository failure occurred.
/operations