Manage content using the REST API

In the following sections, replace example.com with your CMS (SaaS) instance URL. See the API reference documentation for information on finding your instance URL.

Create a content item

You can create a content instance using the Content API with a content version.

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

POST https://example.com/_cms/version2/content
Content-Type: application/json

{
    "key": "6946107a8ad6414f8f1786364dab1ec2",
    "contentType": "story",
    "locale": "en",
    "container": "98eb33cfa7df48d1b987442c522984c8",
    "displayName": "Example story",
    "property": {
        "heading": "The main story"
    }
}

See Create content API Reference.

Copy a content item

Use the content API to create a content instance 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.

POST https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2:copy

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

POST https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2:copy
Content-Type: application/json

{
    "container": "98eb33cfa7df48d1b987442c522984c8"
}

The copied version is created in draft state unless you set the keepPublishedStatus parameter. If you set this parameter to true, copies are created in a published state as long as the source was published.

POST https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2:copy
Content-Type: application/json

{
    "keepPublishedStatus": true
}

Use the allowDeleted parameter flag to copy deleted content items. Deleting the source content and this flag is false or not provided returns a "not found" error response.

POST https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2:copy
Content-Type: application/json

{
    "allowDeleted": true
}

See Copy content API reference.

Get content instance information

You can retrieve shared content instance information using the content API with the unique key of the content instance.

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2

{
  "key": "6946107a8ad6414f8f1786364dab1ec2",
  "contentType": "story",
  "container": "98eb33cfa7df48d1b987442c522984c8",
  "created": "2023-01-01T10:46:08.293+00:00",
  "createdBy": "steve"
}

See Get content API reference.

Get the content hierarchy path

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

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/path

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 path API reference.

Get the content under an instance

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

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/items

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

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/items?contentTypes=story,page

See Get content API reference.

Move a content instance to a container

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

PATCH https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2
Content-Type: application/merge-patch+json

{
  "container": "98eb33cfa7df48d1b987442c522984c8",
}

See Update content API reference.

List versions of a content item

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

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions

You can filter the list on locales and statuses.

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions?locales=fr,de&statuses=draft,ready

See List versions API reference.

Retrieve a specific content version

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

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions/523

See Get content API reference.

Update a content item

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

PATCH https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253
Content-Type: application/merge-patch+json

{
  "displayName": "Updated name",
}

See Update version API reference.

You can also create a version of an existing content instance.

POST https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions
Content-Type: application/json

{
    "key": "6946107a8ad6414f8f1786364dab1ec2",
    "displayName": "story",
    "locale": "en",
    "container": "98eb33cfa7df48d1b987442c522984c8",
    "displayName": "Example story",
    "property": {
        "heading": "The main story"
    }
}

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

See Create version API reference.

Update a content version status

The Content API lets you update the status of an individual version.

PATCH https://example.com/_cms/versino2/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253
Content-Type: application/merge-patch+json

{
  "status": "ready",
}

To publish an existing version of a content item, set the status to published, which updates any existing published version to status previouslyPublished.

PATCH https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253
Content-Type: application/merge-patch+json

{
  "status": "published",
}

Use the scheduled status and provide the publishAt timestamp to schedule the publishing of the content version to a time in the future,

PATCH https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253
Content-Type: application/merge-patch+json

{
  "status": "scheduled",
  "delayPublishUntil": "2023-12-25T07:00:00.000+00:00" 
}

If you have already passed the publishAt timestamp, the version is published immediately.

Scheduled publishing of versions is not guaranteed to happen at the exact scheduled time but should happen within minutes of the set time.

See Update version API reference.

Delete content

Use the Content API to delete a content instance.

DELETE https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2

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 permanent parameter to permanently delete a content item.

DELETE https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2?permanent=true

See Delete content API reference.

Get a deleted content instance

If you deleted a content item but did not permanently remove it, the normal request for the content will fail. However, you can use the allowDeleted parameter to retrieve a deleted content item before permanently deleting it.

Listing content never includes deleted content.

GET https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2?allowDeleted=true

Delete a content version

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.

🚧

Warning

Deleting a content version is immediate and cannot be reversed.

DELETE https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253

See Delete version API reference.

Delete a content locale

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

🚧

Warning

Deleting a content locale is immediate and cannot be reversed.

DELETE https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2/versions?locale=fr

See Delete locale API reference.

Restore a deleted item

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

POST https://example.com/_cms/version2/content/6946107a8ad6414f8f1786364dab1ec2:undelete

See Restore content API reference.