Document Command API

ACCESS_TOKEN=ey1234
curl -k -X PATCH "https://server.livingdocs.io/api/2026-03/documents/{documentId}/commands" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-binary @- << EOF
  {
    "commands": [{
      "operation": "setMetadataProperty",
      "propertyName": "title",
      "value": "updated title"
    }]
  }
  EOF

{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "commands.0": "value of tag \"operation\" must be in oneOf"
  }
}
// or
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "commands.0.value": "must match exactly one schema in oneOf",
    "commands.0.value.params": "Missing required property: params"
  }
}
// or
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Command at index 0 failed: Metadata property \"notExistingProperty\" does not exist",
    "commandIndex": 0
  }
}
// or
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Command at index 0 failed: Component 'doc-123' does not exist in document '123'",
    "commandIndex": 0
  }
}
// or
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Command at index 0 failed: Directive 'my-directive' of type 'editable' does not exist on component 'doc-123' in document '123'",
    "commandIndex": 0
  }
}
// or
{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Command at index 0 failed: Include validation failed: {\"title\":\"Invalid type: expected string\",\"teasers.limit\":\"Missing required property: limit\",\"teasers.invalid\":\"Additional properties not allowed\"}",
    "commandIndex": 0
  }
}

{
  "status": 404,
  "error": "Not Found",
  "error_details": {
    "name": "NotFound",
    "message": "Document Not Found"
  }
}

{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "name": "Conflict",
    "message": "The document you tried to update is outdated",
    "expectedVersion": 1,
    "currentVersion": 2
  }
}
// or
{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "name": "Conflict",
    "message": "Precondition failed: 'isPublished'"
  }
}
// or
{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "name": "Conflict",
    "message": "Cannot update outdated value'"
  }
}

Concepts

The Document Command API lets you modify documents by sending an array of commands in a single PATCH request. All commands in a request are executed sequentially within a single transaction. If any command fails, the entire batch is rolled back and no changes are persisted.

Each command is an object with an operation property that determines its type. The commands array can contain any combination of operations, with the constraint that publish, unpublish, and addPublishSchedule must be the last command and are mutually exclusive.

Versioning and Conflict Detection

There are two mechanisms to prevent concurrent modifications from overwriting each other:

Document version: Pass the version parameter (an integer) in the request body. The server checks that this matches the current document version before executing commands. If another user modified the document since you last read it, you receive a 409 Conflict response with expectedVersion and currentVersion in the error details.

Old value checks: Individual commands that modify a value support an optional oldValue parameter. When provided, the server verifies the current value matches oldValue before applying the change. This is more granular than version checking and useful when you only care about a specific field. If the value has changed, the server returns a 409 Conflict response. Using oldValue is redundant when you also provide a document version.

Preconditions

Preconditions are assertions checked before any commands execute. If a precondition fails, the server responds with 409 Conflict and no commands run.

{
  "preconditions": [
    {"type": "isPublished", "value": true}
  ],
  "commands": [...]
}

Commands Overview

All 18 operations are grouped into three categories:

Content Commands

Commands that modify the document content tree (the livingdoc). See Content Commands for full details.

Metadata Commands

Commands that modify document metadata. See Metadata Commands for full details.

Publishing & Scheduling Commands

Commands for publication lifecycle management. See Publishing & Scheduling Commands for full details.

Error Handling

400 Bad Request

Returned when a command fails validation. The response includes commandIndex indicating which command (zero-based) failed, along with a descriptive message.

{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "message": "Command at index 0 failed: Metadata property \"title\" does not exist",
    "commandIndex": 0
  }
}

Schema validation errors (e.g. invalid operation names or missing required properties) return a different format without commandIndex:

{
  "status": 400,
  "error": "Bad Request",
  "error_details": {
    "commands.0": "value of tag \"operation\" must be in oneOf"
  }
}

404 Not Found

Returned when the document specified by documentId does not exist.

409 Conflict

Returned when:

• The document version does not match (concurrent modification)
• A precondition assertion fails
• An oldValue check fails on a specific command

{
  "status": 409,
  "error": "Conflict",
  "error_details": {
    "name": "Conflict",
    "message": "The document you tried to update is outdated",
    "expectedVersion": 1,
    "currentVersion": 2
  }
}

Related

• Authentication -- How to authenticate API requests
• API Versioning -- API version format and constraints
• Document Object -- Document structure reference
• Errors -- Error response format
• Latest Draft -- Retrieve the current draft to get component IDs and metadata values