> This page is for API Reference.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# Create a design library version

POST https://api.contentful.com/spaces/{spaceId}/design_libraries/{designLibraryId}/versions
Content-Type: application/json

Creates an immutable snapshot of the design library's items asynchronously from its source space.

### Included items

The version copies items selected by the design library's taxonomy concept, along with their related data assemblies. Set `includeLinkedContentTypes` to `true` to also include related content types and editor interfaces.

See [How items are included](/developers/docs/references/experience-management-api/design-libraries#how-items-are-included).

* A `201` response queues processing.
* Poll [Get a design library version](/developers/docs/references/experience-management-api/design-libraries/versions/get-design-library-version) until `sys.status` is `succeeded` or `failed`.

A version can contain at most **1,000 unique fetched items** across all item types, including derived content types and data assemblies.

See [Design library limits](/developers/docs/references/experience-management-api/design-libraries#limits).

Reference: https://contentful.com/developers/docs/references/experience-management-api/design-libraries/versions/create-design-library-version

## Authentication

- `Authorization` header (bearer token, required) — Contentful Management API token

## Request

### Path parameters

- `spaceId` (string, required)
- `designLibraryId` (string, required)

### Body (application/json)

This endpoint expects an object.

- `name` (string, required)
- `description` (string, required, nullable) — A description of up to 1,000 characters, or `null` for no description. This field is required.
- `options` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostRequestBodyContentApplicationJsonSchemaOptions, optional)

## Response

### 201

The version was created and queued for processing. This response does not indicate that the snapshot is complete.

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `name` (string, required)
- `description` (string, required, nullable)
- `itemCounts` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaItemCounts, required)
- `errors` (list of SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaErrorsItems, optional)

## Errors

### 400 Bad Request Error

400

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

### 401 Unauthorized Error

401

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

### 403 Forbidden Error

403

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

### 404 Not Found Error

404

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

### 409 Conflict Error

Another version of this design library is already being created.

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

### 422 Unprocessable Entity Error

422

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

### 500 Internal Server Error

500

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)

## Types

### SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostRequestBodyContentApplicationJsonSchemaOptions

- `includeLinkedContentTypes` (boolean, optional) — Includes same-environment content types referenced by data assemblies and their related editor interfaces in the snapshot when set to `true`.

### SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaSys

- `id` (string, required)
- `type` ("Error", required)

### SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaItemCounts

- `experienceTemplates` (double, optional)
- `components` (double, optional)
- `designTokens` (double, optional)
- `contentTypes` (double, optional)
- `dataAssemblies` (double, optional)
- `editorInterfaces` (double, optional)

### SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaErrorsItems

- `sys` (SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaErrorsItemsSys, required)
- `message` (string, required)
- `details` (string, required)

### SpacesSpaceIdDesignLibrariesDesignLibraryIdVersionsPostResponsesContentApplicationJsonSchemaErrorsItemsSys

- `type` ("Error", required)
- `name` (string, required)

## Examples

**Request**

```json
{
  "name": "string",
  "description": "string"
}
```

**Response**

```json
{
  "sys": {
    "id": "string",
    "type": "string",
    "completedAt": "string",
    "createdAt": "string",
    "createdBy": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "designLibrary": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "space": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "status": "created"
  },
  "name": "string",
  "description": "string",
  "itemCounts": {
    "experienceTemplates": 1.1,
    "components": 1.1,
    "designTokens": 1.1,
    "contentTypes": 1.1,
    "dataAssemblies": 1.1,
    "editorInterfaces": 1.1
  },
  "errors": [
    {
      "sys": {
        "type": "string",
        "name": "string"
      },
      "message": "string",
      "details": "string"
    }
  ]
}
```

**SDK Code**

```http HTTP
POST /spaces/{sourceSpaceId}/design_libraries/{designLibraryId}/versions HTTP/1.1
Host: api.contentful.com
Authorization: Bearer <management_token>
Content-Type: application/json

{
  "name": "Initial snapshot",
  "description": null,
  "options": {
    "includeLinkedContentTypes": true
  }
}
```