<!-- Source: https://www.stormkit.io/docs/api/environments -->
<!-- Title: Environments API -->
<!-- Description: API Documentation for managing environments through Stormkit API. -->

# Environments API

## Overview

The Environments API lets you create, update, and delete environments, and pull environment variable values programmatically.

> **Environment variable values are masked.** For security, variable _values_ are blanked out (returned as empty strings) in every response that lists or describes an environment — `GET /v1/envs`, the deployment endpoints, and the MCP tools. They are also masked in **build logs** (the variable names are listed, but the values are replaced with `***************`). The only exception is a fixed set of Stormkit [system variables](/docs/deployments/system-variables) — `SK_APP_ID`, `SK_BRANCH_NAME`, `SK_COMMIT_SHA`, `SK_DEPLOYMENT_ID`, `SK_DEPLOYMENT_URL`, `SK_ENV`, `SK_ENV_ID`, and `SK_ENV_URL` — which are not secrets and keep their values in build logs. (A user-defined variable that happens to start with `SK_` is still masked.) To read the actual values, use the dedicated [`GET /v1/env/pull`](#get-v1envpull) endpoint described below.

---

## GET /v1/envs

Returns all environments configured for an application. At most 50 environments are returned.

**Base URL:** `https://api.stormkit.io`

**Authentication:** At least an app-level API key passed as the `Authorization` header. When using a team- or user-level key, `appId` must be provided as a query parameter.

### Query parameters

| Parameter | Type   | Required    | Description                                                                           |
| --------- | ------ | ----------- | ------------------------------------------------------------------------------------- |
| `appId`   | string | Conditional | Required when using a team- or user-level API key to identify the target application. |

### Response — 200 OK

| Field          | Type  | Description                   |
| -------------- | ----- | ----------------------------- |
| `environments` | array | Array of environment objects. |

> Each environment object includes its build configuration, but environment variable **values are masked** — `build.vars` is returned with empty strings for every value. Use [`GET /v1/env/pull`](#get-v1envpull) to retrieve the actual values.

### Error responses

| Status | Condition                                                      |
| ------ | -------------------------------------------------------------- |
| `403`  | Missing/invalid API key or insufficient permissions.           |
| `404`  | App not found (team/user key with missing or invalid `appId`). |
| `500`  | Internal server error.                                         |

### Examples

```bash
# Using an app-level key (appId derived from token)
curl -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/json' \
     'https://api.stormkit.io/v1/envs'
```

```json
// Example response
{
  "environments": [
    {
      "id": "305",
      "name": "production",
      "branch": "main"
    },
    {
      "id": "306",
      "name": "staging",
      "branch": "staging"
    }
  ]
}
```

---

## POST /v1/env

Creates a new environment for an application.

**Base URL:** `https://api.stormkit.io`

**Authentication:** API key with at least environment-level scope. Environment-, app-, team-, or user-level keys are accepted as long as they have access to the app that owns the environment and a valid `envId` is provided.

### Request body

| Field                | Type                    | Required | Description                                                                                                 |
| -------------------- | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `name`               | string                  | **Yes**  | Environment name. Only alphanumeric characters and hyphens are allowed. Double hyphens (`--`) are reserved. |
| `branch`             | string                  | **Yes**  | Default git branch for this environment.                                                                    |
| `apiFolder`          | string                  | No       | Repository folder containing serverless API functions.                                                      |
| `apiPathPrefix`      | string                  | No       | URL path prefix for API calls (default: `/api`).                                                            |
| `autoDeploy`         | boolean                 | No       | Whether to trigger automatic deployments.                                                                   |
| `autoDeployBranches` | string                  | No       | Glob/regex pattern to filter which branches trigger auto-deploys. Setting this enables `autoDeploy`.        |
| `autoDeployCommits`  | string                  | No       | Glob/regex pattern to filter which commit messages trigger auto-deploys. Setting this enables `autoDeploy`. |
| `autoPublish`        | boolean                 | No       | Whether to automatically publish successful deployments.                                                    |
| `buildCmd`           | string                  | No       | Command to build the application.                                                                           |
| `cacheDirs`          | `string[]`              | No       | Directories (relative to `workDir`) restored before the install step and snapshotted after a successful build. Best for compiler caches like `.next/cache` or `.turbo`. Requires a premium or ultimate subscription on Stormkit Cloud; always enabled on self-hosted. |
| `distFolder`         | string                  | No       | Output folder containing the build artifacts.                                                               |
| `envVars`            | `Record<string,string>` | No       | Environment variables to inject into deployments.                                                           |
| `errorFile`          | string                  | No       | File served on errors. Must be inside `distFolder`.                                                         |
| `headers`            | string                  | No       | Inline custom HTTP response headers.                                                                        |
| `headersFile`        | string                  | No       | Path to the custom HTTP headers file.                                                                       |
| `installCmd`         | string                  | No       | Command to install dependencies.                                                                            |
| `markdown`           | boolean                 | No       | Serve the `.md` twin of a page to clients sending `Accept: text/markdown`. Off unless enabled.               |
| `markdownConvert`    | boolean                 | No       | Convert a page's HTML when it ships no `.md` twin. Requires `markdown`. Off unless enabled.                  |
| `previewLinks`       | boolean                 | No       | Whether Stormkit posts a preview URL on pull/merge requests.                                                |
| `redirects`          | `Redirect[]`            | No       | Inline redirect/rewrite rules. See the Redirects API for the `Redirect` object shape.                       |
| `redirectsFile`      | string                  | No       | Path to a file containing redirect/rewrite rules.                                                           |
| `serverCmd`          | string                  | No       | Command to start the server (self-hosted only).                                                             |
| `statusChecks`       | `StatusCheck[]`         | No       | Post-deployment commands to run. See `StatusCheck` object below.                                            |
| `workDir`            | string                  | No       | Working directory relative to the repository root where install/build commands run. Defaults to repo root.  |

**`StatusCheck` object:**

| Field         | Type   | Description                             |
| ------------- | ------ | --------------------------------------- |
| `name`        | string | Human-readable name of the check.       |
| `cmd`         | string | Shell command to execute.               |
| `description` | string | Description of what the check verifies. |

### Response — 201 Created

| Field   | Type   | Description                          |
| ------- | ------ | ------------------------------------ |
| `envId` | string | ID of the newly created environment. |

### Error responses

| Status | Condition                                            |
| ------ | ---------------------------------------------------- |
| `400`  | Missing or invalid fields (see `errors` array).      |
| `403`  | Missing/invalid API key or insufficient permissions. |
| `409`  | An environment with the same name already exists.    |
| `500`  | Internal server error.                               |

### Example

```bash
curl -X POST \
     -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/json' \
     -d '{"appId":"1510","branch":"main","name":"staging","envVars":{"NODE_ENV":"staging"}}' \
     'https://api.stormkit.io/v1/env'
```

```json
// Example response
{
  "envId": "305"
}
```

---

## PUT /v1/env

Updates the configuration of an existing environment. Only the fields provided in the request body are changed — all other fields retain their current values.

**Base URL:** `https://api.stormkit.io`

**Authentication:** Environment-level API key. When using an app- or higher-level key, `envId` must be provided in the request body.

### Request body

All fields are **optional**. Only the fields you include will be updated.

| Field                | Type                    | Description                                                                                                                                  |
| -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `envId`              | string                  | ID of the environment to update. **Required when using an app-, team-, or user-level API key; ignored when using an environment-level key.** |
| `name`               | string                  | Environment name. Only alphanumeric characters and hyphens are allowed. Double hyphens (`--`) are reserved.                                  |
| `branch`             | string                  | Default git branch for this environment.                                                                                                     |
| `apiFolder`          | string                  | Repository folder containing serverless API functions.                                                                                       |
| `apiPathPrefix`      | string                  | URL path prefix for API calls (default: `/api`).                                                                                             |
| `autoDeploy`         | boolean                 | Whether to trigger automatic deployments.                                                                                                    |
| `autoDeployBranches` | string                  | Glob/regex pattern to filter which branches trigger auto-deploys. Setting this enables `autoDeploy`.                                         |
| `autoDeployCommits`  | string                  | Glob/regex pattern to filter which commit messages trigger auto-deploys. Setting this enables `autoDeploy`.                                  |
| `autoPublish`        | boolean                 | Whether to automatically publish successful deployments.                                                                                     |
| `buildCmd`           | string                  | Command to build the application.                                                                                                            |
| `cacheDirs`          | `string[]`              | Directories (relative to `workDir`) restored before the install step and snapshotted after a successful build. Replaces the existing list; pass `[]` to disable caching. Requires a premium or ultimate subscription on Stormkit Cloud; always enabled on self-hosted. |
| `distFolder`         | string                  | Output folder containing the build artifacts.                                                                                                |
| `envVars`            | `Record<string,string>` | Environment variables to inject into deployments. Replaces all existing variables.                                                           |
| `errorFile`          | string                  | File served on errors. Must be inside `distFolder`.                                                                                          |
| `headers`            | string                  | Inline custom HTTP response headers.                                                                                                         |
| `headersFile`        | string                  | Path to the custom HTTP headers file.                                                                                                        |
| `installCmd`         | string                  | Command to install dependencies.                                                                                                             |
| `markdown`           | boolean                 | Serve the `.md` twin of a page to clients sending `Accept: text/markdown`. Off unless enabled.                                                |
| `markdownConvert`    | boolean                 | Convert a page's HTML when it ships no `.md` twin. Requires `markdown`. Off unless enabled.                                                   |
| `previewLinks`       | boolean                 | Whether Stormkit posts a preview URL on pull/merge requests.                                                                                 |
| `redirects`          | `Redirect[]`            | Inline redirect/rewrite rules. Replaces all existing inline rules. See the Redirects API for the `Redirect` object shape.                    |
| `redirectsFile`      | string                  | Path to a file containing redirect/rewrite rules.                                                                                            |
| `serverCmd`          | string                  | Command to start the server (self-hosted only).                                                                                              |
| `statusChecks`       | `StatusCheck[]`         | Post-deployment commands to run. Replaces all existing checks. See `StatusCheck` in `POST /v1/env`.                                          |
| `workDir`            | string                  | Working directory relative to the repository root where install/build commands run. Defaults to repo root.                                   |

### Response — 200 OK

| Field | Type    | Description                   |
| ----- | ------- | ----------------------------- |
| `ok`  | boolean | `true` when update succeeded. |

### Error responses

| Status | Condition                                                      |
| ------ | -------------------------------------------------------------- |
| `400`  | Invalid field values (e.g. malformed headers, duplicate name). |
| `403`  | Missing/invalid API key or insufficient permissions.           |
| `404`  | Environment not found.                                         |
| `500`  | Internal server error.                                         |

### Example

```bash
curl -X PUT \
     -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/json' \
     -d '{"envId":"305","buildCmd":"npm run build:prod","distFolder":"dist","autoPublish":true}' \
     'https://api.stormkit.io/v1/env'
```

---

## DELETE /v1/env

Deletes an environment by its ID.

**Base URL:** `https://api.stormkit.io`

**Authentication:** App-level API key (the key must be scoped to the app that owns the environment).

### Query parameters

| Parameter | Type   | Required | Description                                                               |
| --------- | ------ | -------- | ------------------------------------------------------------------------- |
| `envId`   | number | **Yes**  | The ID of the environment to delete. Alternatively `id` is also accepted. |

### Response — 200 OK

| Field | Type    | Description                     |
| ----- | ------- | ------------------------------- |
| `ok`  | boolean | `true` when deletion succeeded. |

### Error responses

| Status | Condition                                            |
| ------ | ---------------------------------------------------- |
| `403`  | Missing/invalid API key or insufficient permissions. |
| `404`  | No environment found with the given ID.              |
| `500`  | Internal server error.                               |

### Example

```bash
curl -X DELETE \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/env?envId=305'
```

---

## GET /v1/env/pull

Returns all environment variables for the specified environment, **including their plaintext values**. This is the only endpoint that reveals variable values — every other endpoint masks them. The response is a flat JSON object where each key is a variable name and each value is the variable's value.

**Base URL:** `https://api.stormkit.io`

**Authentication:** Environment-level API key passed as the `Authorization` header. To generate one: **Your App** → **Your Environment** → **Config** → **Other** → **API Keys**. When using an app or higher-level key, `envId` must be provided as a query parameter.

> **Access & auditing**
>
> - Any **member** of the environment's team may reveal the values — whether through an **API key** or as a **dashboard (session) user**, regardless of role. (Editing variables requires revealing them first, so this keeps env-var management available to all members.)
> - On **Enterprise** licenses, every reveal is written to the **activity feed**, attributed to the user (dashboard) or to the API key's token name (API key).

### Query parameters

| Parameter | Type   | Required                                            | Description                                                                                                                                          |
| --------- | ------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `envId`   | number | **Yes** (unless using an environment-level API key) | The ID of the environment whose variables to retrieve. Not required when using an environment-level key — the environment is derived from the token. |

### Response — 200 OK

A flat JSON object of environment variable key/value pairs.

```json
{
  "NODE_ENV": "production",
  "API_URL": "https://api.my-app.com"
}
```

### Error responses

| Status | Condition                                            |
| ------ | ---------------------------------------------------- |
| `403`  | Missing/invalid API key or insufficient permissions. |
| `500`  | Internal server error.                               |

### Examples

```bash
# Using an environment-level key (envId derived from token)
curl -X GET \
     -H 'Authorization: <env_api_key>' \
     'https://api.stormkit.io/v1/env/pull'
```

```bash
# Using an app or higher-level key (envId required as query parameter)
curl -X GET \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/env/pull?envId=305'
```

### MCP limitation

The Stormkit MCP server intentionally has **no tool to reveal environment variable values**. MCP tools such as `list_environments`, `get_deployment`, and `list_deployments` return variable names with masked (empty) values, so an AI assistant connected over MCP never has access to your secrets. To read the actual values, call this `GET /v1/env/pull` endpoint directly with an API key.