Content
Describes the content and content version resources for CMS (SaaS) and how to work with them.
The content resource is the primary resource type of Optimizely Content Management System (CMS) (SaaS). 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 (SaaS) 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 parent container's' key
when creating 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. Thekey
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
– Thekey
of the content instance that contains this instance.owner
– Thekey
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/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",
"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.
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 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.
Updated 4 months ago