POST
Update a machine pool

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
pool_id
string
required

Body

application/json
​
name
string

Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not.

Required string length: 1 - 64
​
description
string

Optional description of the pool.

​
default_machine_cpu
integer<int32> | null

Default CPU count for new machines in the pool.

Required range: 1 <= x <= 2147483647
​
default_machine_memory_mb
integer<int32> | null

Default memory in MB for new machines in the pool.

Required range: 1 <= x <= 2147483647
​
default_machine_env
object

Default environment for pool machines. A machine's environment, including resolved secret_env values, is applied to the provider machine at provisioning, so the provider_options startup_script and the daemon run with it, and is resolved again for each process at launch.

​
default_machine_secret_env
object

Default secret environment for pool machines, mapping env names to generic secret references. References are resolved to secret values wherever the machine environment is applied.

​
default_machine_provider_options
object

Provider-specific options applied to new machines in the pool.

​
default_cwd
string

Default working directory for processes on machines created from the pool after this change.

​
provider_config
object

Provider-specific settings for the pool.

​
provider_auth_secret_id
string

Secret ID (sec_...).

Pattern: ^sec_[a-z2-7]{26}$
​
runtime_protection_enabled
boolean

Whether BMA should delete a pool machine when its provider remains running after its daemon becomes inactive.

​
max_total_machines
integer<int32>

Deprecated, not enforced: how many machines a pool has no longer blocks new machines. Organization and project quotas over in-use machines (org resource limits max_in_use_pool_machines_per_project and max_in_use_pool_machines_per_org) govern capacity.

Required range: 0 <= x <= 2147483647
​
max_total_cpu
integer<int32> | null

Deprecated, not enforced: organization and project in-use machine CPU quotas govern capacity.

Required range: 0 <= x <= 2147483647
​
max_total_memory_mb
integer<int32> | null

Deprecated, not enforced: organization and project in-use machine memory quotas govern capacity.

Required range: 0 <= x <= 2147483647
​
min_machine_cpu
integer<int32> | null

Smallest CPU count a single machine in the pool can use.

Required range: 0 <= x <= 2147483647
​
min_machine_memory_mb
integer<int32> | null

Smallest memory in MB a single machine in the pool can use.

Required range: 0 <= x <= 2147483647
​
max_machine_cpu
integer<int32> | null

Largest CPU count a single machine in the pool can use.

Required range: 1 <= x <= 2147483647
​
max_machine_memory_mb
integer<int32> | null

Largest memory in MB a single machine in the pool can use.

Required range: 1 <= x <= 2147483647
​
delete_after_idle_minutes
integer<int32> | null

Idle minutes before deleting a machine from this pool. Null clears the pool default; omitted leaves it unchanged.

Required range: 5 <= x <= 2147483647
​
pause_after_idle_minutes
integer<int32> | null

Idle minutes before pausing a machine from this pool. Null clears it; omitted leaves it unchanged. Exclusive with delete_after_idle_minutes.

Required range: 5 <= x <= 2147483647
​
archive_after_paused_days
integer<int32> | null

Days a machine stays paused before it is archived. Null clears it; omitted leaves it unchanged. Requires pause_after_idle_minutes.

Required range: 1 <= x <= 3650
​
delete_after_paused_days
integer<int32> | null

Days a machine stays paused before it is deleted, counted from when it paused. Null clears it; omitted leaves it unchanged. Requires pause_after_idle_minutes; cannot be combined with archive_after_paused_days.

Required range: 1 <= x <= 3650
​
metadata
object

User-supplied metadata stored on a machine, provided directly or copied from the machine pool that provisions it. A restriction of Metadata that leaves room for one reserved pair - BMA sets observed_platform on the machine to the platform reported by its daemon, so the key is reserved and at most 15 user pairs are accepted.

Response

Success.

​
type
string
required
Allowed value: "machine_pool"
​
id
string
required

Machine pool ID (mpo_...).

Pattern: ^mpo_[a-z2-7]{26}$
​
org_id
string
required
Pattern: ^org_[a-z2-7]{26}$
​
name
string
required

Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not.

Required string length: 1 - 64
​
management_kind
enum<string>
required

Lifecycle owner. Tenant-managed resources can be changed through tenant APIs. Cluster-managed resources are installed and lifecycle-managed by the control plane; individual APIs may explicitly expose tenant-editable settings.

Available options:
tenant,
cluster
​
description
string
required
​
provider
string
required
​
default_machine_cpu
integer<int32> | null
required
Required range: 1 <= x <= 2147483647
​
default_machine_memory_mb
integer<int32> | null
required
Required range: 1 <= x <= 2147483647
​
default_machine_env
object
required

Default environment for pool machines. A machine's environment, including resolved secret_env values, is applied to the provider machine at provisioning, so the provider_options startup_script and the daemon run with it, and is resolved again for each process at launch.

​
default_machine_secret_env
object
required

Default secret environment for pool machines, mapping env names to generic secret references. References are resolved to secret values wherever the machine environment is applied.

​
default_machine_provider_options
object
required
​
default_cwd
string
required
​
provider_config
object
required
​
runtime_protection_enabled
boolean
required

Whether BMA deletes this pool's machines when the provider remains running after the daemon becomes inactive.

​
max_total_machines
integer<int32>
required

Deprecated, not enforced: how many machines a pool has no longer blocks new machines. Organization and project quotas over in-use machines (org resource limits max_in_use_pool_machines_per_project and max_in_use_pool_machines_per_org) govern capacity.

Required range: 0 <= x <= 2147483647
​
max_total_cpu
integer<int32> | null
required

Deprecated, not enforced: organization and project in-use machine CPU quotas govern capacity.

Required range: 0 <= x <= 2147483647
​
max_total_memory_mb
integer<int32> | null
required

Deprecated, not enforced: organization and project in-use machine memory quotas govern capacity.

Required range: 0 <= x <= 2147483647
​
min_machine_cpu
integer<int32> | null
required
Required range: 0 <= x <= 2147483647
​
min_machine_memory_mb
integer<int32> | null
required
Required range: 0 <= x <= 2147483647
​
max_machine_cpu
integer<int32> | null
required
Required range: 1 <= x <= 2147483647
​
max_machine_memory_mb
integer<int32> | null
required
Required range: 1 <= x <= 2147483647
​
delete_after_idle_minutes
integer<int32> | null
required

Idle minutes before deleting a machine from this pool, or null when the pool default is unset.

Required range: 5 <= x <= 2147483647
​
pause_after_idle_minutes
integer<int32> | null
required

Idle minutes before pausing a machine from this pool, or null when the pool does not pause idle machines.

Required range: 5 <= x <= 2147483647
​
archive_after_paused_days
integer<int32> | null
required

Days a machine stays paused before it is archived, or null when the pool does not archive.

Required range: 1 <= x <= 3650
​
delete_after_paused_days
integer<int32> | null
required

Days a machine stays paused before it is deleted, counted from when it paused, or null when the pool keeps paused machines.

Required range: 1 <= x <= 3650
​
metadata
object
required

Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters.

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
provider_auth_secret_id
string

Secret ID (sec_...).

Pattern: ^sec_[a-z2-7]{26}$
​
usage
object

Current quota-consuming usage. Populated when the machine pool is returned by the list or get endpoint.