Environment variables

Read and write the environment an application's workers run with.

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, and a write that leaves the value unchanged records nothing at all.

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.

List environment variables

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

Request

Path

appId stringrequiredmin: 6max: 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 stringmin: 1max: 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 integerint32min: 1max: 100default: 20: Maximum number of items to return.

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

Response

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

data object[]

Array items6 properties each

id string (uuid)UUID v4

appId stringmin: 6max: 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 stringrequiredmin: 1max: 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 stringrequired

createdAt string (date-time)date-time

updatedAt string (date-time)date-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

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 409s 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

Path

appId stringrequiredmin: 6max: 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 stringrequiredmin: 1max: 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 stringmin: 1max: 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 stringrequiredmax: 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

id string (uuid)UUID v4

appId stringmin: 6max: 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 stringrequiredmin: 1max: 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 stringrequired

createdAt string (date-time)date-time

updatedAt string (date-time)date-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`409`	`conflict` means the app's state refuses the request. `environment-cap-reached` 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 `minWorkers` 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. `environment-paused` means the environment's spend this UTC month has reached its monthly budget with `pauseAtBudget` on. Nothing is changed. Raise the budget past the spend, or wait for the month to turn, then retry.
`413`	The request body exceeds its size limit: 10 MiB on `invoke-sync` and `invoke-async`, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. `detail` names the limit in bytes.
`415`	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 `application/json` that cannot be parsed returns `400`. One that parses and breaks the schema returns `422`. A body sent with no Content-Type is the same refusal.
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

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

Path

appId stringrequiredmin: 6max: 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 stringrequiredmin: 1max: 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 stringmin: 1max: 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

Status	When
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`409`	`conflict` means the app's state refuses the request. `environment-cap-reached` 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 `minWorkers` 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. `environment-paused` means the environment's spend this UTC month has reached its monthly budget with `pauseAtBudget` on. Nothing is changed. Raise the budget past the spend, or wait for the month to turn, then retry.
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable