v1

latestOpenAPI 3.1.0MIT2026-08-0481194343.8 KB

machines

Enroll a customer-operated machine

Scope: machines:write. Creates an external machine_id for normal Tasks, Workflows, and schedules without provisioning Coasty compute. Authenticate this enrollment with the OWNER API key. Idempotency-Key is required: same key + canonical body safely replays the committed enrollment; a different body conflicts. The response contains a machine-scoped device_token only in this no-store enrollment response/replay, never in list/get; never put an owner API key in the driver.

post/v1/machines/external

Headers

Idempotency-Keystring required

Required for external-machine enrollment. Reuse the same key with the identical canonical body to recover the committed 201 response without creating another machine. Reuse with a different body is rejected.

Request body

display_namestring required

protocol_version'1'

Driver protocol major version. Unsupported major versions fail before enrollment.

capabilitiesMachineCapability[] required

platform'windows' | 'macos' | 'linux' | 'other' required

screen_widthinteger nullable

screen_heightinteger nullable

screen_width and screen_height must be supplied together when either is present.

metadataobject

Non-secret labels only. Never put device credentials or screenshot data in metadata.

Response

External machine enrolled. Persist device_token immediately. It is recoverable only by replaying the exact Idempotency-Key/body within the 24-hour enrollment recovery window; list/get never return it.

device_tokenstring required

Machine-scoped bearer credential. It is returned only by the initial enrollment or an exact Idempotency-Key replay while the 24-hour recovery secret remains available; it is never present in list/get responses and must be stored in the driver's secret store.

fencing_tokeninteger required

Initial device lease generation. Send it on heartbeat and command-result calls.

request_idstring required