HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Content

Describes the content and content version resources and how to work with them.

πŸ‘

Beta

Optimizely SaaS Core is in beta. Apply on Join the waitlist for SaaS Core or contact your Customer Success Manager.

The content resource is the primary resource type of the Optimizely Content Management System (CMS). Content can represent webpages, component, media and almost any other type. A content item holds data in a structured way that is described by a schema defined by a content type. Every content item is always an instance of a content type.

Each content type has different traits, but most content types let users localize the content data and provide a lifecycle that controls the publishing status.

Each content can have multiple versions. Versions can be in different draft states, but you can have only one published version for each locale.

Content resource

The content resource represents information that is shared across the content instance. This information is not versioned and changes to this information affect instances of the content.

The content resource contains the following fields:

NameAPI fieldDescription
KeykeyThe unique identifier of a Content instance.
The key is currently using a UUID based format, but this may change in the future and you should always treat the key as an opaque string.
Content TypecontentTypeThe content type that describes the schema of the content instance.
ContainercontainerThe key of the content instance that contains this instance.
OwnerownerThe key of the content instance that owns this instance. Used for assets of another content instance.
CreatedcreatedA timestamp indicating when this content instance was created.
Created bycreatedByA string indicating the username of the user that created this instance.
DeleteddeletedA timestamp that, if present, indicates when this content instance was deleted.
Deleted bydeletedByA string that, if present, indicates the username of the user that deleted this instance.

Content organization

CMS content is organized in a hierarchical structure. The container field on the content resource defines where an instance is located. This value should be set to the key of the parent container when you create the content instance. The content type may have restrictions on what type of content you can create under another instance of a certain type.

A content instance can also be owned by another instance. Content owned by another instance is usually referred to as an asset, and is usually a media or component content type. A content asset instance has the owner field assigned.

Content version resource

The content version resource represents information specific to one version of a content instance and contains the following fields:

NameAPI fieldDescription
KeykeyThe unique identifier of the content and is the same for all different versions of the same content instance.
LocalelocaleSpecifies the locale that this version is. You cannot change the locale for an existing version.
VersionversionA unique identifier for the version generated by the service. The version is guaranteed to be unique across all versions for the same content key. You cannot assign this value.
Content TypecontentTypeThe content type of the content instance. This value always matches the content type of the content instance and you cannot change it.
Display NamedisplayNameThe display name of the content.
StatusstatusThe status of the version.
PublishedpublishedA timestamp indicated when a content item should be public. If not assigned, this gets assigned when the first version is published.
ExpiredexpiredA timestamp indicated when a content item should no longer be public.
Delay publish untildelayPublishUntilA timestamp used when scheduling a version to be published to indicate when to publish the version. Required when status is set to scheduled.
Route segmentrouteSegmentA route segment associated with the current content, which is used to generate a route to the content instance.
Last modifiedlastModifiedA timestamp indicating when this version was last modified.
Last modified bylastModifiedByA string indicating the username of the user that last modified this version.
PropertiespropertiesA set of values that describes the content data. The names and types are defined by the content type schema.

Version status

The following are possible status values that a content version can have.

NameAPI valueDescription
DraftdraftIndicates that the version is a work in progress. This is the default status.
Ready for reviewreadyIndicates that editing of the version has completed and that it is ready to be reviewed.
In reviewinReviewIndicates that the approval process has started.
RejectedrejectedIndicates that the version was reviewed but rejected.
Scheduled for publishingscheduledIndicates that the version is scheduled to be published at a set time.
PublishedpublishedIndicates that the version is the published version. You can publish only one version for each locale.
Previously publishedpreviouslyPublishedAssigned by the system when another version is published. You cannot assign it through the API. You cannot modify versions with this status.

Properties

The properties field contains values for any property defined by the content type schema. The values of each property must match the data type as specified by the content type definition.

The following example shows a version with some basic data types.

{
  "key": "98eb33cfa7df48d1b987442c522984c8",
  "locale": "en",
  "contentType": "basic",
  "displayName": "Content with basic properties",
  "properties": {
    "someString": "some string content",
    "someBoolean": true,
    "someInteger": 12,
    "someFloat": 3.14,
    "someDateTime": "2023-01-01T10:46:08.293+00:00",
    "someContentReference": "cms://content/e56f85d0e8334e02976a2d11fe4d598c",
    "someStringArray": [
      "first",
      "second"
    ]
  }
}

Component properties

A complex property is defined by the content type as a component property of a certain component content type.

So if there is for example a component defined as:

{
    "key": "teaser",
    "baseType":"component",
    "properties": {
        "heading": {
            "type":"string"
        },
        "body": {
            "type":"string",
            "format":"html"
        }
    }
}

Then you can use that teaser component as property on another content type:

{
    "key": "pageWithComponents",
    "baseType":"page",
    "properties":{
        "mainTeaser":{
            "type": "component",
            "format": "teaser"
        },
        "teaserList":{
            "type":"array",
            "items": {
                "type": "component",
                "format": "teaser"
            }
        }
   }
}

A content version of the page with components could be defined as:

{
    "key": "98EB33CAA7DE48D1B487442C522984C8",
    "contentType": "pageWithComponents",
    "displayName": "A page with components",
    "locale":"en",
    "container":"5B51C2BAB5804DBE96CC5EAA2478830D",
    "properties": {
        "mainTeaser": {
            "heading": "Single component",
            "body": "<p>Some text for a single component</p>"
        },
        "teaserList": [
            {
                "heading": "first",
                "body": "<p>Some text for the first list component</p>"
            },
            {
                "heading": "second",
                "body": "<p>Some text for the second list component</p>"
            }
        ]
    }
}

Content properties

A content property is a complex property where the component content type is defined in the content data
rather than by the content type. The content type definition may however restrict the content property to only allow certain types.

A content property can also reference an existing content instance using it's unique content instance key.

So if a page has a property that is defined as a list of content component, like:

{
    "key": "pageWithContentList",
    "baseType": "page",
    "properties": {
        "someItems": {
            "type":"array",
            "items":{
                "type": "content"
            }
      }
   }
}

If there exists a content instance with specified key and a component type teaser, then a content version with a content property could be defined as follows:

{
    "key":"38EB33CAB7DE48D1B456442C522984C8",
    "contentType":"pageWithContentList",
    "displayName":"Example",
    "locale":"en",
    "container":"5B51C2BAB5804DBE96CC5EAA2478830D",
    "properties": {
        "someItems": [
            {
                "reference": "cms://content/38eb33cab7de48d1b487442c522984c8"
            },
            {
                "contentType": "teaser",
                "properties": {
                    "heading": "Heading for teaser component",
                    "body": "Some text"
                }
            }
        ]
    }
}

Work with content

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/v1/content/6946107a8ad6414f8f1786364dab1ec2
{
  "key": "6946107a8ad6414f8f1786364dab1ec2",
  "contentType": "story",
  "container": "98eb33cfa7df48d1b987442c522984c8",
  "created": "2023-01-01T10:46:08.293+00:00",
  "createdBy": "steve"
}

Create a content item

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

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

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

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

Create a copy of an existing content item

Use the Content API to create a content instance as a copy of an existing content item. A copy includes all items contained under the content item. Only the published or latest version of each content item and locale is copied.

POST https://example.com/_cms/v1/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/v1/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/v1/content/6946107a8ad6414f8f1786364dab1ec2:copy
Content-Type: application/json

{
    "keepPublishedStatus": true
}

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

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

{
    "allowDeleted": true
}

Get the content hierarchy path

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

GET https://example.com/_cms/v1/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. An empty list is returned if content with the provided key is not found.

Get the content under an instance

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

GET https://example.com/_cms/v1/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/v1/content/6946107a8ad6414f8f1786364dab1ec2/items?contentTypes=story,page

Move a content instance to a new container

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

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

{
  "container": "98eb33cfa7df48d1b987442c522984c8",
}

Delete content

Use the Content API to delete a content instance.

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

Deleting a content item will not immediately remove the resource permanently. The content item instead remains in a read-only state for a period of time decided by the CMS configuration.

Use the permanent parameter to permanently delete a content item.

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

Get a deleted content instance

If a content item was deleted, but not yet permanently removed, the normal request for the content will fail. However, you can use the allowDeleted parameter to retrieve a deleted content item before it is permanently deleted.

Deleted content is never included when listing content.

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

Restore a deleted item

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

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

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/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions

You can filter the list on locales and statuses.

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

Retrieve a specific content version

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

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

Update a content item

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

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

{
  "displayName": "Updated name",
}

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

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

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

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

Update the status of a content version

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

PATCH https://example.com/_cms/v1/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/v1/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/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253
Content-Type: application/merge-patch+json

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

If the publishAt timestamp was already passed, 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.

Delete a specific content version

You can remove a content version using the content key and version identifier of the version that should be deleted. You cannot delete the published content version or the only version in a locale using this method.

🚧

Warning

Deleting a content version is immediate and cannot be reversed.

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

Delete a content locale

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

🚧

Warning

Deleting a content locale immediate and cannot be reversed.

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