Manage content types using the REST API
In Optimizely Content Management System (SaaS), a content type defines a content item's characteristics and data model schema. You can create custom content types through the REST API or UI. See Introduction to the CMS (SaaS) REST API.
Create a content type
You can create content types using the content type API. You must provide a unique key and a baseType.
The optional icon field sets the icon that Visual Builder displays for the content type. Use a built-in icon name such as image, video, heading, or file-lines. The API accepts any string of up to 255 characters, but Visual Builder does not display an icon for a name it does not recognize. To change or clear the icon later, send an update request with a new name or null.
You can view the list of icons and their names in the UI:
- Go to Settings > Content Types.
- Select a content type to view its details.
- Go to Settings for that content type.
- Expand the Icon field.
POST https://api.cms.optimizely.com/v1/contenttypes{
"key": "story",
"baseType": "_component",
"displayName": "Story",
"icon": "file-lines",
"properties": {
"heading": {
"type": "string",
"displayName": "Heading",
"description": "Write the greatest heading you can think of.",
"isLocalized": true,
"isRequired": true,
"sortOrder": 10,
"maxLength": 100
},
"body": {
"type": "richText",
"displayName": "Body text",
"isLocalized": true,
"isRequired": true,
"sortOrder": 20
},
"tags": {
"type": "array",
"isRequired": false,
"sortOrder": 30,
"items": {
"type": "string",
"format": "shortString",
"maxLength": 50
}
}
}
}Update a content type
You can update existing content types using the content type API, but you cannot update the key or baseType of an existing content type. Use a PATCH request with application/merge-patch+json content type to modify individual fields.
PATCH https://api.cms.optimizely.com/v1/contenttypes/story
Content-Type: application/merge-patch+json{
"displayName": "Updated Story",
"properties": {
"heading": {
"isRequired": false
}
}
}Get a specific content type
You can retrieve a content type using content type API with its unique key.
GET https://api.cms.optimizely.com/v1/contenttypes/story{
"key": "story",
"displayName": "Story",
"description": "The Story contains data about news stories.",
"baseType": "_component",
"sortOrder": 10,
"mayContainTypes": [ "*" ],
"created": "2023-05-22T14:31:08.43+00:00",
"createdBy": "steve",
"lastModified": "2023-05-22T14:31:20.557+00:00",
"lastModifiedBy": "steve",
"properties": {
"heading": {
"type": "string",
"displayName": "Heading",
"description": "Write the greatest heading you can think of.",
"isLocalized": true,
"isRequired": true,
"sortOrder": 10,
"maxLength": 100
},
"body": {
"type": "richText",
"displayName": "Body text",
"isLocalized": true,
"isRequired": true,
"sortOrder": 20
},
"tags": {
"type": "array",
"isRequired": false,
"sortOrder": 30,
"items": {
"type": "string",
"format": "shortString",
"maxLength": 50
}
}
}
}List content types
You can retrieve a list of content types using the content type API.
GET https://api.cms.optimizely.com/v1/contenttypes{
"items": [
{
"key": "story",
"baseType": "_component",
"displayName": "Story"
},
{
"key": "newspage",
"baseType": "_page",
"displayName": "News"
}
],
"pageSize": 10,
"pageIndex": 0,
"totalCount": 2
}List editable content types
Because you can edit only certain content types, you may want to list only editable content types by providing the sources parameter.
The value DEFAULT returns content types from the default source where the source field is excluded.
List content types from a specific source
You can restrict the list to only return content types from one or more sources. For example, you could use this to limit the listing to include only content types that are editable in the UI.
The value DEFAULT indicates that content types where the source field is empty should be returned;
GET https://api.cms.optimizely.com/v1/contenttypes?sources=DEFAULT,customList content types you can create under a content type
Use the forContainerType parameter to list which content type you can create under another content type.
GET https://api.cms.optimizely.com/v1/contenttypes?forContainerType=newsDelete a content type
You can delete existing content types using the content type API. You cannot delete built-in content types.
DELETE https://api.cms.optimizely.com/v1/contenttypes/storyAccess rights
The accessRights field restricts which users or roles can create content of this type. When specified, only the listed users and roles can create instances of this content type.
{
"key": "internalNews",
"baseType": "_page",
"displayName": "Internal News",
"accessRights": [
{
"name": "Administrators",
"type": "role"
},
{
"name": "[email protected]",
"type": "user"
}
]
}Each entry requires:
- name – The name of the role, user, or application.
- type – One of role, user, or application. Defaults to role if not specified.
Display mode
The displayMode field controls whether a property appears in the editing interface:
- available – (default) The property is visible and editable.
- hidden – The property is hidden from the editing interface but can still be set through the API.
Editor settings
The editorSettings field is a dictionary of key-value pairs for editor-specific configuration. Available settings depend on the property type.
For richText properties, use the preset setting to configure the toolbar. Available values are:
- minimal – A basic toolbar for simple text formatting (for example, bold, italic, and links).
- default – A standard toolbar with common formatting options (for example, headings, lists, and images).
- expanded – A full toolbar with all formatting options (for example, tables, search and replace, and remove formatting).
{
"type": "richText",
"displayName": "Summary",
"isLocalized": true,
"editorSettings": {
"preset": "minimal"
}
}For array properties with richText items, configure editorSettings on the items:
{
"type": "array",
"displayName": "Highlights",
"items": {
"type": "richText",
"editorSettings": {
"preset": "minimal"
}
}
}