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

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

// 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.
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).
serverFolder	string	No	Server-side upload folder.
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

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'

// 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.
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).
serverFolder	string	Server-side upload folder.
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

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

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.

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

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

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