# Container Environment Variables

**Page:** api/container-env

[Download Raw Markdown](./api/container-env.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Container Environment Variables API lets you list, set, bulk-update, and delete environment variables on a container. Use these endpoints to manage runtime configuration without rebuilding images. All write operations take effect on the next container restart.


Keys prefixed with `HOODY_` are reserved for internal use and cannot be set or deleted by users. All other keys must match the pattern `^[a-zA-Z_][a-zA-Z0-9_]*$` and must not start with the reserved prefix.


## `GET /api/v1/containers/{id}/env`

Get all environment variables for a container.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Container ID |

### Response



```json
{
  "statusCode": 200,
  "message": "Environment variables retrieved",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app_user:s3cret@db.internal:5432/production",
      "NODE_ENV": "production",
      "LOG_LEVEL": "info",
      "REDIS_HOST": "cache.internal"
    }
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `RESOURCE_ACCESS_DENIED` | Resource access denied | You do not have permission to access this specific resource | Ensure you own this resource or have been granted access by the owner |
| `CONTAINER_NOT_FOUND` | Container not found | The requested container does not exist or you do not have permission to access it. | Verify the container ID is correct and that you have access to the project it belongs to. |



### SDK usage

```ts
const { data } = await client.api.env.list({
  id: "cnt_abc123def456"
});
```

## `PATCH /api/v1/containers/{id}/env`

Merge environment variables into the container. Existing keys are updated, new keys are added. Keys not present in the body are left unchanged (merge semantics). Changes take effect upon the next container restart.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Container ID |

### Request body

The body is a JSON object of environment variable key-value pairs. Keys must match the pattern `^[a-zA-Z_][a-zA-Z0-9_]*$` and must not start with the reserved `HOODY_` prefix. Each value is a string with a maximum length of 65,536 characters. The object must contain between 1 and 200 properties.

```json
{
  "DATABASE_URL": "postgres://app_user:s3cret@db.internal:5432/production",
  "LOG_LEVEL": "info",
  "REDIS_HOST": "cache.internal"
}
```

### Response



```json
{
  "statusCode": 200,
  "message": "Environment variables updated",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app_user:s3cret@db.internal:5432/production",
      "LOG_LEVEL": "info",
      "REDIS_HOST": "cache.internal"
    },
    "synced": true
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_ENV_KEY` | Invalid Environment Variable Key | The environment variable key is invalid. Keys must start with a letter or underscore, contain only alphanumeric characters and underscores, and must not start with the reserved HOODY_ prefix. | Use a key that matches `[a-zA-Z_][a-zA-Z0-9_]*` and does not start with HOODY_. |
| `RESERVED_ENV_PREFIX` | Reserved Environment Variable Prefix | Environment variable keys starting with HOODY_ are reserved for system use and cannot be set or deleted by users. | Use a different key name that does not start with HOODY_. |
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `RESOURCE_ACCESS_DENIED` | Resource access denied | You do not have permission to access this specific resource | Ensure you own this resource or have been granted access by the owner |
| `CONTAINER_NOT_FOUND` | Container not found | The requested container does not exist or you do not have permission to access it. | Verify the container ID is correct and that you have access to the project it belongs to. |



### SDK usage

```ts
const { data } = await client.api.env.bulkSet({
  id: "cnt_abc123def456",
  data: {
    DATABASE_URL: "postgres://app_user:s3cret@db.internal:5432/production",
    LOG_LEVEL: "info"
  }
});
```

## `PATCH /api/v1/containers/{id}/env/{key}`

Set or update a single environment variable on the container. Changes take effect upon the next container restart.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Container ID |
| `key` | path | string | Yes | Environment variable key |

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `value` | string | Yes | Value for the environment variable (max 65,536 characters) |

### Response



```json
{
  "statusCode": 200,
  "message": "Environment variable updated",
  "data": {
    "environment_vars": {
      "LOG_LEVEL": "debug"
    },
    "synced": false
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_ENV_KEY` | Invalid Environment Variable Key | The environment variable key is invalid. Keys must start with a letter or underscore, contain only alphanumeric characters and underscores, and must not start with the reserved HOODY_ prefix. | Use a key that matches `[a-zA-Z_][a-zA-Z0-9_]*` and does not start with HOODY_. |
| `RESERVED_ENV_PREFIX` | Reserved Environment Variable Prefix | Environment variable keys starting with HOODY_ are reserved for system use and cannot be set or deleted by users. | Use a different key name that does not start with HOODY_. |
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `RESOURCE_ACCESS_DENIED` | Resource access denied | You do not have permission to access this specific resource | Ensure you own this resource or have been granted access by the owner |
| `CONTAINER_NOT_FOUND` | Container not found | The requested container does not exist or you do not have permission to access it. | Verify the container ID is correct and that you have access to the project it belongs to. |



### SDK usage

```ts
const { data } = await client.api.env.set({
  id: "cnt_abc123def456",
  key: "LOG_LEVEL",
  data: { value: "debug" }
});
```

## `DELETE /api/v1/containers/{id}/env/{key}`

Remove a single environment variable from the container. Idempotent — returns 200 whether the key existed or not. Changes take effect upon the next container restart.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Container ID |
| `key` | path | string | Yes | Environment variable key |

### Response



```json
{
  "statusCode": 200,
  "message": "Environment variable deleted",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app_user:s3cret@db.internal:5432/production",
      "REDIS_HOST": "cache.internal"
    },
    "synced": true
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `RESERVED_ENV_PREFIX` | Reserved Environment Variable Prefix | Environment variable keys starting with HOODY_ are reserved for system use and cannot be set or deleted by users. | Use a different key name that does not start with HOODY_. |
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `RESOURCE_ACCESS_DENIED` | Resource access denied | You do not have permission to access this specific resource | Ensure you own this resource or have been granted access by the owner |
| `CONTAINER_NOT_FOUND` | Container not found | The requested container does not exist or you do not have permission to access it. | Verify the container ID is correct and that you have access to the project it belongs to. |



### SDK usage

```ts
const { data } = await client.api.env.delete({
  id: "cnt_abc123def456",
  key: "LOG_LEVEL"
});
```