Environments

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 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. 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 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, 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.

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

Create an environment

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

To create an environment from a specified environment, use the 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

Create an environment with ID

Create a new environment with a specified sys.id.

To create an environment from a specified environment, use the Create an environment with 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 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