---
title: Environment variables | Runware Docs
url: https://runware.ai/docs/serverless/api-environment-variables
description: Read and write the environment an application's workers run with.
relatedDocuments:
  - https://runware.ai/docs/serverless/api
  - https://runware.ai/docs/serverless/environment-variables
  - https://runware.ai/docs/serverless/secrets
---
## Introduction

An app's environment is **part of the version snapshot its workers are rendered from**, so writing a variable is not an in-place edit. A write that changes the stored value records a new version carrying the same image and **rolls the app**, while a write of the value already stored keeps that version and those workers.

> [!WARNING]
> A write while a rollout is **still in flight returns `409` and is discarded**, so setting several variables one at a time is that many sequential rollouts. Replace the whole set in one request with `PATCH /v1/apps/{appId}` instead. See [Environment variables](https://runware.ai/docs/serverless/environment-variables).

## List environment variables

GETapi.serverless.runware.ai/v1/apps/{appId}/environment-variables

### [Request](#list-app-environment-variables-request)

Path

### [appId](#list-app-environment-variables-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

Query

### [environment](#list-app-environment-variables-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [limit](#list-app-environment-variables-query-limit)

- **Type**: `integer`
- **Format**: `int32`
- **Min**: `1`
- **Max**: `100`
- **Default**: `20`

Maximum number of items to return.

### [cursor](#list-app-environment-variables-query-cursor)

- **Type**: `string`

Opaque pagination cursor returned by a previous call, as `nextCursor` or, on the operations that offer one, `prevCursor`.

### [Response](#list-app-environment-variables-response)

### [nextCursor](#list-app-environment-variables-response-nextcursor)

- **Type**: `string (nullable)`

Cursor for the next page. Null when there are no more items.

### [data](#list-app-environment-variables-response-data)

- **Type**: `object[] (6 properties)`

#### [id](#list-app-environment-variables-response-data-id)

- **Type**: `string (uuid)`
- **Format**: `UUID v4`

#### [appId](#list-app-environment-variables-response-data-appid)

- **Type**: `string`
- **Min**: `6`
- **Max**: `30`

Immutable app identifier. Unique among the authenticated organization's live apps in one environment: it cannot be changed after creation, it becomes available again once the app it named reaches `deleted`, and the same id may run once in each environment as a separate copy.

#### [key](#list-app-environment-variables-response-data-key)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

POSIX-style environment variable name. Letters, digits, and underscore. Must start with a letter or underscore. Matched by the `deployment_configs` column CHECK so a valid-by-contract request cannot 500 at INSERT.

#### [value](#list-app-environment-variables-response-data-value)

- **Type**: `string`
- **Required**: true

#### [createdAt](#list-app-environment-variables-response-data-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

#### [updatedAt](#list-app-environment-variables-response-data-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#list-app-environment-variables-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Update an environment variable

PUTapi.serverless.runware.ai/v1/apps/{appId}/environment-variables/{variableName}

Sets one environment variable, creating it if absent. Names the platform sets in the worker's environment are rejected with `422`, as they are on create. A write that changes the stored value records a new version carrying the stored environment set and the same image. That stored set is what a successful deploy leaves in place, which can still hold values a rollback did not revert. If that image is deployable, the write pins it as `activeVersionId` and rolls the workload when the app can take one (`active`, `initializing`, or `failed` which becomes `initializing`). The pin is the rollout target. A worker of the new version answering tasks is a later fact. See `AppEvent`. A `stopped` or `stopping` app pins the version and rolls it on `resume`. A write that leaves the stored value unchanged records no version and does not roll. A write while a rollout of this app is still in flight, or to a `failed` app while the workers of its failed rollout are still stopping, returns `409 Conflict` and does not store the value. Each changing write is serialized behind that rollout, so setting several variables one at a time is that many sequential rolls with `409`s between them. Replace the whole set in one request with `PATCH /v1/apps/{appId}` `environmentVariables`. A write to a `failed` app past the environment's worker or GPU cap returns `409` typed `environment-cap-reached`, and one in an environment its budget pauses `409` typed `environment-paused`; neither stores the value, as that `PATCH` does. An app holds at most 100 environment bindings in total, plain variables plus attached secrets, the same combined ceiling `AppCreate.environmentVariables` declares (create rejects secrets in-request, attach grows the set later). Overwriting an existing variable is always allowed. Adding one past the ceiling returns `422`. The name must not collide with a secret already attached to this app (the secret's injected env var name). Secrets and plain env vars reach the app as one set of environment variables. Only one value can reach the app under a name. A duplicate would leave one value silently shadowing the other, so the server rejects it with `422`. The reverse check applies on attach.

### [Request](#update-app-environment-variable-request)

Path

### [appId](#update-app-environment-variable-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

### [variableName](#update-app-environment-variable-path-variablename)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

POSIX-style environment variable name. Letters, digits, and underscore. Must start with a letter or underscore. Matched by the `deployment_configs` column CHECK so a valid-by-contract request cannot 500 at INSERT.

Query

### [environment](#update-app-environment-variable-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [value](#update-app-environment-variable-body-value)

- **Type**: `string`
- **Required**: true
- **Max**: `4096`

Value delivered to the workload as this variable's value. Write it literally: do not use `$(NAME)` or `$$` in it, as the platform does not guarantee how it treats either sequence. Bounded because all of an app's variables are stored together in one Kubernetes object, which as a whole has to fit what the Kubernetes API server accepts. The same `maxLength` create applies, so one path cannot be used to exceed the other.

### [Response](#update-app-environment-variable-response)

### [id](#update-app-environment-variable-response-id)

- **Type**: `string (uuid)`
- **Format**: `UUID v4`

### [appId](#update-app-environment-variable-response-appid)

- **Type**: `string`
- **Min**: `6`
- **Max**: `30`

Immutable app identifier. Unique among the authenticated organization's live apps in one environment: it cannot be changed after creation, it becomes available again once the app it named reaches `deleted`, and the same id may run once in each environment as a separate copy.

### [key](#update-app-environment-variable-response-key)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

POSIX-style environment variable name. Letters, digits, and underscore. Must start with a letter or underscore. Matched by the `deployment_configs` column CHECK so a valid-by-contract request cannot 500 at INSERT.

### [value](#update-app-environment-variable-response-value)

- **Type**: `string`
- **Required**: true

### [createdAt](#update-app-environment-variable-response-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [updatedAt](#update-app-environment-variable-response-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#update-app-environment-variable-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true"><code class="component-Code">conflict</code> means the app's state refuses the request. <code class="component-Code">environment-cap-reached</code> means the request would take the environment past its resolved worker or GPU cap: what the environment's other apps hold (each the larger of its live workers and its keep-warm floor, counted as at least one while initializing and as <code class="component-Code">minWorkers</code> while active), plus the workers this request starts (at least one, or its keep-warm floor when higher) and their GPUs. Nothing is changed. After a cap is lowered this can refuse deploys until workers fall or the cap is raised. Stop or scale down another app, or raise the cap, then retry. <code class="component-Code">environment-paused</code> means the environment's spend this UTC month has reached its monthly budget with <code class="component-Code">pauseAtBudget</code> on. Nothing is changed. Raise the budget past the spend, or wait for the month to turn, then retry.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Delete an environment variable

DELETEapi.serverless.runware.ai/v1/apps/{appId}/environment-variables/{variableName}

Removes one environment variable. A successful delete records a new version carrying the remaining stored environment set and the same image. That stored set is what a successful deploy leaves in place, which can still hold values a rollback did not revert. If that image is deployable, the delete pins it as `activeVersionId` and rolls the workload when the app can take one (`active`, `initializing`, or `failed` which becomes `initializing`). The pin is the rollout target. A worker of the new version answering tasks is a later fact. See `AppEvent`. A `stopped` or `stopping` app pins the version and rolls it on `resume`. A delete of a key that is present while a rollout of this app is still in flight, or while the workers of a `failed` app's failed rollout are still stopping, returns `409 Conflict` and does not remove the value. A name that is not present returns `404` even during that window. A delete on a `failed` app past the environment's worker or GPU cap returns `409` typed `environment-cap-reached`, and one in an environment its budget pauses `409` typed `environment-paused`; neither removes the value.

### [Request](#delete-app-environment-variable-request)

Path

### [appId](#delete-app-environment-variable-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

### [variableName](#delete-app-environment-variable-path-variablename)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

POSIX-style environment variable name. Letters, digits, and underscore. Must start with a letter or underscore. Matched by the `deployment_configs` column CHECK so a valid-by-contract request cannot 500 at INSERT.

Query

### [environment](#delete-app-environment-variable-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Errors](#delete-app-environment-variable-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true"><code class="component-Code">conflict</code> means the app's state refuses the request. <code class="component-Code">environment-cap-reached</code> means the request would take the environment past its resolved worker or GPU cap: what the environment's other apps hold (each the larger of its live workers and its keep-warm floor, counted as at least one while initializing and as <code class="component-Code">minWorkers</code> while active), plus the workers this request starts (at least one, or its keep-warm floor when higher) and their GPUs. Nothing is changed. After a cap is lowered this can refuse deploys until workers fall or the cap is raised. Stop or scale down another app, or raise the cap, then retry. <code class="component-Code">environment-paused</code> means the environment's spend this UTC month has reached its monthly budget with <code class="component-Code">pauseAtBudget</code> on. Nothing is changed. Raise the budget past the spend, or wait for the month to turn, then retry.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>