Migration checklist

15 min

🚧 Preview3 CMS REST API reaches end-of-life on August 1, 2026The Preview3 CMS REST API endpoints retire on August 1, 2026. After this date, Optimizely begins disabling access, and applications that still call Preview3 endpoints (URLs containing /preview3/) may experience failed requests and service interruptions. Migrate to CMS REST API v1 before August 1, 2026. Mixing Preview3 and v1 endpoints is supported until the retirement date.

This checklist helps you systematically migrate an existing integration from the preview3 Content API to the v1 API. It breaks down required updates across endpoints, authentication, schemas, request and response structures, and validation rules. Use this checklist to ensure no breaking change is missed and to verify that your integration fully complies with the v1 API before going to production.

URL and Endpoints

Update base URL from preview3 to v1

Remove /experimental prefix from all content endpoints

Update Packaging API base URL (paths remain under /experimental/)

Update manifest operations to use the new /v1/manifest endpoint

Update delete locale calls to use path-based locale: /v1/content/{key}/locales/{locale}

Remove any Changesets API usage

Security

Remove use of act_as parameter in OAuth token endpoint requests

Schema and Type Changes

Update schema references in generated client code (OpenAPI spec changes):

ContentItem to ContentVersion

ContentItemPage to ContentVersionPage

ContentMetadata to ContentNode

ContentMetadataPage to ContentNodePage

Rename pagination field totalItemCount to totalCount

Update ContentComponent field names:

name to displayName

content to properties

Update property group name references:

Information to Content

Advanced to Settings

Update boolean field names to use is/has prefix:

localized to isLocalized

required to isRequired

disabled to isDisabled

enabled to isEnabled

deleted to isDeleted

success to isSuccess

Request Changes

Restructure create content requests to use NewContent with initialVersion

Move allowDeleted from query param to cms-allow-deleted header

Remove usage of the locale query parameter on version endpoints

Remove unknown/unsupported fields from all request bodies

Update property values to use nested { "value": ... } structure

Update richText property values to use { "value": { "html": ... } } structure

Replace any request passing cms-skip-validation: true with cms-skip-validation: *

Remove any usage of cms-skip-validation: approval (the approval value is no longer supported)

Response Changes

Expect 204 No Content response status from successfully executed commands

Include the Prefer: return=representation header with command requests when a resource is expected in the response body.

Required Fields

Ensure all ContentType objects have a non-empty displayName

Ensure all PropertyGroup objects have a non-empty displayName

Validation Changes

Ensure choice property values match defined choices

Ensure locales exist before creating content in that locale

Status Transitions

Replace all PATCH calls that set status with the corresponding transition endpoint:

"status": "draft" → POST /content/{key}/versions/{version}:draft

"status": "ready" → POST /content/{key}/versions/{version}:ready

"status": "published" → POST /content/{key}/versions/{version}:publish

"status": "scheduled" with delayPublishUntil → POST /content/{key}/versions/{version}:publish with { "delayUntil": "..." }

Remove status from create content and create version request bodies (new content is always created in draft status)

Update scheduled publishing to use :publish with delayUntil instead of patching status

Note that delayPublishUntil is now read-only — use :publish with delayUntil to schedule publication

Replace use of keepPublishedStatus: true in :copy call with an explicit call to the :publish endpoint

Behavior Changes

Handle non-primary locale versions not including merged properties

Update code that patches published versions to create a new version first

Only draft versions can be updated via PATCH — versions in any other status return an error

Response Handling

Update code parsing locales in content nodes (now array instead of object map)

Update code reading property values (now nested in { "value": ... } objects)

Update code reading richText properties (value changed from string to { "html": ... } object)

Testing

Test all API integrations with the v1 endpoint

Example: Before and After

Creating Content

POST /preview3/experimental/content
Content-Type: application/json

{
  "contentType": "ArticlePage",
  "displayName": "My Article",
  "container": "articles-folder",
  "locale": "en",
  "status": "draft",
  "routeSegment": "my-article",
  "properties": {
    "heading": "Welcome",
    "body": "Article content here"
  }
}

POST /v1/content
Content-Type: application/json

{
  "contentType": "ArticlePage",
  "container": "articles-folder",
  "initialVersion": {
    "displayName": "My Article",
    "locale": "en",
    "routeSegment": "my-article",
    "properties": {
      "heading": {
        "value": "Welcome"
      },
      "body": {
        "value": "Article content here"
      }
    }
  }
}

Deleting a Locale

DELETE /preview3/experimental/content/my-article/versions?locale=sv

DELETE /v1/content/my-article/locales/sv

Changing Version Status

PATCH /preview3/experimental/content/my-article/versions/1
Content-Type: application/json

{
  "status": "ready"
}

POST /v1/content/my-article/versions/1:ready

Scheduling a Version

PATCH /preview3/experimental/content/my-article/versions/1
Content-Type: application/json

{
  "status": "scheduled",
  "delayPublishUntil": "2026-03-01T09:00:00Z"
}

POST /v1/content/my-article/versions/1:publish
Content-Type: application/json

{
  "delayUntil": "2026-03-01T09:00:00Z"
}

Getting a Deleted Content Item

GET /preview3/experimental/content/my-article?allowDeleted=true

GET /v1/content/my-article
cms-allow-deleted: true