---
title: Manage content types using the REST API
slug: cms-saas/docs/manage-content-types-using-the-rest-api
docTags: 
createdAt: 2026-07-30T20:18:09.000Z
---

In Optimizely Content Management System (SaaS), a [content type](docId\:IIrc48HRxDZe6C7wiVBVT) defines a content item's characteristics and data model schema. You can create custom content types through the REST API or [UI](docId\:Dzguwnxrdce73ik_EQ5sx). See [Introduction to the CMS (SaaS) REST API](docId\:UBbVVvgyfOQzyLOTn4KMH).

## Create a content type

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

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

```json
{
    "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](docId\:WFhEMMql5Y0x5-zT_t6df).

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

```http
PATCH https://api.cms.optimizely.com/v1/contenttypes/story
Content-Type: application/merge-patch+json
```

```json
{
    "displayName": "Updated Story",
    "properties": {
        "heading": {
            "isRequired": false
        }
    }
}
```

See [Update content type API reference](docId\:BJ7oMWSDd-DJV0G7U7J2y).

## Get a specific content type

You can retrieve a content type using content type API with its unique key.

```http
GET https://api.cms.optimizely.com/v1/contenttypes/story
```

```json
{
    "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](docId\:huRH2TDsNmYi-hsgL9YT2).

## List content types

You can retrieve a list of content types using the content type API.

```http
GET https://api.cms.optimizely.com/v1/contenttypes
```

```json
{
  "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](docId\:mSUibxnY3b1BqVm1_Prmp).

### 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;

```http
GET https://api.cms.optimizely.com/v1/contenttypes?sources=DEFAULT,custom
```

See [List content types API reference](docId\:mSUibxnY3b1BqVm1_Prmp).

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

```http
GET https://api.cms.optimizely.com/v1/contenttypes?forContainerType=news
```

See [List content types API reference](docId\:mSUibxnY3b1BqVm1_Prmp).

## Delete a content type

You can delete existing content types using the content type API. You cannot delete built-in content types.

```http
DELETE https://api.cms.optimizely.com/v1/contenttypes/story
```

See [Delete content type API reference](docId\:y3aACio149J0XslAdhryn).

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

```json
{
  "key": "internalNews",
  "baseType": "_page",
  "displayName": "Internal News",
  "accessRights": [
    {
      "name": "Administrators",
      "type": "role"
    },
    {
      "name": "john.doe@example.com",
      "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).

```json
{
  "type": "richText",
  "displayName": "Summary",
  "isLocalized": true,
  "editorSettings": {
    "preset": "minimal"
  }
}
```

For `array` properties with `richText` items, configure `editorSettings` on the `items`:

```json
{
  "type": "array",
  "displayName": "Highlights",
  "items": {
    "type": "richText",
    "editorSettings": {
      "preset": "minimal"
    }
  }
}
```