API reference

Machines

GET /v1/agents/machines

Lists the computers on your account.

Request

bash

curl -s "$SAI_API_URL/v1/agents/machines" \
  -H "Authorization: Bearer $SAI_API_KEY"

Response

json

{
  "machines": [
    {
      "machineId": "m_9c1e",
      "name": "Sai cloud computer",
      "updatedAt": 1789990000000,
      "status": "hibernated",
      "canWake": true,
      "kind": "cloud",
      "online": true
    },
    {
      "machineId": "m_7f2a",
      "name": "Work Desktop",
      "updatedAt": 1790000000000,
      "status": "active",
      "canWake": false,
      "kind": "own",
      "online": true
    }
  ]
}

Field	Notes
`machineId`	Pass as `machineId` on other calls.
`name`	The name shown in the Sai app. Absent when the computer has none.
`updatedAt`	Unix time in milliseconds of the last status update.
`status`	The raw machine status string. Absent when unknown. Prefer `online`.
`canWake`	Whether `POST /wake` applies to this computer.
`kind`	`cloud` (hosted by Simular) or `own` (your desktop app).
`online`	`true` when the computer is `active`, `hibernated` (a message wakes it), or its agent reports online.

Rows are sorted by name.

Free accounts

A free account whose computer is not claimed right now sees one synthetic row:

json

{
  "machines": [
    {
      "machineId": "free-3fA9kQ2xYz",
      "name": "Sai cloud computer (free)",
      "updatedAt": 0,
      "canWake": false,
      "kind": "cloud",
      "online": false
    }
  ]
}

online: false means the first message will claim and start the computer, which takes about two minutes. While it is claimed, the row is a normal one with the same machineId.

Note

kind, online and the free-account row are available from October 1.

Create a computer

POST /v1/agents/machines

Creates a Windows cloud computer for a paid account. It needs a signed-in session: the portal's Create a cloud computer button in the Playground calls it. An API key cannot create a computer, because a computer costs money and is created with the account owner's own checks (plan, payment method, quota, one creation at a time).

Body (optional):

json

{ "name": "Work PC" }

Response 202:

json

{
  "taskId": "3f1c…",
  "message": "Creating your computer. It appears in GET /v1/agents/machines within a few minutes."
}

Poll GET /v1/agents/machines until the new computer is listed with online: true, usually within a few minutes.

Status	`error`	When
`403`	`session_required`	Called with an API key. The body carries `createUrl`, the portal page to send the user to.
`409`	`free_plan_computer`	Free plan. Its computer is the pooled one, started by the first task.
`429`	`busy`, or a rate-limit message	A creation is already in progress, or more than 3 in an hour.
`403`	`not_billable`	The account cannot pay for a computer right now.

Live screen

POST /v1/agents/machines/:machineId/live

Returns a view-only stream of one of your computers' screens: what the live view shows. The stream uses Apache Guacamole; connect websocketUrl with its JavaScript client (Guacamole.WebSocketTunnel + Guacamole.Client) and draw nothing back.

bash

curl -s -X POST "$SAI_API_URL/v1/agents/machines/m_9c1e/live" \
  -H "Authorization: Bearer $SAI_API_KEY"

Response 200:

json

{
  "machineId": "m_9c1e",
  "websocketUrl": "wss://proxy.vm.api.simular.cloud/guacamole/websocket-tunnel?token=…",
  "width": 1920,
  "height": 1080
}

websocketUrl carries a session token for that computer. Hand it only to your viewer, and get a new one when the stream ends. Split the query string off the URL and pass it to client.connect(), because Guacamole appends it itself.

Status	`error`	When
`404`		The computer is not yours. A free account may use its own `free-…` computer.
`409`	`machine_not_running`	The computer is asleep or starting. Retry while a task runs.
`502`	`live_unavailable`	The stream could not be set up. Retry later.
`429`		More than 120 requests in an hour.