Publishing & Scheduling Commands

Publishing commands manage the document's publication lifecycle, including immediate publishing/unpublishing, embargoes, and scheduled publication actions.

Configuration

Embargo, publish schedules, and unpublish schedules must be enabled per content type via the publishControl configuration. They are all disabled by default. If you attempt to use a command whose feature is not enabled, the server returns a 400 Bad Request with a specific error code (EMBARGO_DISABLED, PUBLISH_SCHEDULE_DISABLED, or UNPUBLISH_SCHEDULE_DISABLED).

Command ordering

The publish, unpublish, and addPublishSchedule commands can only be used as the last command in a request and are mutually exclusive. You cannot combine these three operations in the same request.

All other publishing commands (setEmbargo, removeEmbargo, cancelPublishSchedule, addUnpublishSchedule, cancelUnpublishSchedule) can appear at any position in the commands array.

Embargo interactions

An active embargo prevents immediate publishing and can block scheduled publishing:

• Indefinite embargo (no until date): blocks publish and addPublishSchedule entirely.
• Timed embargo (with until date): blocks publish before the embargo expiry and blocks addPublishSchedule if the scheduled date is before the embargo expiry.
• Embargo can only be set on unpublished documents. Attempting to set an embargo on a published document returns an error.
• If a scheduled publish fires while an embargo is still active, the publish is silently skipped.

Schedule interactions

When both a publish schedule and an unpublish schedule are set, the publish schedule date must be before the unpublish schedule date.

publish

Creates a new publication for the document. The current draft becomes the published version. This triggers any configured publication hooks and delivery processes.

Parameters

Example

{
  "operation": "publish"
}

Typical usage combines content/metadata changes with a publish as the final command:

{
  "version": 1,
  "commands": [
    {
      "operation": "setMetadataProperty",
      "propertyName": "title",
      "value": "Updated title"
    },
    {
      "operation": "publish"
    }
  ]
}

Validation

• Must be the last command in the commands array.
• Cannot be combined with unpublish or addPublishSchedule in the same request.
• Blocked if the document has an active embargo that has not expired.

unpublish

Unpublishes the document if it is currently published. After unpublishing, the document is no longer publicly accessible.

Parameters

Example

{
  "operation": "unpublish"
}

Validation

• Must be the last command in the commands array.
• Cannot be combined with publish or addPublishSchedule in the same request.

setEmbargo

Sets an embargo on the document. An embargo prevents publishing until it is removed or expires, typically used in news workflows to control when content can be shared with the public.

Parameters

Example

{
  "operation": "setEmbargo",
  "reason": "Press release not yet public",
  "until": "2025-06-15T09:00:00Z"
}

Validation

• Can only be set on unpublished documents.

removeEmbargo

Removes an existing embargo from the document, allowing it to be published again.

Parameters

Example

{
  "operation": "removeEmbargo"
}

addPublishSchedule

Schedules the document for automatic publication at a future date. The document will be published when the scheduled time is reached, unless an active embargo prevents it.

Parameters

Example

{
  "operation": "addPublishSchedule",
  "date": "2025-06-15T09:00:00Z"
}

Validation

• Must be the last command in the commands array.
• Cannot be combined with publish or unpublish in the same request.
• Blocked if the document has an active embargo that expires after the scheduled date.
• The publish schedule date must be before any existing unpublish schedule date.

cancelPublishSchedule

Cancels a previously scheduled publication.

Parameters

Example

{
  "operation": "cancelPublishSchedule"
}

addUnpublishSchedule

Schedules the document for automatic unpublication at a future date. The document will be unpublished when the scheduled time is reached.

Parameters

Example

{
  "operation": "addUnpublishSchedule",
  "date": "2025-12-31T23:59:59Z"
}

Validation

• The unpublish schedule date must be after any existing publish schedule date.

cancelUnpublishSchedule

Cancels a previously scheduled unpublication.

Parameters

Example

{
  "operation": "cancelUnpublishSchedule"
}

Related

• Publication Events -- Subscribe to publication change events
• Latest Publication -- Retrieve the current published version