VM API

HTTP reference for the GUI desktop surface. Base URL https://api.getsolari.com. Every route takes Authorization: Bearer slr_live_…. For the TypeScript client over these routes, see the VM SDK reference.

Contents

Desktops

POST/desktops

Creates a GUI microVM and returns its stream + control URLs. Requires a paid plan and the desktop entitlement; otherwise 402.

Request body. All fields optional. A malformed or absent body is tolerated as {}. This route accepts no diskGb or envs; the host uses its desktop defaults.

Responses

Example request

curl -s -X POST https://api.getsolari.com/desktops \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "template": "default",
        "resolution": "1920x1080",
        "cpu": 4,
        "memMb": 8192,
        "timeoutMs": 3600000,
        "lifecycle": { "onTimeout": "pause", "autoResume": true },
        "metadata": { "project": "acme" }
      }'

Example response

{
  "sessionId": "pool-desktop-sta:vm_7c1e:org_9f2a.YWJjZGVmZ2hpamts",
  "streamUrl": "wss://api.getsolari.com/stream/pool-desktop-sta%3Avm_7c1e%3Aorg_9f2a.YWJjZGVmZ2hpamts",
  "controlUrl": "wss://api.getsolari.com/control/pool-desktop-sta%3Avm_7c1e%3Aorg_9f2a.YWJjZGVmZ2hpamts",
  "expiresAt": "2026-07-16T12:30:00.000Z",
  "recordingUrl": "https://storage.solaribrowser.com/org_9f2a/res_1a2b.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=8f2b1c0d4e6a7b9c"
}

Mounting a volume and recording the session:

curl -s -X POST https://api.getsolari.com/desktops \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "template": "default",
        "record": true,
        "volumes": [
          { "volumeId": "vol_4f3a9c1e77b24d5e8a1b0c9d2e3f4a5b", "path": "/data" }
        ]
      }'

GET/desktops/:id

Returns the routing record's status. An authorized call is activity: it re-stamps the rolling idle deadline, so polling this route keeps a session alive.

Path parameters

Responses

Example request

ENC=$(jq -rn --arg v "$SESSION_ID" '$v|@uri')

curl -s "https://api.getsolari.com/desktops/$ENC" \
  -H "Authorization: Bearer $SOLARI_API_KEY"

Example response

{
  "sessionId": "pool-desktop-sta:vm_7c1e:org_9f2a.YWJjZGVmZ2hpamts",
  "status": "ready",
  "expiresAt": "2026-07-16T12:30:00.000Z",
  "orgId": "org_9f2a"
}

DELETE/desktops/:id

Releases the host VM, frees the concurrency slot, and closes the billing segment.

Path parameters

Responses

Example request

curl -s -X DELETE "https://api.getsolari.com/desktops/$ENC" \
  -H "Authorization: Bearer $SOLARI_API_KEY"

Example response

{ "ok": true }

POST/desktops/:id/pause

Saves full RAM+disk state. Billing stops (you are billed only for active runtime) and it stops counting against your concurrency limit. Paused means stopped; resume picks up where it left off.

Path parameters

Responses

Example request

curl -s -X POST "https://api.getsolari.com/desktops/$ENC/pause" \
  -H "Authorization: Bearer $SOLARI_API_KEY"

Example response

{
  "sessionId": "pool-desktop-sta:vm_7c1e:org_9f2a.YWJjZGVmZ2hpamts",
  "status": "paused"
}

POST/desktops/:id/resume

Restores the RAM+disk snapshot and re-acquires a concurrency slot. A fresh billing segment opens.

Path parameters

Responses

Example request

curl -s -X POST "https://api.getsolari.com/desktops/$ENC/resume" \
  -H "Authorization: Bearer $SOLARI_API_KEY"

Example response

{
  "sessionId": "pool-desktop-sta:vm_7c1e:org_9f2a.YWJjZGVmZ2hpamts",
  "status": "ready"
}

Stream channel

WSwss://api.getsolari.com/stream/:id

Desktop-only. Serves plain RFB (VNC) bytes for embedding the live view. It is not JSON-RPC and has no REST equivalent. Returned as streamUrl from POST /desktops and from POST /sandboxes when kind: "desktop". Point any RFB client or noVNC at it.

Everything a desktop session does rides the control WebSocket instead: mouse and keyboard input, screenshots, clipboard, process and port listings. See the control channel, whose computer-use namespace is desktop-kind only.

Session ID format

The sessionId returned by POST /desktops is a signed, opaque capability:

<poolId>:<vmId>:<orgId>.<sig>

pool-desktop-sta:vm_7c1e:org_9f2a.YWJjZGVmZ2hpamts

The gateway verifies the signature and that the embedded org matches the caller's org. A forged, malformed, or cross-org id is indistinguishable from a missing one: both return 404.

Desktop ids are signed identically to sandbox ids and are accepted by every /sandboxes/:id/* route.