Content

👍

Beta

Optimizely CMS (SaaS) is in beta. Apply on Join the waitlist for CMS (SaaS) 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, components, media, and almost any other type. A content item holds data in a structured way described by a schema defined by a content type. Every content item is 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 organization

CMS organizes content in a hierarchical structure. The container field on the content resource defines where to locate an instance. You should set this value to the key of the parent container when you create the content instance. The content type may restrict what type of content you can create under another instance of a certain type.

An instance can also own a content instance. Content owned by another instance is an asset, and a media or component content type. A content asset instance has the owner field assigned.

Content resource

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

The content resource contains the following fields:

• key – The unique identifier of a content instance. The key currently uses a UUID-based format, but this may change, and you should treat the key as an opaque string.
• contentType – The content type that describes the schema of the content instance.
• container – The key of the content instance that contains this instance.
• owner – The key of the content instance that owns this instance. Used for assets of another content instance.
• created – A timestamp indicating when someone created the content instance.
• createdBy – A string indicating the username of the person who created the instance.
• deleted – A timestamp that, if present, indicates when someone deleted the content instance.

Content version resource fields

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

• key – The unique identifier of the content is the same for different versions of the same content instance.
• locale – Specifies the locale of this version. You cannot change the locale for an existing version.
• version – A unique identifier for the version generated by the service. The version is guaranteed to be unique across versions for the same content key. You cannot assign this value.
• contentType – The content type of the content instance. This value matches the content type of the content instance, and you cannot change it.
• displayName – The display name of the content.
• status – The status of the version.
• published – A timestamp indicates when a content item should be public. If not assigned, this gets assigned when the first version is published.
• expired – A timestamp indicated when a content item should no longer be public.
• delayPublishUntil – A timestamp used when scheduling a version to be published to indicate when to publish the version. It is required when you set the status scheduled.
• routeSegment – A route segment associated with the current content generates a route to the content instance.
• lastModified – A timestamp indicating when this version was last modified.
• lastModifiedBy – A string indicating the user's username that last modified this version.
• properties – A set of values that describes the content data. The content type schema defines the names and types.

Content version status values

A content version can have the following status values.

• draft – Default. Indicates that the version is a work in progress.
• ready – Indicates that editing of the version is complete and ready to be reviewed.
• inReview – Indicates that the approval process has started.
• rejected – Indicates that the version was reviewed but rejected.
• scheduled – Indicates that the version will be published at the scheduled time.
• published – Indicates that the version is the published version. You can publish only one version for each locale.
• previouslyPublished – Assigned 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 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

The content type defines a complex property as a component property of a certain component content type.

So, if there is 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"
      }
    }
  }
}

You could define a content version of the page with components 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. However, the definition of a content type may restrict the content property to only certain types.

A content property can also reference an existing content instance using its unique content instance key.

So, suppose you define a page with a property as a list of content components as follows:

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

If there exists a content instance with a 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"
        }
      }
    ]
  }
}

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/v1/content
Content-Type: application/json

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

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/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. Deleting the source content and this flag is false or not provided returns a "not found" error response.

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

{
    "allowDeleted": true
}

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"
}

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. It returns an empty list if it does not find content with the provided key.

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 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",
}

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, provide a new locale.

Update a content version status

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 you 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.

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. Instead, The content item remains in a read-only state for a 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 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 you permanently delete it.

Listing content never includes deleted content.

GET https://example.com/_cms/v1/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/v1/content/6946107a8ad6414f8f1786364dab1ec2/versions/1253

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 immediate and cannot be reversed.

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

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