Describes the Optimizely Contnent Management System (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://api.cms.optimizely.com/<version>/docs/content-openapi.json
as followed:
GET https://api.cms.optimizely.com/VERSION/docs/content-openapi.json
Accept: application/json
Authorization: Bearer <your_access_token>
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": [],
"pageIndex": 2,
"pageSize": 10,
"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.
POST
requests can also be used to replace an existing resource.
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.
PATCH requests
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.
DELETE requests
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.
Error responses
The following list shows CMS (SaaS) API error responses. They follow RFC 7807 standards.
- The
type
,title
,status
, andinstance
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
errors
array field is included, it indicates an issue with the provided model. Each object on theerrors
array contains two fields, i.e.detail
andfield
.field
represents a field on the provided model, anddetail
provides error information about the problem with that field.