POST
Create a persistent machine for an agent

Authorizations

Authorization
string
header
required

An opaque BMA personal or organization bearer token.

Headers

Idempotency-Key
string

Idempotency key for replay-safe mutating requests.

Required string length: 1 - 255

Path Parameters

orgID
string
required

Organization ID (org_...).

Pattern: ^org_[a-z2-7]{26}$
projectID
string
required

Project ID (proj_...).

Pattern: ^proj_[a-z2-7]{26}$
agentID
string
required

Agent ID (agt_...).

Pattern: ^agt_[a-z2-7]{26}$

Body

application/json
template
string
required

The sold machine-class template (for example base-2c4g, base-2c8g or base-8c32g). It must be allowed by the machine pool's provider configuration.

Required string length: 1 - 200
machine_pool_id
string

Machine pool ID (mpo_...).

Pattern: ^mpo_[a-z2-7]{26}$
display_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

Response

Existing machine returned.

id
string
required

Machine ID (mch_...).

Pattern: ^mch_[a-z2-7]{26}$
kind
enum<string>
required

Persistent machines are kept for a person and never deleted for being idle; ephemeral machines serve turns and are deleted after their idle window.

Available options:
persistent,
ephemeral
display_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
machine_pool_id
string | null
required

Machine pool ID (mpo_...).

Pattern: ^mpo_[a-z2-7]{26}$
machine_pool_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
lifecycle_state
enum<string>
required
Available options:
provisioning,
provision_failed,
active,
deleting,
delete_failed,
deleted
connection_state
enum<string>
required
Available options:
online,
asleep,
offline
cpu
integer<int32> | null
required

The machine shape BMA reports, or null before the provider resolves it.

Required range: x >= 1
memory_mb
integer<int32> | null
required

The machine shape BMA reports, or null before the provider resolves it.

Required range: x >= 1
created_at
string<date-time>
required