Environments

View as Markdown

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

GEThttps://launch-api.contentstack.com/projects/{project_uid}/environments

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

Sample Response

Status|200 OK

{
  "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",
      "isCachePrimingEnabled": false,
      "passwordProtection": {
        "isEnabled": false
      }
    }
  ]
}

Create an Environment

POSThttps://launch-api.contentstack.com/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.

2. Upload your ZIP file to Launch (The signed URL is valid only for 10 minutes).

Sample Request

{
  "name": "Test Environment",
  "outputDirectory": "./_site",
  "frameworkPreset": "OTHER",
  "description": "It is a test environment.",
  "gitBranch": "main",
  "buildCommand": "npx @11ty/eleventy",
  "environmentVariables": [
    {
      "key": "key1",
      "value": "value1"
    }
  ],
  "autoDeployOnPush": true
}

Sample Response

Status|200 OK

{
  "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",
    "isCachePrimingEnabled": false,
    "passwordProtection": {
      "isEnabled": false
    }
  }
}

Get an Environment

GEThttps://launch-api.contentstack.com/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.

Sample Response

Status|200 OK

{
  "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",
    "isCachePrimingEnabled": false,
    "passwordProtection": {
      "isEnabled": false
    }
  }
}

Update an Environment

PUThttps://launch-api.contentstack.com/projects/{project_uid}/environments/{environment_uid}

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

Sample Request

{
  "name": "Test02",
  "outputDirectory": "./_site",
  "frameworkPreset": "OTHER",
  "description": "It is a dev environment 2.",
  "gitBranch": "dev",
  "buildCommand": "npx @11ty/eleventy",
  "autoDeployOnPush": true,
  "isStreamingEnabled": true,
  "isCachePrimingEnabled": true,
  "passwordProtection": {
    "isEnabled": true,
    "username": "test-user",
    "password": "test-password"
  },
  "environmentVariables": [
    {
      "key": "NEXT_PUBLIC_TEST_VARIABLE",
      "value": "TEST_VALUE"
    }
  ]
}

Sample Response

Status|200 OK

{
  "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",
    "isCachePrimingEnabled": true,
    "passwordProtection": {
      "isEnabled": true
    }
  }
}

Delete an Environment

DELETEhttps://launch-api.contentstack.com/projects/{project_uid}/environments/{environment_uid}

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

Sample Response

Status|204 No Content

Environment deleted successfully.

Revalidate CDN Cache

POSThttps://launch-api.contentstack.com/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.

Sample Request

{
  "cachePath": {
    "path": "/blog",
    "isPrefix": true
  }
}

Sample Response

Status|200 OK

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

{ "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", "isCachePrimingEnabled": false, "passwordProtection": { "isEnabled": false } } ] }

{ "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 }

{ "name": "Test Environment", "outputDirectory": "./_site", "frameworkPreset": "OTHER", "description": "It is a test environment.", "gitBranch": "main", "buildCommand": "npx @11ty/eleventy", "environmentVariables": [ { "key": "key1", "value": "value1" } ], "autoDeployOnPush": true }

{ "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", "isCachePrimingEnabled": false, "passwordProtection": { "isEnabled": false } } }

{ "name": "Test02", "outputDirectory": "./_site", "frameworkPreset": "OTHER", "description": "It is a dev environment 2.", "gitBranch": "dev", "buildCommand": "npx @11ty/eleventy", "autoDeployOnPush": true, "isStreamingEnabled": true, "isCachePrimingEnabled": true, "passwordProtection": { "isEnabled": true, "username": "test-user", "password": "test-password" }, "environmentVariables": [ { "key": "NEXT_PUBLIC_TEST_VARIABLE", "value": "TEST_VALUE" } ] }

{ "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", "isCachePrimingEnabled": true, "passwordProtection": { "isEnabled": true } } }

Environments

Get all Environments

Create an Environment

Create an Environment by FileUpload:

Get an Environment

Update an Environment

Delete an Environment

Revalidate CDN Cache

Purge cache of a specific path:

Purge cache by cache tags:

Purge cache for specific hostnames:

Environments

Get all Environments

URL Parameters

Query Parameters

Headers

Create an Environment

Create an Environment by FileUpload:

URL Parameters

Headers

Get an Environment

URL Parameters

Headers

Update an Environment

URL Parameters

Headers

Delete an Environment

URL Parameters

Headers

Revalidate CDN Cache

Purge cache of a specific path:

Purge cache by cache tags:

Purge cache for specific hostnames:

URL Parameters

Headers

URL Parameters

Query Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers

URL Parameters

Headers