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

# Variáveis de Ambiente

> Consultar, adicionar, substituir e remover variáveis de ambiente de uma aplicação

As variáveis de ambiente são configuradas por aplicação nas rotas REST `/v1/apps/:id/envs` da API v1. As operações de escrita salvam a configuração; elas **não reiniciam** a aplicação automaticamente. Para aplicar valores atualizados, chame `sonder.apps.restart(appId)` ou a rota `POST /v1/apps/:id/restart`.

> [!WARNING]
>
> `GET /v1/apps/:id/envs` e as respostas de escrita retornam valores sem mascaramento, inclusive segredos. Proteja o token de API e evite registrar ou exibir essas respostas em logs, interfaces públicas ou ferramentas de observabilidade.

## Operações

| Método HTTP | Rota | Comportamento |
| - | - | - |
| `GET` | `/v1/apps/:id/envs` | Lista as variáveis atuais e seus valores. |
| `POST` | `/v1/apps/:id/envs` | Mescla variáveis: cria novas chaves e atualiza as informadas. |
| `PATCH` | `/v1/apps/:id/envs` | Mescla variáveis, com o mesmo comportamento do `POST`. |
| `PUT` | `/v1/apps/:id/envs` | Substitui o conjunto completo; chaves omitidas são removidas. |
| `DELETE` | `/v1/apps/:id/envs` | Remove as chaves indicadas no array `keys`. |

As requisições exigem `Authorization: Bearer <token>` e um `appId` em formato UUID v4. Para detalhes por operação, consulte [GET](https://docs.sondercloud.app/api-reference/endpoint/apps/envs-get.md), [POST](https://docs.sondercloud.app/api-reference/endpoint/apps/envs-post.md), [PATCH](https://docs.sondercloud.app/api-reference/endpoint/apps/envs-patch.md), [PUT](https://docs.sondercloud.app/api-reference/endpoint/apps/envs-put.md) e [DELETE](https://docs.sondercloud.app/api-reference/endpoint/apps/envs-delete.md).

## Consultar

```bash theme={null}
curl 'https://api.sondercloud.app/v1/apps/APP_ID/envs' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json theme={null}
{
  "success": true,
  "appId": "APP_ID",
  "envs": {
    "NODE_ENV": "production",
    "API_KEY": "valor-secreto"
  }
}
```

## Adicionar ou atualizar

Envie apenas as chaves que deseja criar ou alterar. As demais permanecem salvas.

```bash theme={null}
curl -X PATCH 'https://api.sondercloud.app/v1/apps/APP_ID/envs' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"envs":{"NODE_ENV":"production","API_KEY":"substitua-pelo-segredo"}}'
```

## Substituir o conjunto completo

O corpo representa o conjunto desejado inteiro. Chaves que existiam, mas foram omitidas, são removidas.

```bash theme={null}
curl -X PUT 'https://api.sondercloud.app/v1/apps/APP_ID/envs' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"envs":{"NODE_ENV":"production"}}'
```

## Remover chaves

O corpo deve conter um array `keys` não vazio.

```bash theme={null}
curl -X DELETE 'https://api.sondercloud.app/v1/apps/APP_ID/envs' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"keys":["API_KEY"]}'
```

## Formato e limites

* São permitidas até **256 variáveis** por aplicação.
* O nome deve ter até 128 caracteres e seguir o padrão `[A-Za-z_][A-Za-z0-9_]*` (por exemplo, `API_KEY` ou `_INTERNAL`).
* O valor deve ser uma string de até 4096 caracteres. Para representar um valor vazio, envie `""`; números e booleanos devem ser convertidos para strings.
* Não é possível alterar variáveis enquanto o app está em `BUILDING`; a API responde com `400 Bad Request`.
* As respostas de escrita incluem `success: true`, `response` com o mapa atualizado de variáveis e a mensagem `Environment variables saved. Restart the app to apply changes.`. Falhas retornam `success: false` e `message`, com o status HTTP correspondente. Trate `response` como dado secreto.

## Aplicar as alterações

Depois de salvar as variáveis, reinicie a aplicação:

```ts theme={null}
await sonder.apps.restart(appId);
```

O start e o restart usam o conjunto de variáveis salvo. Para uma aplicação parada, `sonder.apps.start(appId)` também inicia o container com os valores atuais.


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