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

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

Installs a succeeded design library version into the target environment asynchronously.

Installation requirements:

* The library must be owned by or shared with the target space.
* Installation into the library's source environment is rejected.

A target organisation can have up to **100 concurrent design library installations** across all its spaces, environments and libraries. Installations with `sys.status` set to `created` or `in_progress` count towards this limit. Installations with status `succeeded` or `failed` do not count.

When the limit is reached, this endpoint returns `409 Conflict` with the message `Parallel installation limit reached` and `details.limit` set to `100`. No installation is created or queued. Retry after an active installation finishes and capacity becomes available.

A `201` response queues processing. Retrieve the installation using [Get a design library installation](/developers/docs/references/experience-management-api/design-libraries/installations/get-design-library-installation) until `sys.status` is `succeeded` or `failed`.

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

## Authentication

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

## Request

### Path parameters

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

### Body (application/json)

This endpoint expects an object.

- `version` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostRequestBodyContentApplicationJsonSchemaVersion, required) — A link to the succeeded version of this design library to install.

## Response

### 201

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

- `Design Library Installations_createDesignLibraryInstallation_Response_201`
  - DesignLibraryInstallationsCreateDesignLibraryInstallationResponse2010
  - DesignLibraryInstallationsCreateDesignLibraryInstallationResponse2011
  - DesignLibraryInstallationsCreateDesignLibraryInstallationResponse2012

## Errors

### 400 Bad Request Error

400

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

### 401 Unauthorized Error

401

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

### 403 Forbidden Error

403

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

### 404 Not Found Error

404

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

### 409 Conflict Error

The request conflicts with the current installation state. If `sys.id` is `Conflict` and the message is `Parallel installation limit reached`, the target organisation has reached its concurrent installation limit. No installation is created or queued. Retry after an active installation finishes and capacity becomes available. This response can also contain `VersionMismatch`.

- `CreateDesignLibraryInstallationRequestConflictError`
  - CreateDesignLibraryInstallationRequestConflictError0
  - CreateDesignLibraryInstallationRequestConflictError1

### 422 Unprocessable Entity Error

422

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

### 500 Internal Server Error

500

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

## Types

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostRequestBodyContentApplicationJsonSchemaVersion

A link to the succeeded version of this design library to install.

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostRequestBodyContentApplicationJsonSchemaVersionSys, required)

### DesignLibraryInstallationsCreateDesignLibraryInstallationResponse2010

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf0Sys, required)

### DesignLibraryInstallationsCreateDesignLibraryInstallationResponse2011

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf1Sys, required)

### DesignLibraryInstallationsCreateDesignLibraryInstallationResponse2012

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2Sys, required)
- `errors` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2ErrorsItems, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaSys

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

### CreateDesignLibraryInstallationRequestConflictError0

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

### CreateDesignLibraryInstallationRequestConflictError1

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

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostRequestBodyContentApplicationJsonSchemaVersionSys

- `type` ("Link", required)
- `linkType` ("DesignLibraryVersion", required)
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf0Sys

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

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf1Sys

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

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2Sys

- `id` (string, required)
- `type` ("DesignLibraryInstallation", required)
- `createdAt` (string, required)
- `status` ("failed", required)
- `createdBy` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysCreatedBy, required)
- `space` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysSpace, required)
- `environment` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysEnvironment, required)
- `designLibrary` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysDesignLibrary, required)
- `version` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysVersion, required, nullable)
- `completedAt` (string, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2ErrorsItems

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

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysCreatedBy

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysCreatedBySys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysSpace

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysSpaceSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysEnvironment

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysEnvironmentSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysDesignLibrary

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysDesignLibrarySys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysVersion

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysVersionSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2ErrorsItemsSys

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

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysCreatedBySys

- `type` ("Link", required)
- `linkType` ("User", required)
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysSpaceSys

- `type` ("Link", required)
- `linkType` ("Space", required)
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysEnvironmentSys

- `type` ("Link", required)
- `linkType` ("Environment", required)
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysDesignLibrarySys

- `type` ("Link", required)
- `linkType` ("DesignLibrary", required)
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignLibrariesDesignLibraryIdInstallationsPostResponsesContentApplicationJsonSchemaOneOf2SysVersionSys

- `type` ("Link", required)
- `linkType` ("DesignLibraryVersion", required)
- `id` (string, required)

## Examples

**Request**

```json
{
  "version": {
    "sys": {
      "type": "string",
      "linkType": "string",
      "id": "string"
    }
  }
}
```

**Response**

```json
{
  "sys": {
    "completedAt": "string",
    "createdAt": "string",
    "createdBy": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "designLibrary": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "environment": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "id": "string",
    "space": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "status": "created",
    "type": "string",
    "version": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    }
  }
}
```

**SDK Code**

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

{
  "version": {
    "sys": {
      "type": "Link",
      "linkType": "DesignLibraryVersion",
      "id": "<succeeded_version_id>"
    }
  }
}
```