API reference

The raw HTTP surface: every endpoint, every status code, every body shape, callable with curl or any HTTP client. No SDK required and no SDK code on these pages. If you work in TypeScript, Python, Go, Rust or C++, the SDK reference documents the client libraries that wrap these routes.

Contents

Base URLs

The browser product and the VM/sandbox product are separate gateways on separate hosts. One API key works on both.

Request and response bodies are JSON unless stated otherwise. Set Content-Type: application/json on any request that carries a body. The two file data-path routes on the VM gateway are the exception: they move raw application/octet-stream bytes.

Authentication

Every route takes your console API key as a bearer token. The key format is slr_live_<id>_<secret>.

GET /profiles HTTP/1.1
Host: api.getsolari.com
Authorization: Bearer slr_live_4b91ac2f_s3cr3tvalue

Create keys in the console. A key is shown once, at creation. There are four exceptions to the bearer rule:

Errors

Body shape

Both gateways return a JSON object with a human-readable error. Some handlers add a machine-readable code; branch on the status or on code, never on the prose.

{
  "code": "ConcurrencyLimitExceeded",
  "error": "Concurrent session limit reached (20)",
  "plan": "starter",
  "cap": 20
}

Individual errors carry extra context fields alongside these: plan, cap, feature, supported, profileId. They are documented on the endpoints that emit them.

Code values

Retries and status conventions

On the VM gateway, a transient failure additionally carries "retryable": true in the body, which is the signal to prefer over the bare status. Send Idempotency-Key: <uuid-v4> on create routes to make that retry safe. GET and DELETE are idempotent by nature: deleting an already-gone VM still returns 200 {"ok": true}.

Sections

End-to-end example

Create a sandbox, run a command on it over the warm HTTP fast path, then kill it. URL-encode the session ID before putting it in a path; it contains : and ..

export SOLARI_API_KEY=slr_live_…

# 1. Create. The Idempotency-Key makes a retry safe.
SANDBOX=$(curl -sS -X POST https://api.getsolari.com/sandboxes \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"template":"base","cpu":2,"memMb":2048}')

ID=$(echo "$SANDBOX" | jq -r .sandboxId)
ENC=$(jq -rn --arg v "$ID" '$v|@uri')

# 2. Run one command. No shell: cmd is the binary, args its argv tail.
curl -sS -X POST "https://api.getsolari.com/sandboxes/$ENC/exec" \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"python3","args":["--version"]}' | jq .
# => { "exitCode": 0, "stdout": "Python 3.11.2\n", "stderr": "" }

# 3. Kill it. Idempotent: a second DELETE also returns {"ok": true}.
curl -sS -X DELETE "https://api.getsolari.com/sandboxes/$ENC" \
  -H "Authorization: Bearer $SOLARI_API_KEY"

Health probes

On the shared api.getsolari.com host, the public GET /health is answered by the browser gateway and reports pool capacity (documented in full as GET /health). It is unauthenticated. The VM gateway's bare { "ok": true } liveness probes run behind the load balancer and are not exposed at this hostname: GET /healthz returns 401 here.

GET/health

Unauthenticated pool-health probe served by the browser gateway. Reports idle/busy pool counts and saturation. See the browser reference for the full body.

Example request

curl -s https://api.getsolari.com/health

Example response

{ "ok": true, "idle": 68, "busy": 2, "recycling": 0, "pools": 6, "saturated": false }

GET/healthz

The VM gateway's container liveness probe. Not exposed on the public api.getsolari.com host, where it returns 401.

Example request

curl -s https://api.getsolari.com/healthz
# {"error":"Unauthorized"}

For error semantics in the SDKs rather than on the wire, see Errors.