Developer API

The power-state lifecycle applies to kind: managed. On an external machine, owner-authenticated start, stop, and restart are logical dispatch gates: they increment the fencing generation and cancel outstanding commands, but never power the caller-owned host on or off. External machines use connection_status, cannot be snapshotted, and are not billed for runtime. A managed machine moves through a small set of statuses. status is the field you poll: drive the machine only while it is running. The runtime rate that applies in each status is shown below; exact per-hour USD numbers are in the Pricing section.

Start, stop, restart are POST /v1/machines/{id}/start (and /stop, /restart). Managed-machine power changes are asynchronous: the call returns a transitional status (starting / stopping) and you poll until it settles. External logical gates commit immediately and return running or stopped. They are state-checked — starting a machine that is already running, or stopping one that is not running, returns 409 INVALID_STATE with current_state and allowed_from in the body, so you can react without guessing. start is allowed from stopped or error; stop only from running.

Terminate with DELETE /v1/machines/{id}. For a managed machine this permanently tears down the VM and its disk. For an external machine it revokes only the Coasty registration, device token, and outstanding command leases; the caller-owned host and storage remain untouched. A later GET returns 404 MACHINE_NOT_FOUND. Delete is idempotent, so an exact retry after an already-completed deletion is safe.

curl -X POST https://coasty.ai/v1/machines/$MACHINE_ID/stop   -H "X-API-Key: $COASTY_API_KEY"
curl -X DELETE https://coasty.ai/v1/machines/$MACHINE_ID       -H "X-API-Key: $COASTY_API_KEY"

Auto-destroy / auto-revoke (TTL). A managed machine left running bills until you destroy it, so set ttl_minutes as a safety net. A background sweep (every ~60s) terminates managed infrastructure once its auto_destroy_at passes. On an external machine, expiry revokes only its Coasty registration/token/leases and never powers off or deletes the host or its storage. Adjust it any time with PATCH /v1/machines/{id}: ttl_minutes is measured from now (so it doubles as a lease extension), accepts 5–10080 (5 min to 7 days), and 0 clears auto-destroy entirely. Anything else is 400 INVALID_TTL. Provisioning without a TTL works but adds a Warning response header nudging you to set one.

curl -X PATCH https://coasty.ai/v1/machines/$MACHINE_ID \
  -H "X-API-Key: $COASTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_minutes": 30}'

Runtime billing. Machines bill the developer API wallet (separate from any subscription credits) by the minute, rounded down to whole credits in your favour. Published defaults are running Linux $0.05/hr, running Windows $0.09/hr, and a stopped or suspended machine the keep-alive rate of $0.01/hr; creating, error, and terminated are free. Transitional states (starting/stopping/restarting) bill at the running rate. The per-call control endpoints (actions, terminal, files, browser, screenshot, connection) are never billed. Managed-machine metering consists of runtime plus the separate one-time snapshot charge.