Manage content using the REST API

The Content API lets you manage content items and their versions in Optimizely CMS (SaaS) programmatically. The following sections describe how to create, copy, retrieve, update, transition the status of, and delete content through the API.

You can create a content item using the Content API with an initial content version.

The request must contain a contentType, container, and displayName. If the content type is localized, it must also contain a locale.

See Create contentCreate content API Reference.

Use the content API to create a content item as a copy of an existing content item. A copy includes items contained under the content item. The content API copies only each content item's published or latest version and locale.

The copy is created in the same container as the original unless the container parameter is provided.

You can specify an owner to assign the copied content as an asset of another content item.

The container and owner fields are mutually exclusive.

To make a copy of a deleted content item you must include the cms-accept-resource header with a deleted or * value.

See Copy contentCopy content API reference.

You can retrieve content node information (shared by all versions) by using the content API with the unique key of the content item.

See Get content nodeGet content node API reference.

Use the path API to retrieve the content hierarchy of a content item

This method returns a list of content items that creates the hierarchical path to the content. This list includes the requested content. It returns an empty list if it does not find content with the provided key.

See Get content pathGet content path API reference.

Use the items API to retrieve the content hierarchy of a content item.

Use the contentTypes parameter to filter the list based on content types or base types such as page.

See List content itemsList content items API reference.

Use the Content API to move a content item to another container by updating the container field.

See Patch contentPatch content API reference.

Use versions to retrieve a list of content versions through the Content API by providing the unique key of the content item.

You can filter the list on locales and statuses.

See List versionsList versions API reference.

Use the content key and the version identifier to retrieve a specific content version.

See Get versionGet version API reference.

You can update an existing content version using the Content API.

See Update versionUpdate version API reference.

You can also create a new version of an existing content item.

To create a locale version of an existing content item, provide a new locale.

See Create versionCreate version API reference.

The Content API lets you transition a version between statuses using dedicated endpoints. You cannot change the status field through PATCH.

When you create content, omit the status field from initialVersion. New content starts in draft status, and you must use the dedicated status transition endpoints (:ready, :publish, :draft, :approve, :reject) to change the status.

All transition endpoints support optimistic concurrency checks through ETags. You should provide an If-Match precondition header with the ETag of the content version you want to update anytime that you call a transition endpoint.

Transition a draft version to ready status. If an approval workflow is configured, the system automatically submits the version for approval and transitions it to inReview instead.

You can include an optional request body with a comment (max 255 characters). When an approval definition exists and the version transitions to inReview, the comment is attached to the approval start. If the approval definition requires a comment at start, the comment field is mandatory.

Publish a version to make it the live version. Publishing moves any existing published version to previous status.

Use the :publish endpoint with a delayUntil timestamp to schedule publishing for a future time. This sets the version status to scheduled.

If the delayUntil timestamp is in the past, the system publishes the version immediately.

The system may not publish scheduled versions at the exact scheduled time, but publishing should happen within minutes of the set time.

Set force to true in the request body to bypass validations such as approval workflows and required properties. This requires Administer access rights on the content.

Transition a ready or scheduled version back to draft for further editing.

When a version is inReview (submitted for approval), approve the active step of the approval workflow. The authenticated client must be a reviewer for the active step.

You can include an optional request body with a comment (max 255 characters). If the approval definition requires a comment for approvals, the comment field is mandatory.

For multi-step approvals, approving advances one step. The version remains in inReview until all steps are approved. After the final step, the version transitions to ready.

To bypass reviewer validation and approve the entire flow, set force to true. This requires Administer access on the content.

When a version is inReview, reject the active step of the approval workflow. This transitions the version to rejected status regardless of remaining steps. The authenticated client must be a reviewer for the active step.

You can include an optional request body with a comment (max 255 characters). If the approval definition requires a comment for rejections, the comment field is mandatory.

To bypass reviewer validation and reject the entire flow, set force to true. This requires Administer access on the content.

Use the Content API to delete a content item.

Deleting a content item does not immediately or permanently remove the resource. Instead, the content item remains read-only for a time decided by the CMS (SaaS) configuration.

Use the cms-permanent-delete header to permanently delete a content item.

See Delete contentDelete content API reference.

If you deleted a content item but did not permanently remove it, the normal request for the content fails. You can use the cms-accept-resource header to retrieve a deleted content item before permanently deleting it.

Listing content never includes deleted content.

The content endpoint accepts the cms-accept-resource header with a deleted or * value.

You can remove a content version using the content key and version identifier. Using this method, you cannot delete the published content or the only version in a locale.

See Delete versionDelete version API reference.

To delete all versions of a content locale, provide the locale as a path parameter together with the content key.

See Delete localeDelete locale API reference.

Use undelete to restore a deleted content item that was not permanently removed.

See Restore contentRestore content API reference.