Computers API

Persistent Linux machines: the root disk and network address survive stop/start, and only DELETE reclaims the disk.

REST API endpoints for Computers. 11 operations.

List your Computers

plaintext

GET /v1/computers

Auth: Bearer API key

Responses

Status	Description
`200`	Your Computers, newest first
`401`	Missing or invalid API key

operationId: computerList

Create a Computer

plaintext

POST /v1/computers

Boots a persistent Linux machine and returns once it is provisioning. The root disk survives stop/start and is only reclaimed by DELETE. Billed per start, per vCPU-hour and GB-hour while running, and per GB-month of disk for as long as the Computer exists.

Auth: Bearer API key

Request body

application/json (required) — schema ComputerCreateRequest.

Responses

Status	Description
`201`	Computer created (initially CREATING)
`400`	Invalid name or resource shape
`401`	Missing or invalid API key
`402`	Credit exhausted or plan limit reached
`409`	A Computer with that name already exists
`503`	No host has capacity for the requested resources

operationId: computerCreate

Delete a Computer

plaintext

DELETE /v1/computers/{id}

The only operation that reclaims the root disk. Irreversible — stop the Computer instead if you want the files back later.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`204`	Computer and its disk deleted
`404`	Not found

operationId: computerDelete

Get one Computer

plaintext

GET /v1/computers/{id}

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`200`	The Computer
`404`	Not found

operationId: computerGet

Run a command inside a Computer

plaintext

POST /v1/computers/{id}/exec

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Request body

application/json (required) — schema ComputerExecRequest.

Responses

Status	Description
`200`	Command finished
`404`	Not found
`409`	The Computer is not RUNNING

operationId: computerExec

Read one file out of a Computer

plaintext

GET /v1/computers/{id}/files

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id
`path`	query	`string`	Yes	Absolute path inside the guest

Responses

Status	Description
`200`	File contents, base64-encoded
`400`	Missing `path` query parameter
`404`	Not found
`409`	The Computer is not RUNNING

operationId: computerReadFile

Write files into a Computer

plaintext

PUT /v1/computers/{id}/files

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Request body

application/json (required) — schema ComputerWriteFilesRequest.

Responses

Status	Description
`204`	Files written
`400`	No files, or more than 64
`404`	Not found
`409`	The Computer is not RUNNING

operationId: computerWriteFiles

Replace a Computer's authorised ssh keys

plaintext

PUT /v1/computers/{id}/ssh-keys

Sends the whole list every time, so removing a key is the same operation as adding one. On a RUNNING machine the change applies immediately — a revoked key stops working now, not at the next restart. On a stopped machine it is stored and delivered when it next boots.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Request body

application/json (required) — schema ComputerSshKeysRequest.

Responses

Status	Description
`200`	The Computer, with the new key list
`400`	Not an OpenSSH public key, or more than 32
`404`	Not found
`502`	The keys could not be delivered to the running machine

operationId: computerSetSshKeys

Start a stopped Computer

plaintext

POST /v1/computers/{id}/start

Boots the same disk on the same host and reclaims the same address.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`200`	The Computer, now RUNNING
`404`	Not found
`503`	The Computer's host is unavailable

operationId: computerStart

Stop a Computer

plaintext

POST /v1/computers/{id}/stop

Halts the machine. The root disk and the network address are kept, so a later start comes back to the same files at the same address. Runtime billing stops; disk billing continues at the parked rate.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Computer id

Responses

Status	Description
`200`	The Computer, now STOPPED
`404`	Not found

operationId: computerStop

Get or create a Computer by name

plaintext

PUT /v1/computers/by-name/{name}

Idempotent: the first call creates the machine (201), every identical repeat returns the existing one (200). Resource changes on a repeat are ignored — the existing machine wins. Use this instead of create when an agent may retry.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	Lowercase DNS label, max 63 characters

Request body

application/json (required) — schema ComputerCreateRequest.

Responses

Status	Description
`200`	The existing Computer
`201`	Computer created
`400`	Invalid name or resource shape
`503`	No host has capacity for the requested resources

operationId: computerGetOrCreateByName