Skip to main content
POST
Create Machine

Authorizations

Authorization
string
header
required

API key from Settings > Developer > REST API

Headers

Idempotency-Key
string | null

Repeat a request safely: the same key and body return the original result.

Maximum string length: 120

Body

application/json
preset
string
default:render

render (default), render-lite or compute.

name
string | null

A name you can use in place of the id. Default: <preset>-<random>.

Required string length: 1 - 63
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$
gpu
string | null

Overrides the preset's GPU.

Required string length: 1 - 32
image
string | null

Overrides the preset's image.

Required string length: 1 - 128
idle_timeout
integer
default:900

Seconds without a command or file transfer before the machine pauses itself (default 900).

Required range: 30 <= x <= 604800
budget_usd
number | null

Stop the machine once it has spent this much.

Required range: 0 < x <= 10000
from_snapshot
string | null

Start from a snapshot (snp_…) instead of a fresh disk.

Maximum string length: 80

Response

Successful Response

id
string
required

The machine id (mch_…). Every route also takes the machine's name.

name
string
required

The name.

status
enum<string>
required

The state (see the enum).

Available options:
starting,
ready,
paused,
released,
failed
gpu
string
required

The GPU model, e.g. RTX-PRO-6000.

image
string
required

The machine image (GET /v1/machines/images).

preset
string | null
required

The preset it matches (render, render-lite, compute), if any.

created_at
string | null
required

When it was created (ISO 8601).

ready_at
string | null
required

When it became ready.

idle_timeout
integer | null
required

Seconds without a command or file transfer before it pauses.

cost
MachineCost · object
required

What it has cost so far.

next
string
required

What to do next, for agents.

error
MachineFailure · object | null

Why it failed, when it failed.