Introduction to the CMS (SaaS) REST API

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

OpenAPI schema

You can download the OpenAPI schema from https://EXAMPLE.COM/_cms/VERSION/docs/content-openapi.json.

Replace VERSION with preview2 and EXAMPLE.COM with your CMS (SaaS) instance's URL.

You can find your CMS (SaaS)'s instance URL in your address bar.

For example: https://app-123.cms.optimizely.com/_cms/preview2/docs/content-openapi.json.

Management and delivery

The REST APIs are intended for managing resources only.

For high-performance delivery, use your CMS (SaaS) instance's Optimizely Graph instance.

Authentication

See authentication and authorization.

API Requests

Requests and responses use Content-Type: application/json unless otherwise specified. Unknown fields in requests are ignored unless otherwise stated. Any invalid field type will result in an error response.

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 the operation processing status can be retrieved.

GET requests

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

Paging

Most list endpoints use the query parameters pageIndex and pageSize.

• pageIndex – Zero-based index deciding which resource page to return. If omitted, the first page is returned.
• pageSize – Defines how many items are returned. If omitted, each page includes up to 100 resources unless defined otherwise.

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

{
  "items": [],
  "pageSize": 10,
  "pageIndex": 2,
  "totalItemCount": 421
}

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

POST requests

POST requests are mostly used to create resources but are sometimes used 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.

PUT requests

You can use a PUT request to create a resource or replace an existing one. Not all resource types support PUT requests.

To prevent a new resource from being created if the resource does not exist, include the If-Match=* header with the request.

To ensure that no one has updated an existing resource since 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.

PATCH requests

Use a PATCH request to update existing resources. The 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 since 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.

DELETE requests

Use a DELETE request to delete existing resources.

To ensure that no one has updated an existing resource since 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.

Error responses

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

• The type, title, status, and instance fields are used only for generic error information.
• The details field provides a human-readable description of the error
• The code field provides a machine-readable description of the error.
• If an error field is included, it indicates an issue with the provided model. Each property on the error object represents a field on the provided model, and the value provides error information about the problem with that field. There is a discrepancy between the name of the property on the error object and the model property.