Added in: release-2023-11
Execute Commands on Documents
Required scope:
public-api:write
Description
Execute a Document Command based on itsid
.
All commands run in a single transaction.Endpoint
PATCH api/v1/documents/:id/commands
Parameters
Name | Type | Required | Notes |
---|---|---|---|
version | integer | Current document version. When set on update the version is checked. | |
preconditions | array | An array of preconditions for command execution. If a precondition assertion fails, no commands are executed and the request responds with a 429 Conflict status.Each entry is an object with at least a type property. Possible types: - isPublished : Document is currently public- isPublishedAndHasNoChanges : Document is currently public and has no changes since last publishSee further details in example requests. | |
commands | array | x | An array of commands to execute. Each entry is an object with at least an operation property. Possible operations: - setMetadataProperty - setEditableDirective - publish .See further details in example requests. |
Example Request
{
"version": 1,
"preconditions": [
// Asserts that the document is published or
// unpublished based on the value property
{"type": "isPublished", "value": true}
// Asserts that the document is published and
// has no changes since last publish
// {"type": "isPublishedAndHasNoChanges"}
],
"commands": [
{
// update a single metadata property
"operation": "setMetadataProperty",
"propertyName": "title",
"value": "updated title", // send null to delete metadata property
"oldValue": "previous title" // optional, for conflict detection (not necessary when sending document version too)
},
{
// sets the content of an editable directive
"operation": "setEditableDirective",
"componentId": "doc-1a2b3c4d5",
"directiveName": "headline",
"value": "updated headline"
},
{
"operation": "publish"
}
]
}