---
title: "Environments"
description: "<p>Launch environments help you deploy and manage different versions of your project independently. Each environment is auto-deployed to a unique URL and can be customized to match your development workflow.</p>"
url: "https://www.contentstack.com/docs/developers/apis/launch-api/environments"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-01-13"
---

# Environments

Launch environments help you deploy and manage different versions of your project independently. Each environment is auto-deployed to a unique URL and can be customized to match your development workflow.

## Get all Environments

### Get all Environments

**GET** `/projects/{project_uid}/environments`

The Get all Environments request fetches the list of all environments in your project.

#### URL Parameters

- **project_uid** (required)
  Enter the project\_uid of the project where the environments belong.

#### Query Parameters

- **skip** (optional)
  The "skip" parameter will skip a specific number of environments in the output. For example, if there are 20 environments and you want to skip the first 2 to get only the last 12 in the response body, you need to specify "2" here.
- **limit** (optional)
  The "limit" parameter will return a specific number of environments (in between 0-100) in your response based on the value you provide. If there are 20 environments and you want to fetch only 10 environments, set the limit as 10.

#### Headers

- **authorization** (optional)
  Use a bearer token to authenticate if you're not using the authtoken header. Format: Bearer . If provided, the organization\_uid header isn't required.
- **authtoken** (optional)
  Use an authentication token if the Authorization header isn't provided. \*\*Requires the organization\_uid header.\*\* When using authtoken authentication, you must explicitly provide the organization\_uid header. The organization\_uid cannot be derived from project\_uid for Launch REST APIs.
- **x-cs-api-version** (optional)
  Enter the API version. Default is 1.0
- **organization_uid** (optional)
  ⚠️ \*\*REQUIRED when using authtoken authentication\*\* - you must explicitly provide this header. Optional with Authorization Bearer token (organization\_uid can be derived from the token).

#### Sample Response

```json
{
  "pagination": {
    "count": 1,
    "limit": 10,
    "skip": 0
  },
  "environments": [
    {
      "uid": "690xxxxxxxxxxxxxx95f",
      "name": "Test Environment",
      "description": "It is a test environment.",
      "project": "691xxxxxxxxxxxxx9103",
      "gitBranch": "main",
      "buildCommand": "npx @11ty/eleventy",
      "outputDirectory": "./_site",
      "frameworkPreset": "OTHER",
      "environmentVariables": [
        {
          "key": "key1",
          "value": "value1"
        }
      ],
      "autoDeployOnPush": true,
      "nodeVersion": "22",
      "organizationUid": "bltxxxxxxxxxxxx3589",
      "createdAt": "2025-11-06T07:39:19.230Z",
      "updatedAt": "2025-11-06T07:39:53.582Z",
      "createdBy": "bltxxxxxxxxxxxx5783",
      "updatedBy": "bltxxxxxxxxxxxx5783",
      "hasLyticsEnabled": false,
      "isCachePrimingEnabled": false,
      "passwordProtection": {
        "isEnabled": false
      }
    }
  ]
}
```

## Create an Environment

### Create an Environment

**POST** `/projects/{project_uid}/environments`

The Create Environment request lets you create a new environment in your Launch project.

The examples below explain how to create environments using a Git Provider or the File Upload option.  
  

##### Create an Environment by FileUpload:

```
{
  "name": "Test Environment",
  "outputDirectory": "./",
  "frameworkPreset": "OTHER",
  "description": "It is a test environment.",
  "uploadUid": "8dxxxxxx00",
  "buildCommand": "npm run build",
  "serverCommand": "npm run start",
  "environmentVariables": [
    {
      "key": "key1",
      "value": "value1"
    }
  ],
  "autoDeployOnPush": true
}
```

To create an environment using FileUpload, you must run the following APIs step-by-step:

1\. [Get a Signed Upload URL for an Environment](https://www.contentstack.com/docs/developers/apis/launch-api#get-a-signed-upload-url-for-an-environment).

2\. [Upload your ZIP file to Launch](https://www.contentstack.com/docs/developers/launch/upload-your-deployment-zip-file-to-launch) (The signed URL is valid only for 10 minutes).

#### URL Parameters

- **project_uid** (required)
  Enter the project\_uid of the project where you want to create the environment.

#### Headers

- **authorization** (optional)
  Use a bearer token to authenticate if you're not using the authtoken header. Format: Bearer . If provided, the organization\_uid header isn't required.
- **authtoken** (optional)
  Use an authentication token if the Authorization header isn't provided. \*\*Requires the organization\_uid header.\*\* When using authtoken authentication, you must explicitly provide the organization\_uid header. The organization\_uid cannot be derived from project\_uid for Launch REST APIs.
- **x-cs-api-version** (optional)
  Enter the API version. Default is 1.0
- **organization_uid** (optional)
  ⚠️ \*\*REQUIRED when using authtoken authentication\*\* - you must explicitly provide this header. Optional with Authorization Bearer token (organization\_uid can be derived from the token).

#### Sample Response

```json
{
  "environment": {
    "uid": "690xxxxxxxxxxxxxx95f",
    "name": "Test Environment",
    "description": "It is a test environment.",
    "project": "691xxxxxxxxxxxxx9103",
    "gitBranch": "main",
    "buildCommand": "npx @11ty/eleventy",
    "outputDirectory": "./_site",
    "frameworkPreset": "OTHER",
    "environmentVariables": [
      {
        "key": "key1",
        "value": "value1"
      }
    ],
    "autoDeployOnPush": true,
    "nodeVersion": "22",
    "organizationUid": "bltxxxxxxxxxxxx3589",
    "createdAt": "2025-11-06T07:39:19.230Z",
    "updatedAt": "2025-11-06T07:39:53.582Z",
    "createdBy": "bltxxxxxxxxxxxx5783",
    "updatedBy": "bltxxxxxxxxxxxx5783",
    "hasLyticsEnabled": false,
    "isCachePrimingEnabled": false,
    "passwordProtection": {
      "isEnabled": false
    }
  }
}
```

## Get an Environment

### Get an Environment

**GET** `/projects/{project_uid}/environments/{environment_uid}`

The Get an Environment request fetches a specific environment from a project in Launch using the project\_uid and environment\_uid path parameters.

#### URL Parameters

- **environment_uid** (required)
  Enter the environment\_uid of the environment.
- **project_uid** (required)
  Enter the project\_uid of the project where the environments belong.

#### Headers

- **authorization** (optional)
  Use a bearer token to authenticate if you're not using the authtoken header. Format: Bearer . If provided, the organization\_uid header isn't required.
- **authtoken** (optional)
  Use an authentication token if the Authorization header isn't provided. \*\*Requires the organization\_uid header.\*\* When using authtoken authentication, you must explicitly provide the organization\_uid header. The organization\_uid cannot be derived from project\_uid for Launch REST APIs.
- **x-cs-api-version** (optional)
  Enter the API version. Default is 1.0
- **organization_uid** (optional)
  ⚠️ \*\*REQUIRED when using authtoken authentication\*\* - you must explicitly provide this header. Optional with Authorization Bearer token (organization\_uid can be derived from the token).

#### Sample Response

```json
{
  "environment": {
    "uid": "690xxxxxxxxxxxxxx95f",
    "name": "Test Environment",
    "description": "It is a test environment.",
    "project": "691xxxxxxxxxxxxx9103",
    "gitBranch": "main",
    "buildCommand": "npx @11ty/eleventy",
    "outputDirectory": "./_site",
    "frameworkPreset": "OTHER",
    "environmentVariables": [
      {
        "key": "key1",
        "value": "value1"
      }
    ],
    "autoDeployOnPush": true,
    "nodeVersion": "22",
    "organizationUid": "bltxxxxxxxxxxxx3589",
    "createdAt": "2025-11-06T07:39:19.230Z",
    "updatedAt": "2025-11-06T07:39:53.582Z",
    "createdBy": "bltxxxxxxxxxxxx5783",
    "updatedBy": "bltxxxxxxxxxxxx5783",
    "hasLyticsEnabled": false,
    "isCachePrimingEnabled": false,
    "passwordProtection": {
      "isEnabled": false
    }
  }
}
```

## Update an Environment

### Update an Environment

**PUT** `/projects/{project_uid}/environments/{environment_uid}`

The Update an Environment request lets you update an existing environment in your project.

#### URL Parameters

- **environment_uid** (required)
  Enter the environment\_uid of the environment that must be updated.
- **project_uid** (required)
  Enter the project\_uid of the project where the environments belong.

#### Headers

- **authorization** (optional)
  Use a bearer token to authenticate if you're not using the authtoken header. Format: Bearer . If provided, the organization\_uid header isn't required.
- **authtoken** (optional)
  Use an authentication token if the Authorization header isn't provided. \*\*Requires the organization\_uid header.\*\* When using authtoken authentication, you must explicitly provide the organization\_uid header. The organization\_uid cannot be derived from project\_uid for Launch REST APIs.
- **x-cs-api-version** (optional)
  Enter the API version. Default is 1.0
- **organization_uid** (optional)
  ⚠️ \*\*REQUIRED when using authtoken authentication\*\* - you must explicitly provide this header. Optional with Authorization Bearer token (organization\_uid can be derived from the token).

#### Sample Response

```json
{
  "environment": {
    "uid": "690xxxxxxxxxxxxxx95f",
    "name": "Test02",
    "description": "It is a dev environment 2.",
    "project": "691xxxxxxxxxxxxx9103",
    "gitBranch": "main",
    "buildCommand": "npx @11ty/eleventy",
    "outputDirectory": "./_site",
    "frameworkPreset": "OTHER",
    "environmentVariables": [
      {
        "key": "NEXT_PUBLIC_TEST_VARIABLE",
        "value": "TEST_VALUE"
      }
    ],
    "autoDeployOnPush": true,
    "nodeVersion": "22",
    "organizationUid": "bltxxxxxxxxxxxx3589",
    "createdAt": "2025-11-06T07:39:19.230Z",
    "updatedAt": "2025-11-06T07:39:53.582Z",
    "createdBy": "bltxxxxxxxxxxxx5783",
    "updatedBy": "bltxxxxxxxxxxxx5783",
    "hasLyticsEnabled": true,
    "isCachePrimingEnabled": true,
    "passwordProtection": {
      "isEnabled": true
    }
  }
}
```

## Delete an Environment

### Delete an Environment

**DELETE** `/projects/{project_uid}/environments/{environment_uid}`

The Delete an Environment request lets you delete an existing environment in your project.

#### URL Parameters

- **environment_uid** (required)
  Enter the environment\_uid of the environment that must be deleted.
- **project_uid** (required)
  Enter the project\_uid of the project where the environments belong.

#### Headers

- **authorization** (optional)
  Use a bearer token to authenticate if you're not using the authtoken header. Format: Bearer . If provided, the organization\_uid header isn't required.
- **authtoken** (optional)
  Use an authentication token if the Authorization header isn't provided. \*\*Requires the organization\_uid header.\*\* When using authtoken authentication, you must explicitly provide the organization\_uid header. The organization\_uid cannot be derived from project\_uid for Launch REST APIs.
- **x-cs-api-version** (optional)
  Enter the API version. Default is 1.0
- **organization_uid** (optional)
  ⚠️ \*\*REQUIRED when using authtoken authentication\*\* - you must explicitly provide this header. Optional with Authorization Bearer token (organization\_uid can be derived from the token).

#### Sample Response

```json
Environment deleted successfully.
```

## Revalidate CDN Cache

### Revalidate CDN Cache

**POST** `/projects/{project_uid}/environments/{environment_uid}/revalidate-cdn-cache`

The Revalidate CDN Cache request lets you view the latest content after changes to your environment. The CDN checks for updates and fetches fresh content from the origin server if needed, without manually purging the cache. This helps maintain consistency across all domains sharing the same CDN configuration.

The examples below provide a detailed explanation on how to revalidate CDN cache with various options.  
  

##### Purge cache of a specific path:

```
{
  "cachePath": {
    "path": "/blog",
    "isPrefix": false
  }
}
```

Use the cachePath object with isPrefix set to false to purge the cache for an exact path (e.g., /blog).  
  

##### Purge cache by cache tags:

```
{
  "cacheTags": [
    "blogs"
  ]
}
```

Use cacheTags to purge the cache for routes tagged with specific cache tags.  
  

##### Purge cache for specific hostnames:

```
{
  "hostnames": [
    "test.contentstackapps.com"
  ]
}
```

Use hostnames to purge the cache for specific hostnames.

#### URL Parameters

- **environment_uid** (required)
  Enter the environment\_uid of the environment.
- **project_uid** (required)
  Enter the project\_uid of the project where the environments belong.

#### Headers

- **authorization** (optional)
  Use a bearer token to authenticate if you're not using the authtoken header. Format: Bearer . If provided, the organization\_uid header isn't required.
- **authtoken** (optional)
  Use an authentication token if the Authorization header isn't provided. \*\*Requires the organization\_uid header.\*\* When using authtoken authentication, you must explicitly provide the organization\_uid header. The organization\_uid cannot be derived from project\_uid for Launch REST APIs.
- **x-cs-api-version** (optional)
  Enter the API version. Default is 1.0
- **organization_uid** (optional)
  ⚠️ \*\*REQUIRED when using authtoken authentication\*\* - you must explicitly provide this header. Optional with Authorization Bearer token (organization\_uid can be derived from the token).

#### Sample Response

```json
{
  "message": "The CDN cache revalidation task has been initiated."
}
```