> 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/_mcp/server.

Environments allow you to develop and test changes to data in isolation from other environments. You can use them for all purposes in your development process like QA, staging environments or in continuous integration.

Environments are resources in a space and can be accessed by a unique identifier. This means that two spaces can have an environment with the same name.

A space can have multiple environments. A space has a minimum of one environment, which is called master. The master environment cannot be changed, deleted or renamed.

When cloning environments, please note that it is a heavy duty process that takes time proportionate to the amount of data contained in the source environment.

For a best practice explanation on how to use environments in your development workflow, please read the [Managing multiple environments](/concepts/multiple-environments) article.

## Creating environments

To create other environments next to master, you need to have the default space admin role or a role, which allows you to [manage and use all sandbox environments in this space](/references/content-management-api/roles). While creating an environment, you need to understand that it can only be a copy of the current state of the master environment. See the [Environment aware Resources](/references/content-management-api/overview) chapter below for more information on what resources are copied to an environment. It is not possible to create or have empty environments or environments based on older versions of a master environment.

To create an environment, make a request to `PUT /spaces/<id>/environments/staging` specifying the name in the payload like `{"name": "My staging environment"}`. After this request got a successful response, please query the single endpoint of that environment to check if the environment is already available.

You can also create an environment with any other environment as a source by providing the `X-Contentful-Source-Environment` header and providing it with the environment ID for the desired source environment.

## Access content in an environment

To request content from an environment, you need to provide another fragment in the url. For example to get all entries from the previously created `staging` environment, use `/spaces/<id>/environments/staging/entries`.

Requests to `/spaces/<id>/entries` without the environment fragment will implicitly request content from the master environment.

## Environment aware resources

The following resources are environment aware. This means upon creation of an environment, the following resources are copied from the master environment to the environment you want to create:

* App Installations

* Assets

* Content Types

* Editor Interfaces

* Entries

* Extensions

* Locales

* Releases

* Scheduled Actions

Upon copying, all resources maintain their original metadata like `sys.id` or `createdAt`.

All other resources are available on a space level only. Personal access tokens allow access according to your role. This means if you have access to a space and have the default space admin role or a role, which allows to [manage and use all sandbox environments in this space](/references/content-management-api/roles), you can use your PAT to access all environments. For CDA/CPA API key pairs, you can select the environments for which they have access, please refer to the API keys section in this document for more information.

## Environment states

An environment can have different states determined by the `sys.state` property.

| Status     | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| queued     | The environment was queued successfully and will be created soon. |
| inProgress | The environment is currently being created.                       |
| ready      | The environment is ready to use.                                  |
| failed     | The environment failed to get to a `ready` state.                 |

The master environment is always in state `ready`.

## Environments and rate limiting

All requests to environments in a space count against the organizations rate limits bucket.

## Environments and webhooks

Webhooks can be triggered for one or multiple environments by using the `filters` property of a
webhook. Supported scenarios are:

* trigger only for specific environments by specifying environment constraints in the `filters`
  property (e.g. `{"filters": [{"equals": [{"doc": "sys.environment.sys.id"}, "some-env-id"]}]}`)

* trigger for all environments by not setting any environment filters (e.g. `{"filters": []}`)

* trigger only for the `master` environment by omitting the `filters` property or setting its value
  to `null`. This scenario handles webhooks created prior to introduction of environments in
  a backwards compatible manner.

Please refer the [webhooks reference](/references/content-management-api/webhooks) for more details.

There are no events for creating or deleting an environment.

## Environments and snapshots

Snapshots are only available for entries and content types belonging to the master environment. Snapshots are not available in the sandbox environments.

## Environment collection

[Get all environments of a space](/references/content-management-api/environments/get-all-environments-of-a-space)

[Create an environment](/references/content-management-api/environments/create-an-environment)

Create an environment with an auto-generated `sys.id`.

> **Info**
>
> Whilst it's possible to create an environment with an auto-generated ID, we recommend creating environments with a specified ID to have more control in your automation scripts. See Environment section below.

To create an environment from a specified environment, use the [Create an environment](/references/content-management-api/environments/create-an-environment) endpoint with the X-Contentful-Source-Environment header and provide it with the environment ID for the desired source environment.

## Environment

[Get an environment](/references/content-management-api/environments/get-an-environment)

[Create an environment with ID](/references/content-management-api/environments/create-an-environment-with-a-specified-id)

Create a new environment with a specified `sys.id`.

> **Info**
>
> When creating a new environment, the following character length limit applies to environment IDs: 40 characters.

To create an environment from a specified environment, use the [Create an environment with ID](/references/content-management-api/environments/create-an-environment-with-a-specified-id) endpoint with the X-Contentful-Source-Environment header and provide it with the environment ID for the desired source environment.

To update an existing environment, use the [Create an environment with ID](/references/content-management-api/environments/create-an-environment-with-a-specified-id) endpoint.

**Notes**: When updating an existing environment, you need to specify the last version of the environment you are updating with `X-Contentful-Version`.

[Delete an environment](/references/content-management-api/environments/delete-an-environment)


## API Docs

- Environments [Get all environments of a space](https://contentful.com/developers/docs/references/content-management-api/environments/get-all-environments-of-a-space.md)
- Environments [Create an environment](https://contentful.com/developers/docs/references/content-management-api/environments/create-an-environment.md)
- Environments [Get an environment](https://contentful.com/developers/docs/references/content-management-api/environments/get-an-environment.md)
- Environments [Create an environment with a specified ID](https://contentful.com/developers/docs/references/content-management-api/environments/create-an-environment-with-a-specified-id.md)
- Environments [Delete an environment](https://contentful.com/developers/docs/references/content-management-api/environments/delete-an-environment.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json)
- [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)