Manage blueprints using the REST API
Blueprints are templates for creating content items with predefined structure and properties. Instead of building content from scratch each time, you can define a blueprint that captures a reusable layout and property configuration. When creating content, you can base it on an existing blueprint to start with that predefined structure.
Blueprints reference a content type, which determines the available properties and structure. You can create blueprints for experience, section, and section-enabled component content types.
The blueprints API is available at https://api.cms.optimizely.com/v1/blueprints. The endpoint requires a valid token, as described in Authentication and authorizationAuthentication and authorization.
Blueprint data model
The blueprint resource has the following fields:
- key – Unique identifier for the blueprint (UUID format). If omitted on creation, a key is auto-generated.
- displayName – Display name of the blueprint. Required, maximum 255 characters.
- contentType – The content type of the blueprint. Required. You can set this field during creation, but it is read-only thereafter.
- content – The blueprint data containing the predefined structure and properties. Required. Contains:
- properties – Properties as defined by the corresponding content type.
- binding – Optional binding to another content item.
- composition – Optional composition structure for Visual Builder content (experiences and sections).
- created – Read-only timestamp indicating when the blueprint was created.
- createdBy – Read-only field indicating who created the blueprint.
- lastModified – Read-only timestamp indicating when the blueprint was last modified.
- lastModifiedBy – Read-only field indicating who last modified the blueprint.
Create a blueprint
You can create a blueprint using the blueprints API. You must provide a displayName, contentType, and content with the properties for the blueprint. See Create a blueprintCreate a blueprint for the full API reference.
The request supports the following optional header:
- Prefer: return=representation – Return the created resource in the response body.
POST https://api.cms.optimizely.com/v1/blueprints
Content-Type: application/json{
"displayName": "Standard Hero Section",
"contentType": "HeroSection",
"content": {
"properties": {
"heading": {
"value": "Default Heading"
},
"imageLayout": {
"value": "fullWidth"
}
}
}
}Get a blueprint
You can retrieve a specific blueprint using its unique key. See Get a blueprintGet a blueprint for the full API reference.
The request supports the following optional headers for conditional requests:
- If-None-Match – Return the resource only if the current ETag does not match. Returns 304 Not Modified if it matches.
- If-Modified-Since – Return the resource only if it was modified after the specified date. Returns 304 Not Modified if unchanged.
GET https://api.cms.optimizely.com/v1/blueprints/A42574ACC4FF402A94D807B7D45AD6B1{
"key": "A42574ACC4FF402A94D807B7D45AD6B1",
"displayName": "Standard Hero Section",
"contentType": "HeroSection",
"content": {
"properties": {
"heading": {
"value": "Default Heading"
},
"imageLayout": {
"value": "fullWidth"
}
}
},
"created": "2025-01-15T10:30:00+00:00",
"createdBy": "[email protected]",
"lastModified": "2025-01-15T10:30:00+00:00",
"lastModifiedBy": "[email protected]"
}List blueprints
You can list blueprints using the blueprints API. See List blueprintsList blueprints for the full API reference.
The endpoint supports the following query parameters for pagination:
- pageIndex – The zero-based index of the page to retrieve (0–10000).
- pageSize – The number of items per page (1–10000, default: 100).
GET https://api.cms.optimizely.com/v1/blueprints{
"items": [
{
"key": "A42574ACC4FF402A94D807B7D45AD6B1",
"displayName": "Standard Hero Section",
"contentType": "HeroSection",
"content": {
"properties": {
"heading": {
"value": "Default Heading"
},
"imageLayout": {
"value": "fullWidth"
}
}
},
"created": "2025-01-15T10:30:00+00:00",
"createdBy": "[email protected]",
"lastModified": "2025-01-15T10:30:00+00:00",
"lastModifiedBy": "[email protected]"
}
],
"pageSize": 100,
"pageIndex": 0,
"totalCount": 1
}Update a blueprint
You can update individual fields on an existing blueprint using a merge patch request. You cannot update the contentType field because it is read-only after creation. See Update a blueprintUpdate a blueprint for the full API reference.
The request supports the following optional headers:
- Prefer: return=representation – Return the updated resource in the response body.
- If-Match – Update only if the current ETag matches (optimistic concurrency). Returns 412 Precondition Failed on mismatch.
- If-Unmodified-Since – Update only if the resource was not modified after the specified date. Returns 412 Precondition Failed if modified.
PATCH https://api.cms.optimizely.com/v1/blueprints/A42574ACC4FF402A94D807B7D45AD6B1
Content-Type: application/merge-patch+json{
"displayName": "Updated Hero Section"
}Delete a blueprint
You can delete an existing blueprint using its unique key. See Delete a blueprintDelete a blueprint for the full API reference.
The request supports the following optional headers:
- Prefer: return=representation – Return the deleted resource in the response body.
- If-Match – Delete only if the current ETag matches (optimistic concurrency). Returns 412 Precondition Failed on mismatch.
- If-Unmodified-Since – Delete only if the resource was not modified after the specified date. Returns 412 Precondition Failed if modified.
DELETE https://api.cms.optimizely.com/v1/blueprints/A42574ACC4FF402A94D807B7D45AD6B1