---
title: Manage blueprints using the REST API
slug: cms-saas/docs/manage-blueprints-using-the-rest-api
docTags: 
createdAt: 2026-07-30T20:18:09.000Z
---

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](docId\:IIrc48HRxDZe6C7wiVBVT), 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](docId:2uVhCnJr4BdL9e5UNkN4L).

## 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](docId\:dvDI2XO6dpTmFCa9KgYrv) for the full API reference.

The request supports the following optional header:

- `Prefer: return=representation` – Return the created resource in the response body.

```http
POST https://api.cms.optimizely.com/v1/blueprints
Content-Type: application/json
```

```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](docId\:Imupm8I2_jVm_e6C8KAzp) 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.

```http
GET https://api.cms.optimizely.com/v1/blueprints/A42574ACC4FF402A94D807B7D45AD6B1
```

```json
{
    "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": "admin@example.com",
    "lastModified": "2025-01-15T10:30:00+00:00",
    "lastModifiedBy": "admin@example.com"
}
```

## List blueprints

You can list blueprints using the blueprints API. See [List blueprints](docId\:gGiIAbQjzL1Z_p2t-ar2Z) 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).

```http
GET https://api.cms.optimizely.com/v1/blueprints
```

```json
{
    "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": "admin@example.com",
            "lastModified": "2025-01-15T10:30:00+00:00",
            "lastModifiedBy": "admin@example.com"
        }
    ],
    "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](docId\:QxzH0eFKdSTVs1yctuHuH) 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.

```http
PATCH https://api.cms.optimizely.com/v1/blueprints/A42574ACC4FF402A94D807B7D45AD6B1
Content-Type: application/merge-patch+json
```

```json
{
    "displayName": "Updated Hero Section"
}
```

## Delete a blueprint

You can delete an existing blueprint using its unique key. See [Delete a blueprint](docId:9bsKodvvOrqjW7L9ZsrRa) 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.

```http
DELETE https://api.cms.optimizely.com/v1/blueprints/A42574ACC4FF402A94D807B7D45AD6B1
```