Introduction to the CMS (SaaS) REST API

Optimizely Content Management System (CMS) (SaaS) has a REST API to manage resources. See the developer guide for available Resource typesResource types.

You can download the OpenAPI schema from https://api.cms.optimizely.com/<version>/docs/content-openapi.json as follows:

The REST APIs are intended for managing resources only. For high-performance delivery, use your CMS (SaaS) instance's Optimizely GraphOptimizely Graph instance.

See authentication and authorization.

Requests and responses use Content-Type: application/json unless otherwise specified. Unknown or unsupported fields in request bodies result in a 400 Bad Request error. Read-only properties are an exception and are silently ignored to simplify JSON roundtripping. Refer to the OpenAPI spec for details on which fields are read-only.

Responses may include additional fields not defined in the specification. The client should be able to handle this. In the future, operations that normally return a 200 OK response may return 202 Accepted if the service believes the operation will take too long to process. Such a response includes information about where you can retrieve the operation processing status.

Standard values for a field are documented as examples rather than a fixed enum, so the API accepts values beyond those listed. If you generate an API client, generate it from the current specification and regenerate it after each update. A client built from an earlier specification can reject valid values.

Use GET requests to retrieve existing resources. Generally, when a request is without a resource key, a list of resources matching the request is returned.

Use the If-None-Match header with an ETag value to avoid fetching unchanged resources. If the resource's ETag matches the provided value, the API returns a 304 Not Modified response. Alternatively, use the If-Modified-Since header with a date value; if the resource has not been modified since that date, a 304 Not Modified response is returned. Note that If-None-Match takes precedence if both headers are provided. Refer to the OpenAPI spec for which operations support these headers.

Most list endpoints use the query parameters pageIndex and pageSize.

The response returns a resource list in the following format, where the resources are included under the items field.

If all existing resources are returned, the service will omit the pageSize and pageIndex fields. The totalCount field provides an approximate indication of the total number of items available. It is not returned if the total number of resources is unknown.

You can mostly use POST requests to create resources, but you can sometimes use them for custom actions. In such cases, the resource path ends with a suffix representing the action. For example, the :copy suffix is used for the endpoint that creates a copy of an existing content item.

To ensure that no one has updated an existing resource because you last checked, pass in the ETag returned in the response header from a GET request for the same resource in the If-Match request header.

All POST requests return a 201 Created or 204 No Content response without a body by default. If you want the API to return the created or updated resource, you can pass in a Prefer header with the value return=representation as per the RFC 7240 standard.

Use a PATCH request to update existing resources. CMS (SaaS) API follows the JSON Merge Patch standard and expects a Content-Type: application/merge-patch+json header with requests.

To ensure that no one has updated an existing resource because you last checked, pass in the ETag returned in the response header from a GET request for the same resource in the If-Match request header.

All PATCH requests return a 204 No Content response by default. If you want the API to return the updated resource, you can pass in a Prefer header with the value return=representation as per the RFC 7240 standard.

Use a DELETE request to delete existing resources.

To ensure that no one has updated an existing resource because you last checked, pass in the ETag returned in the response header from a GET request for the same resource in the If-Match request header.

All DELETE requests return a 204 No Content response by default. If you want the API to return the resource that was deleted, you can pass in a Prefer header with the value return=representation as per the RFC 7240 standard.

Attempts to delete a resource that does not exist or that has already been deleted will result in a 404 Not Found response.

The following list shows CMS (SaaS) API error responses. They follow RFC 7807 standards.

CMS (SaaS) Rest API limits the number of REST API requests that you can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for users.