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

# Environment Variables API

> List environments and manage environment variables programmatically

These endpoints let you browse [environments](/docs/environments.md) and manage their environment variables programmatically. Use them to bulk-import config from another secrets manager, keep credentials in sync with CI, or build dashboards on top of BugRadar.

All requests require an API key in the `X-API-Key` header. See [API Reference](/docs/api-reference.md) for authentication and the standard `401` / `403` / `429` / `500` error shapes shared by every endpoint on this page.

> [!WARNING]
>
> **Secret values are write-only through the API.** When `is_secret=true`, the value is stored encrypted in vault and is never returned by any read endpoint — list and get responses always render secret values as `"***"`. There is no API path to retrieve a decrypted secret.

> [!NOTE]
>
> During test runs, secrets are never sent to the AI agent. The agent works with the `${env:KEY}` placeholder and the real value is injected only at the moment keystrokes are sent to your app, so run history records the placeholder, not the value. See [Secret Variables](/docs/environments.md#secret-variables).

> [!NOTE]
>
> Environments themselves (create / rename / delete) are managed from the [dashboard](https://usebugradar.com/settings?tab=environments). The API surface here covers env vars and read access to the environments that contain them.

***

## List Environments

Returns every environment in your organization with its env vars nested. Plaintext values come back in full; secret values are masked as `"***"`.

> [!NOTE]
>
> **GET** `/api/v1/environments` — Returns `200 OK`

### Example Request

```bash theme={null}
curl -X GET https://backend.usebugradar.com/api/v1/environments \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response Fields

**environments** `array`

List of environments.

**Environment object**

**id** `string`

Unique identifier (UUID).

**name** `string`

Environment name (e.g. "Staging", "Production").

**env\_vars** `array`

Environment variables, alphabetically by `key`.

**Env var object**

**id** `string`

Unique identifier (UUID).

**environment\_id** `string`

UUID of the parent environment.

**key** `string`

Variable name (referenced from flows as `${env:KEY}`).

**value** `string | null`

Plaintext value, or `"***"` placeholder when `is_secret=true`. **Never** the decrypted secret.

**is\_secret** `boolean`

Whether the value is stored encrypted in vault.

**description** `string | null`

Optional human-readable note.

**created\_at** `string`

ISO 8601 timestamp.

**updated\_at** `string`

ISO 8601 timestamp.

**count** `integer`

Total number of environments returned.

#### Example Response

```json theme={null}
{
  "environments": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440099",
      "name": "Staging",
      "env_vars": [
        {
          "id": "880e8400-e29b-41d4-a716-446655440010",
          "environment_id": "770e8400-e29b-41d4-a716-446655440099",
          "key": "API_TOKEN",
          "value": "***",
          "is_secret": true,
          "description": null,
          "created_at": "2026-01-15T10:30:00Z",
          "updated_at": "2026-01-15T10:30:00Z"
        },
        {
          "id": "880e8400-e29b-41d4-a716-446655440011",
          "environment_id": "770e8400-e29b-41d4-a716-446655440099",
          "key": "API_URL",
          "value": "https://staging.api.example.com",
          "is_secret": false,
          "description": "Staging API base URL",
          "created_at": "2026-01-15T10:31:00Z",
          "updated_at": "2026-01-15T10:31:00Z"
        }
      ]
    }
  ],
  "count": 1
}
```

***

## Create Env Var

> [!NOTE]
>
> **POST** `/api/v1/env-vars` — Returns `201 Created`. Returns `409 Conflict` if an env var with the same `key` already exists on this environment.

### Request Body

**environment\_id** `string` *required*

UUID of the environment this variable belongs to.

**key** `string` *required*

Variable name (1–255 characters). Referenced from flows and curl hooks as `${env:KEY}`.

**value** `string` *required*

Variable value — must be a non-empty string. Empty values are rejected with `422` because they're indistinguishable from "unset" at consumption time. For secrets, this is written to vault and never returned by any read endpoint.

**description** `string`

Optional human-readable note.

**is\_secret** `boolean`

Defaults to `false`. When `true`, the value is stored encrypted in vault and is never readable back through the API.

### Example Request (plaintext)

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/env-vars \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "770e8400-e29b-41d4-a716-446655440099",
    "key": "API_URL",
    "value": "https://staging.api.example.com",
    "description": "Staging API base URL"
  }'
```

### Example Request (secret)

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/env-vars \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "770e8400-e29b-41d4-a716-446655440099",
    "key": "API_TOKEN",
    "value": "abc123...super-secret",
    "is_secret": true
  }'
```

#### Example Response

```json theme={null}
{
  "id": "880e8400-e29b-41d4-a716-446655440010",
  "environment_id": "770e8400-e29b-41d4-a716-446655440099",
  "key": "API_TOKEN",
  "value": "***",
  "is_secret": true,
  "description": null,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}
```

***

## Get Env Var

> [!NOTE]
>
> **GET** `/api/v1/env-vars/{env_var_id}` — Returns `200 OK` with the same shape as items in [List Environments](#list-environments)' `env_vars`, or `404` if the var does not exist. Secret values are returned as `"***"`.

**env\_var\_id** `string` *required*

UUID of the env var.

```bash theme={null}
curl -X GET https://backend.usebugradar.com/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Update Env Var

Update an env var. Only provided fields change; omitted fields are unchanged.

> [!NOTE]
>
> **PATCH** `/api/v1/env-vars/{env_var_id}` — Returns `200 OK`. `400` if no recognized fields are provided. `404` if the var does not exist. `409` if renaming `key` collides with another env var in the same environment. `422` for invalid transitions (see below).

> [!TIP]
>
> **No-op PATCHes don't bump `updated_at`.** If the body resolves to no actual state change — e.g. `{"is_secret": true}` on a row that's already a secret — the endpoint returns the unchanged row without writing to the DB. Don't rely on PATCH to act as a heartbeat.

**env\_var\_id** `string` *required*

UUID of the env var.

**key** `string`

New variable name (1–255 characters). **Note:** any flows or curl hooks that reference the old name as `${env:OLD_KEY}` must be updated in lockstep — there is no automatic rewrite. Collisions with another env var in the same environment return `409`.

**value** `string`

New value. Omit to keep the existing value unchanged. Required when changing `is_secret` in either direction (the API never re-uses the existing value across a secret/plaintext transition). `null` is treated as "no change", not "clear" — there is no way to clear a value without deleting the row.

**description** `string | null`

New description. Pass `""` or `null` to explicitly clear (this is the only field where `null` clears rather than meaning "no change").

**is\_secret** `boolean`

Move the var between plaintext and vault-encrypted storage. Switching the flag in either direction requires `value`.

### Secret transition rules

| Existing state | Request | Result |
| - | - | - |
| Plaintext | `value: "new"` | Plaintext value rewritten in place. |
| Plaintext | `is_secret: true`, no `value` | **422** — promoting to secret requires a `value`. |
| Plaintext | `is_secret: true`, `value: "secret-x"` | New vault row written; row repointed to it. |
| Secret | `value: "rotated"` | New vault row written, old one cleaned up after the row is repointed. |
| Secret | `is_secret: false`, no `value` | **422** — demoting to plaintext requires a `value`. |
| Secret | `is_secret: false`, `value: "plain"` | Old vault row cleaned up, plaintext value written. |

### Example Request

```bash theme={null}
# Rotate an existing secret
curl -X PATCH https://backend.usebugradar.com/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "new-rotated-secret-value" }'

# Promote a plaintext var to a secret
curl -X PATCH https://backend.usebugradar.com/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_secret": true, "value": "secret-only-known-at-rotation" }'
```

***

## Delete Env Var

Deletes the env var. If the var is a secret, its vault entry is cleaned up too.

> [!NOTE]
>
> **DELETE** `/api/v1/env-vars/{env_var_id}` — Returns `204 No Content`, or `404` if the var does not exist.

**env\_var\_id** `string` *required*

UUID of the env var.

```bash theme={null}
curl -X DELETE https://backend.usebugradar.com/api/v1/env-vars/ENV_VAR_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

> [!WARNING]
>
> Deleting a variable will cause any flows or hooks that reference `${env:VARIABLE_NAME}` to fail. Update or remove references before deleting.


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