> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Add or edit environment variables

> Add or update environment variables with POST /v2/apps/{app_id}/envs. Variables left out of the body stay untouched, which suits rotating a single key.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Requires an API key with the `envs:write` [scope](/en/api-reference/authentication#scopes).

Use this endpoint to add new environment variables or update specific ones without touching the rest. Existing variables that aren't included in the request body are left untouched, which makes it the safest option for incremental changes like rotating a single API key.

Static applications don't support environment variables and return an error. The full set is capped at 256 variables per application, with a 1024-character limit per key and 4096 characters per value. On workspace-shared applications, the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership.

To replace the entire variable set instead of merging, use [Overwrite Variables](/en/api-reference/endpoint/apps/envs/overwrite). To remove specific keys, see [Remove Variables](/en/api-reference/endpoint/apps/envs/remove), and to read the current values, see [List Variables](/en/api-reference/endpoint/apps/envs/get).

## Parameters

<ParamField path="app_id" type="string" placeholder="App ID" required>
  The application ID.
</ParamField>

<ParamField body="envs" type="object" required>
  The key and value of environment variables.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful: `success` if it was, `error` if not.
</ResponseField>

<ResponseField name="response" type="object">
  The key and value of all environment variables you defined.
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
    "status": "success",
    "response": {
      "TEST": "myTest"
    }
  }
  ```
</ResponseExample>

## Common errors

| Code | HTTP | Meaning |
| - | - | - |
| `STATIC_APP_ENV_NOT_SUPPORTED` | 400 | The application is static; static apps don't support environment variables. |
| `INVALID_ENV_CONTENT` | 400 | `envs` is missing, not an object, or an array. |
| `TOO_MANY_ENV_VARS` | 400 | The merged set would exceed 256 environment variables. |
| `ENV_NAME_TOO_LONG` | 400 | A variable key exceeds 1024 characters. |
| `ENV_CONTENT_TOO_LONG` | 400 | A variable value exceeds 4096 characters. |

## Related

* CLI: [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set)
* SDKs: [`api.apps.envs.set()`](/en/sdks/js/environment_variables) (JavaScript), [`client.apps.envs.set()`](/en/sdks/py/environment_variables) (Python), [`c.Apps.Envs.Set()`](/en/sdks/go/environment_variables) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.