Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
environments

Set environment variables

Create or update environment variables for an environment in a single atomic request.

By default this is an upsert: each variable in the payload is created if new or fully overwritten if the key already exists, and any variable not in the payload is left untouched. This lets you change one variable without re-sending the others, which matters for write-only secrets you can no longer read back.

Set prune: true to make it a full replace instead: after upserting, every variable not in the payload is deleted. Sending prune: true with an empty variables list resets the environment by deleting every variable.

Each variable is written exactly as sent, never merged, so omitted optional fields fall back to their defaults rather than the previous value. Values are always encrypted at rest. Set kind: recoverable to allow a value to be read back; it defaults to writeonly, which can never be read back through the API.

Required Permissions

Your root key must have one of the following permissions:

  • environment.*.set_environment_variables (for any environment)
  • environment.<environment_id>.set_environment_variables (for a specific environment)
post/v2/environments.setEnvironmentVariables

Request body

projectstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

appstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

environmentstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

pruneboolean

Optional. Defaults to false. When false, the variables above are upserted and any existing variable not in the list is kept. When true, this becomes a full replace: after upserting, every variable not in the list is deleted. Combined with an empty variables list, prune: true resets the entire environment by deleting every variable.

Example request

{
  "project": "proj_1234abcd",
  "app": "proj_1234abcd",
  "environment": "proj_1234abcd",
  "variables": [
    {
      "key": "DATABASE_URL",
      "value": "postgresql://user:pass@host:5432/db",
      "kind": "writeonly",
      "description": "Primary database connection string"
    }
  ]
}

Response

Successfully set the environment variables.

dataEmptyResponse required

Empty response object by design. A successful response indicates this operation was successfully executed.

Example response

{
  "meta": {
    "requestId": "req_123"
  }
}