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 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 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 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 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 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 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