Browser API

HTTP reference for the browser gateway. Base URL https://api.getsolari.com. Every route except GET /health takes Authorization: Bearer slr_live_…. For the TypeScript client over these routes, see the browser SDK reference.

Contents

Sessions

POST/sessions

Creates a session and returns the endpoints to connect to. Counts against your concurrency limit until released.

Request body. Optional. A missing or non-JSON body is treated as all-defaults: a fast, unproxied, unrecorded session. Only a literal true opts a toggle in.

proxy object fields. All optional; unknown fields are ignored. The gateway coerces rather than rejects several of these: a non-string session, state, city or asn is silently dropped.

Cross-field rules, enforced in this order: proxy (anything but "off") requires stealth: true, else 400; stealth/proxy/captcha each require the plan's matching feature flag, else 402; captcha requires stealth: true, else 400.

Responses

Example request

# Fast session: no body needed.
curl -sS -X POST https://api.getsolari.com/sessions \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Stealth + sticky mobile proxy + recording.
curl -sS -X POST https://api.getsolari.com/sessions \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "stealth": true,
        "recording": true,
        "proxy": {
          "country": "us",
          "tier": "mobile",
          "session": "warm-1",
          "sessionDuration": 10
        }
      }'

Example response

{
  "sessionId": "AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo...Nzp2w9.RtY7dQxLmNbVcKsHj4FwZu",
  "wsEndpoint": "wss://api.getsolari.com/ws/AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo...Nzp2w9.RtY7dQxLmNbVcKsHj4FwZu",
  "cdpEndpoint": "wss://api.getsolari.com/cdp/AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo...Nzp2w9.RtY7dQxLmNbVcKsHj4FwZu",
  "expiresAt": "2026-07-17T09:00:00.000Z",
  "storageStateUrl": {
    "url": "https://storage.googleapis.com/cmowemxix0001mt01fxlwjc7m/cmusb5bzs01heny01tnvz9ddm/v7.json?X-Goog-Signature=…",
    "expiresInSeconds": 60
  },
  "proxy": {
    "timezoneId": "America/Los_Angeles",
    "country": "us",
    "tier": "mobile"
  }
}

The proxy is already applied to the browser you connect to, so there is nothing to wire up. Pass timezoneId to newContext({ timezoneId }) to match the browser clock to the egress IP. tier echoes which tier actually served the request, so you can confirm a mobile ask did not quietly degrade to residential.

Following the presigned URL for the cookies the SDK would have inlined for you:

SESSION=$(curl -sS -X POST https://api.getsolari.com/sessions \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stealth":true,"profileId":"cmusb5bzs01heny01tnvz9ddm"}')

echo "$SESSION" | jq -r '.wsEndpoint'

# A null url means "profile exists but was never saved": no seed.
URL=$(echo "$SESSION" | jq -r '.storageStateUrl.url // empty')
[ -n "$URL" ] && curl -sS "$URL" | jq .

GET/sessions/:id

Returns the gateway's view of a session: identity, lifecycle status, deadlines, and, while still usable, the connect endpoints. The gateway answers from its own state (the signed id, the owning pool's registration, and the session's concurrency reservation); it does not ask the browser. A well-formed id from your own org always gets a 200.

status is one of:

Path parameters

Responses

Example request

curl -sS -X GET \
  "https://api.getsolari.com/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SOLARI_API_KEY"

Example response

{
  "id": "AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo...Nzp2w9.RtY7dQxLmNbVcKsHj4FwZu",
  "status": "active",
  "kind": "fast",
  "org": "cmowemxix0001mt01fxlwjc7m",
  "createdAt": "2026-09-01T12:00:00.000Z",
  "expiresAt": "2026-09-01T13:00:00.000Z",
  "wsEndpoint": "wss://api.getsolari.com/ws/AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo...",
  "cdpEndpoint": "wss://api.getsolari.com/cdp/AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo..."
}

Confirming a release:

curl -sS -X DELETE "https://api.getsolari.com/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SOLARI_API_KEY"   # 204, forwarded async

curl -sS "https://api.getsolari.com/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SOLARI_API_KEY" | jq -r .status   # "released"

DELETE/sessions/:id

Releases the session and its concurrency slot. Idempotent: a second DELETE of the same ID also returns 204.

Path parameters

Responses

Example request

curl -sS -X DELETE \
  "https://api.getsolari.com/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SOLARI_API_KEY"
# 204 No Content on success, including for an already-released session.
# A 404 with code: InvalidSessionId means the ID was refused and NOTHING
# was released; do not treat it as success.

Example response

HTTP/1.1 204 No Content

GET/sessions/:id/replay-url

Returns a short-lived presigned URL for the session's rrweb replay. Only sessions created with recording: true produce one. Fetch the returned url directly, with no auth header. contentEncoding tells you what the bytes you actually receive will be — not what was uploaded. The stored object is always gzip, but on GCP the storage layer decompresses it transparently on an ordinary download, so contentEncoding is "identity" there and "gzip" on AWS. Check this field before decompressing — do not assume gzip.

Path parameters

Responses

Example request

# 404 is expected for a second or two after release; poll.
for i in 1 2 3 4 5; do
  RESP=$(curl -sS -w '\n%{http_code}' \
    "https://api.getsolari.com/sessions/$SESSION_ID/replay-url" \
    -H "Authorization: Bearer $SOLARI_API_KEY")
  CODE=$(echo "$RESP" | tail -n1)
  BODY=$(echo "$RESP" | sed '$d')
  [ "$CODE" = "200" ] && break
  sleep 1
done

# The presigned URL needs no auth header.
ENCODING=$(echo "$BODY" | jq -r .contentEncoding)
echo "$BODY" | jq -r .url | xargs curl -sS -o replay.ndjson
if [ "$ENCODING" = "gzip" ]; then
  gunzip -c replay.ndjson | head -n 3
else
  head -n 3 replay.ndjson
fi

Example response

{
  "url": "https://storage.googleapis.com/cmowemxix0001mt01fxlwjc7m/9d1c4e2a.ndjson.gz?X-Goog-Signature=…",
  "expiresInSeconds": 900,
  "contentEncoding": "identity"
}

Profiles

Persistent cookie/localStorage profiles. The org is taken from your API key, so cross-tenant reads are impossible.

GET/profiles

Lists every profile owned by the caller's org.

Responses

Example request

curl -sS https://api.getsolari.com/profiles \
  -H "Authorization: Bearer $SOLARI_API_KEY" | jq .

Example response

[
  { "id": "cmusb5bzs01heny01tnvz9ddm", "name": "linkedin-login" },
  { "id": "cmusc2x4z01hfny01qmdw3abc", "name": "shopify-admin" }
]

POST/profiles

Creates a new, empty profile. The returned id is immediately usable as POST /sessions { "profileId": … }: a fresh profile has no saved storage state, so the session's storageStateUrl.url comes back null and the browser starts from a clean context. Populate it by running the editor from the dashboard, or by driving a session and then calling POST /profiles/:id/save.

Request body

Responses

Example request

curl -sS -X POST https://api.getsolari.com/profiles \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"linkedin-login"}' | jq .

Example response

{ "id": "cmusb5bzs01heny01tnvz9ddm", "name": "linkedin-login" }

DELETE/profiles/:id

Deletes the profile row. Orphaned GCS objects (storage-state versions, legacy tarballs) are reaped by a separate lifecycle job, not inline.

Path parameters

Responses

Example request

curl -sS -X DELETE \
  "https://api.getsolari.com/profiles/cmusb5bzs01heny01tnvz9ddm" \
  -H "Authorization: Bearer $SOLARI_API_KEY"
# 204 on success. 409 means the dashboard editor is open on this profile.

Example response

HTTP/1.1 204 No Content

POST/profiles/:id/save

Persists a Playwright-shaped storageState (cookies + localStorage origins) to the profile, bumping its version. This is a pure control-plane operation on profile metadata. It touches no pool and no session, so save-without-a-session is a valid flow, e.g. migrating profiles out of a local Playwright harness into the platform.

Path parameters

Request body

Responses

Example request

# Playwright writes this file via context.storageState({ path: … }).
jq '{storageState: .}' storageState.json | curl -sS -X POST \
  "https://api.getsolari.com/profiles/cmusb5bzs01heny01tnvz9ddm/save" \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- | jq .

Example response

{
  "profileId": "cmusb5bzs01heny01tnvz9ddm",
  "version": 7,
  "storageStateS3Key": "cmowemxix0001mt01fxlwjc7m/cmusb5bzs01heny01tnvz9ddm/v7.json",
  "sizeBytes": 4211
}

Proxy

GET/proxy/countries

Returns the egress countries available to you, and whether managed proxy is available at all. Intended for region pickers and “should I even send proxy:?” guards. No SDK method exposes this route; it is a curl-only surface.

Responses

Example request

curl -sS https://api.getsolari.com/proxy/countries \
  -H "Authorization: Bearer $SOLARI_API_KEY" | jq .

Example response

{
  "enabled": true,
  "countries": ["au","br","ca","de","es","fr","gb","in","it","jp","kr","mx","nl","sg","us"],
  "tiers": {
    "residential": ["au","br","ca","de","es","fr","gb","in","it","jp","kr","mx","nl","sg","us"],
    "mobile": ["au","br","ca","de","es","fr","gb","in","it","jp","kr","mx","nl","sg","us"],
    "static": ["au","br","ca","de","fr","gb","in","it","jp","mx","nl","us"]
  }
}

Egress allowlist

allowedDomains on POST /sessions restricts a stealth session to a set of destination hostnames, subdomain-suffix matched — an entry of example.com permits example.com and any *.example.com, nothing else. Omitting the field (the default for every session) is unrestricted egress, unchanged.

Enforcement is network-level, below Chrome, not a navigation filter: every outbound connection a page makes — navigations, but also every image, script, stylesheet, and XHR/fetch it triggers — is checked, independently of how the connection is made: a direct DNS lookup for a non-allowlisted hostname resolves to NXDOMAIN; a request proxied through the slot's local CONNECT forwarder (used by every proxy-configured session) is checked against the same allowlist at the forwarder and refused with a 403 proxy response if the target host doesn't match; and a connection made entirely outside either of those paths — including a raw IP-literal destination, and including a raw CDP client over /cdp/ bypassing the shim this proxy and resolver instrument — is blocked at the packet level before it leaves the host.

Setting it: at create time (allowedDomains on POST /sessions, requires stealth: true, else 400) or any time after, below.

POST/sessions/:id/allowed-domains

Replaces the session's current allowlist in full — this is not an add, despite the create-time field's name; the gateway holds no partial list to merge against, so send your complete desired set every time. There is no endpoint to read the list back; track what you last sent.

Request body

Responses

System

GET/health

Liveness and capacity. Unauthenticated: the auth middleware short-circuits before the bearer check, making this the only customer-reachable route with no auth.

Responses

Example request

curl -sS https://api.getsolari.com/health | jq .

Example response

{
  "ok": true,
  "idle": 42,
  "busy": 7,
  "recycling": 1,
  "pools": 4,
  "saturated": false,
  "fast":    { "idle": 30, "busy": 4, "recycling": 0, "pools": 2 },
  "stealth": { "idle": 12, "busy": 3, "recycling": 1, "pools": 2 }
}

WebSocket upgrades

These are served by a raw upgrade hook that pipes TCP, not by the HTTP router. They are listed with a method and path because that is how they are addressed, but the responses below are handshake outcomes written directly to the socket, not JSON bodies.

WS/ws/:sessionId

Playwright wire-protocol upgrade, proxied to the owning pool's /ws/. This is the wsEndpoint returned by POST /sessions; connect with chromium.connect(wsEndpoint).

Path parameters

Responses

Example request

# curl cannot speak the Playwright wire protocol; this only proves the
# handshake succeeds. Real use: chromium.connect(wsEndpoint).
curl -sS -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $(head -c16 /dev/urandom | base64)" \
  "https://api.getsolari.com/ws/$SESSION_ID"

Example response

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

WS/cdp/:sessionId

Raw CDP upgrade, proxied to the owning pool's /cdp/. This is the cdpEndpoint returned by POST /sessions; connect with chromium.connectOverCDP(cdpEndpoint), Puppeteer, or any raw CDP client. Identical auth and semantics to /ws/:sessionId.

Path parameters

Responses

Example request

# Expect: HTTP/1.1 101 Switching Protocols.
# Real use: chromium.connectOverCDP(cdpEndpoint), or Puppeteer.
curl -sS -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $(head -c16 /dev/urandom | base64)" \
  "https://api.getsolari.com/cdp/$SESSION_ID"

Example response

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

WS/ws/observe/:sessionId

Bidirectional live-view stream for a session, used by the console's live view. This channel is not read-only. It carries screencast frames one way and input events the other: the viewer drives the real browser through it, and the pool dispatches what arrives as trusted CDP input.

So an observer is not a passive viewer. Opening the socket is well guarded — the signed URL alone is not enough, and this route additionally requires either an org-matching Authorization: Bearer key or a short-lived token minted for that exact session. But once open, granting observe access is granting control: whoever holds those credentials can type and click in the live session. That is the part the “read-only” wording denied.

Frame type is the discriminator, not direction. Binary frames are screencast imagery, forwarded from CDP Page.screencastFrame, and travel server to client only. Text frames carry structured JSON and travel in both directions: client to server they are input, dispatched by the pool as CDP Input.dispatchMouseEvent and Input.dispatchKeyEvent; server to client they are out-of-band metadata about the session, such as the guest's real viewport size, which a viewer needs in order to map a click correctly.

Do not treat either list as closed. A text message is identified by its type field, and new ones can appear in either direction without the transport changing — so branch on type, and ignore anything you do not recognise rather than failing on it.

The frame schema is owned jointly by the pool and the console, and neither end negotiates or versions it, so both must change together. A protocol mismatch is silent in both directions — it looks like nothing happening rather than an error. The pool dispatches on a message type through a chain with no fallback branch and drops anything it cannot parse; the console renders binary frames and discards text ones. Neither side reports that the other is speaking a different protocol.

Path and query parameters

Responses

Example request

curl -sS -i -N \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $(head -c16 /dev/urandom | base64)" \
  "https://api.getsolari.com/ws/observe/$SESSION_ID"

Example response

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

Session ID format

The ID returned by POST /sessions is an opaque, signed token — not a composite you can parse apart:

AgODjZhJuvsUOhwIXtabrWP8D_P6XOUAyXJBc4feYRziSSNo...Nzp2w9.RtY7dQxLmNbVcKsHj4FwZu

It is base64url (already URL-safe, no manual encoding needed) and carries no inspectable fields — routing, org scoping and URL lifetime are all enforced server-side against the signature, not read out of the string. The signature is verified on every route; the age is not, except where the table below says so.