Skip to content

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 a status string.

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 typeDomain entityDescription
publishedDocumentLive published document
published-summaryDocumentSummaryPublished document without content
unpublishedUnpublishedDraft or otherwise unpublished document
unpublished-summaryUnpublishedSummaryUnpublished document without content
revisionRevisionImmutable historical snapshot
revision-summaryRevisionSummaryRevision without content
folderFolderFolder entry in a records listing
folder-summaryFolderSummaryFolder entry in a record summaries listing
documents-capabilitiesDocumentsCapabilitiesRepository 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 /.

Capabilities​

Backend capability introspection.


Get the underlying documents repository capabilities​

GET/capabilities

Responses​

Capabilities of the backing documents repository.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "documents-capabilities",
  
  
"id": "self",
  
  
"attributes": {
  
  
  
"compatibilityDate": "2024-01-01",
  
  
  
"pagination": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"versionTracking": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"changes": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Samples​


Changes​

Capability-gated change signals (sync tokens + change feed).


Get an opaque change token for a scope​

GET/sync-token

Returns 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

filter[folder]

Scope the token to a folder. Omit for the whole store. Pass the same folder to GET /changes when using the token.

Type
string

Responses​

The current sync token for the scope.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "sync-token",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"syncToken": "string",
  
  
  
"folder": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


List changes since a sync token​

GET/changes

Lists 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

filter[since]*

A sync token previously obtained from GET /sync-token or a prior GET /changes.

Type
string
Required
filter[folder]

Scope the feed to a folder. Must be the folder the filter[since] token was obtained for; omit both for the whole store.

Type
string

Responses​

Change summary collection; meta.syncToken carries the new token.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "change-summary",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"deleted": true,
  
  
  
  
"version": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
],
  
  
"syncToken": "string"
  
}
}

Samples​


Records​

Combined published + unpublished listings.


List full records (published and/or unpublished view per key)​

GET/records

Parameters​

Query Parameters

filter[type]

Which record variants to list. all lists both published and unpublished. Defaults to published.

Type
string
Valid values
"published""unpublished""all"
filter[folder]

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].

Type
string
filter[depth]

Folder recursion depth. Defaults to 1.

Type
integer
Minimum
1
page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items 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.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum 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.

Type
integer
Minimum
1
page[after]

Forward 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).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string

Responses​

Record collection with pagination links, meta.page.total when the backend reports a total, and meta.warnings for per-item recoverable errors.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "published",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"language": "string",
  
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
  
"status": "published",
  
  
  
  
"content": {
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
},
  
  
  
  
"version": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


List record summaries (lightweight listing without content)​

GET/record-summaries

Parameters​

Query Parameters

filter[type]

Which record variants to list. all lists both published and unpublished. Defaults to published.

Type
string
Valid values
"published""unpublished""all"
filter[folder]

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].

Type
string
filter[depth]

Folder recursion depth. Defaults to 1.

Type
integer
Minimum
1
page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items 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.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum 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.

Type
integer
Minimum
1
page[after]

Forward 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).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string

Responses​

Record summary collection with pagination links and meta.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "published-summary",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"language": "string",
  
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
  
"status": "published",
  
  
  
  
"version": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Published​

Published documents.


Create a published document​

POST/published

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "published",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"status": "published",
  
  
  
"language": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

Created published document; meta.warnings carries recoverable write warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "published",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "published",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Read a published document​

GET/published/{key}

Responses​

The published document.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "published",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "published",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Remove a published document​

DELETE/published/{key}

Responses​

Deletion confirmation; meta.warnings carries recoverable cleanup warnings.

application/vnd.api+json
JSON
{
  
"meta": {
  
  
"deleted": true,
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Update a published document​

PATCH/published/{key}

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "published",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"status": "published",
  
  
  
"language": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

The updated published document.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "published",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "published",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


State transition: move a published document to unpublished​

POST/published/{key}/unpublish

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"attributes": {
  
  
  
"status": "string"
  
  
}
  
}
}

Responses​

The resulting unpublished document.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Unpublished​

Unpublished drafts.


Create an unpublished draft​

POST/unpublished

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"status": "string",
  
  
  
"language": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

Created unpublished draft.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Read an unpublished draft​

GET/unpublished/{key}

Responses​

The unpublished draft.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Delete an unpublished draft​

DELETE/unpublished/{key}

Deletes the draft permanently; it is not moved to trash.

Responses​

Deletion confirmation; meta.warnings carries recoverable cleanup warnings.

application/vnd.api+json
JSON
{
  
"meta": {
  
  
"deleted": true,
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Update an unpublished draft​

PATCH/unpublished/{key}

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"status": "string",
  
  
  
"language": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

The updated unpublished draft.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "unpublished",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


State transition: publish an unpublished draft​

POST/unpublished/{key}/publish

Responses​

The resulting published document.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "published",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"status": "published",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Revisions​

Document revisions.


Create a revision for a document​

POST/revisions

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "revision",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"revision": "string",
  
  
  
"language": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

Created revision.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "revision",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"key": "string",
  
  
  
"revision": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


List revisions for a document​

GET/revisions/{key}

Parameters​

Query Parameters

page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items 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.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum 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.

Type
integer
Minimum
1
page[after]

Forward 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).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string

Responses​

Revision summary collection with pagination links and meta.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "revision-summary",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"language": "string",
  
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
  
"key": "string",
  
  
  
  
"revision": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Read a specific revision of a document​

GET/revisions/{key}/{revisionId}

Responses​

The revision.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "revision",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"language": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
"key": "string",
  
  
  
"revision": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Operations​

Fail-fast batch operations.


Batch operations (add/update/remove and publish/unpublish transitions)​

POST/operations

Fail-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​

application/vnd.api+json
JSON
{
  
"operations": [
  
  
{
  
  
  
"op": "add",
  
  
  
"data": {
  
  
  
  
"type": "published",
  
  
  
  
"id": "string",
  
  
  
  
"attributes": {
  
  
  
  
  
"status": "published",
  
  
  
  
  
"language": "string",
  
  
  
  
  
"content": {
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
},
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
}
  
  
}
  
]
}

Responses​

Results for all applied operations. Processing stopped if a repository failure occurred.

application/vnd.api+json
JSON
{
  
"results": [
  
  
{
  
  
  
"data": {
  
  
  
  
"type": "published",
  
  
  
  
"id": "string",
  
  
  
  
"attributes": {
  
  
  
  
  
"language": "string",
  
  
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
  
  
"updatedAt": "2024-01-01T00:00:00Z",
  
  
  
  
  
"status": "published",
  
  
  
  
  
"content": {
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
},
  
  
  
  
  
"version": "string"
  
  
  
  
},
  
  
  
  
"links": {
  
  
  
  
  
"self": "string",
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"warnings": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"status": "string",
  
  
  
  
  
  
"title": "string",
  
  
  
  
  
  
"detail": "string",
  
  
  
  
  
  
"source": {
  
  
  
  
  
  
  
"pointer": "string"
  
  
  
  
  
  
}
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
]
}

Samples​