> 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

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

Creates a design library from a source environment and taxonomy concept in the specified space.

Creating a design library does not create a version. Use [Create a design library version](/developers/docs/references/experience-management-api/design-libraries/versions/create-design-library-version) to snapshot its items.

### Item selection

The taxonomy concept in `basedOn.concept` selects the components, design tokens and experience templates to include in future versions. Related data assemblies are included automatically; content types and editor interfaces can be included when creating a version.

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

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

## Authentication

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

## Request

### Path parameters

- `spaceId` (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.
- `basedOn` (SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOn, required) — Links to the source environment in this space and the taxonomy concept used to select the library's items.
- `sharedWithSpaces` (SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaSharedWithSpaces, required) — Controls which spaces in the same organisation can read and install the library: - An array of space IDs: Share with those spaces. - `"*"`: Share with all spaces in the organisation. - An empty array: No sharing. Explicit space IDs must contain 12 lowercase letters or digits and must exclude the source space.

## Response

### 201

201

- `sys` (SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaSys, required)
- `name` (string, required)
- `description` (string, required, nullable)
- `sharedWithSpaces` (SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaSharedWithSpaces, required)
- `recommendedVersion` (SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaRecommendedVersion, required, nullable)

## Errors

### 400 Bad Request Error

400

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

### 401 Unauthorized Error

401

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

### 403 Forbidden Error

403

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

### 404 Not Found Error

404

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

### 409 Conflict Error

409

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

### 422 Unprocessable Entity Error

422

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

### 500 Internal Server Error

500

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

## Types

### SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOn

Links to the source environment in this space and the taxonomy concept used to select the library's items.

- `environment` (SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnEnvironment, required)
- `concept` (SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnConcept, required)

### SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaSharedWithSpaces

Controls which spaces in the same organisation can read and install the library: - An array of space IDs: Share with those spaces. - `"*"`: Share with all spaces in the organisation. - An empty array: No sharing. Explicit space IDs must contain 12 lowercase letters or digits and must exclude the source space.

- "*"
- list of string

### SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaSys

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

### SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaSharedWithSpaces

- "*"
- list of string

### SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaRecommendedVersion

- `sys` (SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaRecommendedVersionSys, required)

### SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnEnvironment

- `sys` (SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnEnvironmentSys, required)

### SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnConcept

- `sys` (SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnConceptSys, required)

### SpacesSpaceIdDesignLibrariesPostResponsesContentApplicationJsonSchemaRecommendedVersionSys

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

### SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnEnvironmentSys

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

### SpacesSpaceIdDesignLibrariesPostRequestBodyContentApplicationJsonSchemaBasedOnConceptSys

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

## Examples

**Request**

```json
{
  "name": "string",
  "description": "string",
  "basedOn": {
    "environment": {
      "sys": {
        "type": "string",
        "linkType": "string",
        "id": "string"
      }
    },
    "concept": {
      "sys": {
        "type": "string",
        "linkType": "string",
        "id": "string"
      }
    }
  },
  "sharedWithSpaces": "string"
}
```

**Response**

```json
{
  "sys": {
    "id": "string",
    "type": "string",
    "basedOn": {
      "concept": {
        "sys": {
          "id": "string",
          "linkType": "string",
          "type": "string"
        }
      },
      "environment": {
        "sys": {
          "id": "string",
          "linkType": "string",
          "type": "string"
        }
      }
    },
    "createdAt": "string",
    "createdBy": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "space": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "updatedAt": "string",
    "updatedBy": {
      "sys": {
        "id": "string",
        "linkType": "string",
        "type": "string"
      }
    },
    "version": 1
  },
  "name": "string",
  "description": "string",
  "sharedWithSpaces": "string",
  "recommendedVersion": {
    "sys": {
      "type": "string",
      "linkType": "string",
      "id": "string"
    }
  }
}
```