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. See also Manage content types from the UI.

Create a content type

You can create content types using the content type API. You must provide a unique key and a baseType.

POST https://api.cms.optimizely.com/v1/contenttypes

{
    "key": "story",
    "baseType": "_component",
    "displayName": "Story",
    "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
            }
        }
    }
}

See Create content type API reference.

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

See Update content type API reference.

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

See Get content type API reference.

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
}

See List content types API reference.

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,custom

See List content types API reference.

List 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=news

See List content types API reference.

Delete 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/story

See Delete content type API reference.

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