> 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. > **Info** > > **Disclaimer**: Any user may opt-in and create the Master environment alias. Creating additional custom aliases is only available for Premium/Enterprise customers on [current pricing plans](https://www.contentful.com/pricing/). \ An environment alias allows you to access and modify the data of an environment, called the target environment, through a different static identifier. You must opt-in to this feature in the Contentful web app on the Settings > Environments page. During this opt-in process, we create a default alias with the ID `master`. This alias cannot be renamed or deleted. Once you've opted in, you can create up to two more aliases. Only space admins can opt-in and manage environment aliases. Aliases and target environments can be used to enhance your development and deployment workflows. For example, you can safely apply content model changes and roll them back when necessary or use them in your CI/CD pipelines. Check out the [concepts section](/concepts/environment-aliases) to find out more about environment aliases. ## Creating environment aliases When you set up this feature for your space, we create a default `master` environment alias for you. You can also create up to two more aliases by sending a `PUT` request to `spaces//environment_aliases/` and specifying the target environment in the payload [as described below](/references/content-management-api/overview). > **Info** > > When creating a new environment alias, the following character length limit applies to environment alias IDs: 64 characters. Aliases must always target an existing environment. Environments targeted by aliases cannot be deleted. The `master` environment alias cannot be deleted. ## Updating environment aliases To change the target environment of an environment alias, you need to be a space admin. Similar to environments, you cannot change an environment alias id. You do this by sending a `PUT` request to `/spaces//environment_aliases/` specifying the target environment in the payload [as described below](/references/content-management-api/overview). ## Deleting environment aliases You can delete an environment alias by sending a `DELETE` request to `/spaces//environment_aliases/`. It is not possible to delete the `master` alias or its target environment. ## Accessing data using an environment alias To request data using the environment alias, specify the alias ID instead of the ID of the target environment. For example, if the `master` alias targets an environment with ID `target-environment`, you can access its data from `/spaces//environments/master/...`. ### Master alias Requests without the environment alias fragment will be treated like requests to the `master` environment alias. For example, requests to `/spaces//entries` will have the same outcome as requests to `/spaces//environments/master/entries`. ## New environment properties when using aliases Fetching an environment can now be done through the environment's ID or alias ID. New properties are introduced on environments that are targeted by aliases. * Fetching the environment using the environment identifier e.g. `target-environment` `GET /spaces/{space_id}/environments/{environment_id}` ``` # Sample response body { "name": "target-environment", "sys": { "type": "Environment", "id": "target-environment", "version": 1, "space": { ... }, }, # NEW - list of environment aliases that target this environment "aliases": [{ "sys": { "type": "Link", "linkType": "EnvironmentAlias", "id": "master" } }], "status": { ... }, "createdBy": { ... }, "createdAt": "2018-10-08T09:07:03Z", "updatedBy": { ... }, "updatedAt": "2018-10-08T09:07:03Z" } ``` * Fetching the environment using the environment alias identifier `master` `GET /spaces/{space_id}/environments/{environment_alias_id}` ``` # Sample response body { "name": "master", "sys": { "type": "Environment", "id": "master", "version": 1, "space": { ... }, # NEW - the targeted environment "aliasedEnvironment": { "sys": { "type": "Link", "linkType": "Environment", "id": "target-environment" } }, # NEW - list of environment aliases that target this environment # for consistency we also return the aliases "aliases": [{ "sys": { "type": "Link", "linkType": "EnvironmentAlias", "id": "master" } }], "status": { ... }, "createdBy": { ... }, "createdAt": "2018-10-08T09:07:03Z", "updatedBy": { ... }, "updatedAt": "2018-10-08T09:07:03Z" } } ``` ## Environment alias collection [Get all environment aliases of a space](/references/content-management-api/environment-aliases/get-all-environment-aliases-of-a-space) ## Environment alias [Get an environment alias](/references/content-management-api/environment-aliases/get-an-environment-alias) [Create or update an environment alias](/references/content-management-api/environment-aliases/create-or-update-an-environment-alias) Use this endpoint to create a new environment alias or change the environment which the environment alias references. **Note that when updating an environment alias, the following headers need to be specified**: * `X-Contentful-Version`, you need to specify the last version of the environment alias you are updating with [Delete an environment alias](/references/content-management-api/environment-aliases/delete-an-environment-alias) > **Info** > > You can never delete the `master` environment alias. ## API Docs - Environment aliases [Get all environment aliases of a space](https://contentful.com/developers/docs/references/content-management-api/environment-aliases/get-all-environment-aliases-of-a-space.md) - Environment aliases [Get an environment alias](https://contentful.com/developers/docs/references/content-management-api/environment-aliases/get-an-environment-alias.md) - Environment aliases [Create or update an environment alias](https://contentful.com/developers/docs/references/content-management-api/environment-aliases/create-or-update-an-environment-alias.md) - Environment aliases [Delete an environment alias](https://contentful.com/developers/docs/references/content-management-api/environment-aliases/delete-an-environment-alias.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)