Container Environment Variables

Download Page (.md)

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.

`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

{
  "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

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.

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

Response

{
  "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

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

{
  "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

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

{
  "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

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