Migrate from Content API preview3 to v1

Migration from preview3 to V1 has a lot of breaking changes between the Optimizely CMS Content API preview3 and v1 versions. Use this guide when migrating an existing integration from preview3 to the stable v1 API.

The v1 API introduces changes to endpoint structure, request and response schemas, validation behavior, and security controls. Review each section carefully and update client configurations, request payloads, and response handling logic to ensure compatibility.

Update your API base URL in all client configurations.

All content endpoints have moved from /experimental/ paths to root paths:

The Packaging API remains under the /experimental/ prefix in v1. Only the base URL changes:

Manifest packages are now handled through a standalone endpoint:

The v1 manifest endpoint uses standard application/json content type. The /packages endpoint no longer supports Manifests.

While the Packaging API remain experimental, the /manifest endpoint is now considered stable and has been moved out of experimental status.

The locale parameter has moved from query string to path parameter.

The following schemas have been renamed in the OpenAPI specification. These are documentation changes to the model names and do not affect the API endpoints or JSON payloads:

If you generate client code from the OpenAPI specification, update your type references to use the new schema names.

Update any code that reads the total item count from paginated responses.

The ContentComponent model has been renamed to align with other API conventions:

Update all code that creates or reads ContentComponent objects to use the new field names.

The default property group names have been renamed to match the UI and .NET API:

Update any code that references these system property group names.

The structure of content properties has changed. In preview3, property values were stored directly. In v1, all property values are wrapped in an object with a value property. This change enables future scenarios where properties may include additional metadata.

Update all code that reads or writes content properties to use the new nested structure.

In addition to the value wrapper, richText property values have changed from plain strings to objects with an html property. This change enables future support for additional rich text formats beyond raw HTML.

When reading richText properties, extract the value from properties.{name}.value.html instead of properties.{name}.

When writing richText properties, wrap the HTML string in an object with an html property inside the value wrapper.

All boolean fields now use is or has prefix for consistency:

Update all boolean field references to use the new naming convention.

In preview3, media content could be created using a JSON request body without binary data. In v1, creating media content requires a multipart form-data request with both metadata and the binary file. You can no longer create media content without providing the binary file.

See the API documentation for details on creating media content.

The create content endpoint (POST /content) now uses a different request body structure.

Preview3 used ContentItem directly:

V1 uses NewContent with nested initialVersion of type ContentVersion:

Key differences:

The displayName field is now required for several resource types:

Ensure all objects of these types include a non-empty displayName when creating or updating. Existing resources without a displayName value will have the key value assigned.

When creating content, several fields have moved:

When reading content, use ContentNode (from GET /content/{key}) to access container and owner information.

All POST, PATCH, and DELETE command requests now return a 201 Created or 204 No Content response without a body by default. If you want the API to return the resulting or deleted resource as in preview3, you can pass in a Prefer header with the value return=representation as per the RFC 7240 standard.

In v1, non-primary locale versions only expose culture-specific properties. Properties that are not localizable are no longer merged from the primary locale version into non-primary versions.

In preview3, non-primary locale versions included merged properties from the primary locale. In v1, you must fetch the primary locale version separately if you need non-localizable property values.

In preview3, you could change a version's status by patching the status field:

In v1, the status field is read-only on both ContentVersion and NewContent.InitialVersion. Attempting to set status to a different value via PATCH returns a validation error. New content is always created in draft status.

The delayPublishUntil field on ContentVersion is also now read-only. To schedule publication, use the :publish endpoint with a delayUntil request body property.

To change a version's status, use the dedicated status transition endpoints described below.

V1 introduces three dedicated endpoints for changing version status. These replace the preview3 pattern of patching the status field.

Transition a version back to draft status.

Allowed from: ready, scheduled. Calling :draft on a version that is already in draft returns the current version unchanged.

This endpoint does not validate required properties or references.

Mark a version as ready. The version is available for publishing.

If an approval workflow is configured for the content, this endpoint automatically submits the version for approval. The resulting status will be inReview rather than ready.

This endpoint now accepts an optional request body with a comment (string, max 255 characters) that is attached to the approval start when the version transitions to inReview.

Allowed from: draft, scheduled. Calling :ready on a version that is already ready returns the current version unchanged.

This endpoint validates required properties and references.

Publish a version, making it the live version.

Allowed from: draft, ready, scheduled, rejected, inReview (force only).

This endpoint validates required properties and references unless force is set to true.

Optional request body properties:

Scheduled publishing:

In preview3, scheduled publishing was done by patching the status to scheduled with a delayPublishUntil field. In v1, use the :publish endpoint with delayUntil instead.

Approve the active step of an approval for a content version in inReview status. See Approve a content version in reviewApprove a content version in review for details.

Reject the active step of an approval for a content version in inReview status. The version transitions to rejected. See Reject a content version in reviewReject a content version in review for details.

Content in inReview status (awaiting approval) has restricted transitions:

In v1, you cannot use PATCH to update a version that is not in draft status. Any attempt to patch a non-draft version returns a 400 Bad Request error.

In preview3, patching a published version would directly modify the published version in place, bypassing the normal versioning workflow. In v1, you must explicitly create a new version using POST /content/{key}/versions to modify content that is already published.

This change aligns the API behavior with the CMS user interface, which requires creating a new draft to edit published content.

The act_as parameter has been removed from the OAuth token endpoint in v1. In preview3, this parameter allowed a client to request tokens that impersonate another user, which presented security risks:

The cms-skip-validation header value has been changed from accepting a boolean to a string. It currently only supports wildcard (*) values but the intention is to support more granular skip validation instructions in the future.

Replace cms-skip-validation: true with cms-skip-validation: *.

Move the allowDeleted flag from query parameter to request header.

The locale query parameter has been removed from version endpoints. Use the new /content/{key}/locales/{locale} endpoint for locale-specific operations.

The copy endpoint, /content/{key}:copy, no longer supports the keepPublishedStatus parameter. Copied content will always be created with draft status. Call the :publish endpoint to publish copied content.

Key differences in the response:

The following arrays now have explicit maximum item limits of 1000:

V1 uses strict JSON validation. Unknown or unsupported fields in request bodies now result in a 400 Bad Request error. In preview3, unknown fields were silently ignored.

Exception: Read-only properties are ignored. To simplify JSON roundtripping (e.g., fetching content and sending it back in an update), read-only properties such as created, createdBy, lastModified, and lastModifiedBy are silently ignored rather than causing an error. These properties are clearly documented as read-only in the API specification.

Preview3 behavior (ignored unknown field):

V1 behavior (returns 400 error):

Review all API requests and remove any fields that are not part of the v1 schema.

V1 validates that values for choice properties match one of the defined choices. In preview3, any value was accepted regardless of the defined choices.

If a choice property has defined values like ["Option1", "Option2", "Option3"], attempting to set an undefined value will now return a validation error.

V1 requires that the locale exists in the system before creating content in that locale. In preview3, creating content in a non-existent locale would automatically create the locale.

Ensure the required locale is configured in the system before creating content.

The following endpoints are not available in v1:

The Changesets API is not available in v1. This API was built on top of the CMS PaaS feature "Projects" which is not available in CMS SaaS.

The following schemas are not available in v1:

The following fields have been removed from existing schemas: