Developer API

A machine is the stable execution target used by Tasks and Workflows. It can be a managed Coasty cloud VM or an external machine whose driver you operate. For a managed VM, provision one, poll until it is running, then either hand it to a task run (the agent drives it to done) or drive it yourself with the action endpoints. Machines are optional for primitives: /predict, /sessions, and /ground run against your screen. You only need a Coasty machine or an enrolled external machine when you want the hosted Task/Workflow runtime to own the loop.

Provision with POST /v1/machines. Only display_name is required; everything else has a sensible default. The body rejects unknown fields, so a typo returns 422 VALIDATION_ERROR rather than being silently ignored.

curl -X POST https://coasty.ai/v1/machines \
  -H "X-API-Key: $COASTY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"display_name": "agent-box", "os_type": "linux", "desktop_enabled": true, "ttl_minutes": 120}'

Provisioning is asynchronous. The response returns immediately with the machine in creating status and a connection object whose secrets are redacted. The VM is not drivable yet — poll GET /v1/machines/{id} until status is running before you send actions or start a run.

{
  "machine": {
    "id": "9f2c1e7a-3b6d-4c81-9a0e-2d5f8b1c4e90",
    "display_name": "agent-box",
    "kind": "managed",
    "capabilities": [
      "screenshot",
      "mouse",
      "keyboard",
      "scroll",
      "terminal",
      "files",
      "browser"
    ],
    "protocol_version": null,
    "connection_status": null,
    "last_seen_at": null,
    "status": "creating",
    "os_type": "linux",
    "desktop_enabled": true,
    "cpu_cores": 2,
    "memory_gb": 4,
    "storage_gb": 16,
    "public_ip": null,
    "auto_destroy_at": "2026-06-17T14:30:00Z",
    "ttl_minutes": 120,
    "is_test": false,
    "created_at": "2026-06-17T12:30:00Z"
  },
  "connection": {
    "public_ip": null,
    "ssh_port": 22,
    "ssh_username": "ubuntu",
    "has_ssh_key": true,
    "has_vnc_password": true
  },
  "request_id": "req_2f9c1a7b3e4d"
}

The machine object — returned by provision, list, and get:

List your machines with GET /v1/machines (newest first, ?limit= 1–200, default 50) — it returns { data, has_more, request_id }. Fetch one with GET /v1/machines/{id}. Both read straight from the registry, so they keep working even when provisioning is busy.