API Reference

Sessions API

View as Markdown

All session lifecycle endpoints. Authenticated via Bearer API key.

POST /v1/sessions

Create a new browser session.

$curl -s https://api.chaser.sh/v1/sessions \
>  -X POST \
>  -H "Authorization: Bearer $CHASER_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "ttl_seconds": 1800
>  }' | jq

Request body:

FieldTypeDefaultDescription
profilestringdefaultInternal profile label. Omit unless instructed.
ttl_secondsinteger1800Session lifetime in seconds. Range: 60–3600.

Response 201:

1{
2  "id": "sess_019ec0d0-a88a-73f2-9741-8030dc82a854",
3  "object": "session",
4  "status": "creating",
5  "cdp_url": "wss://cdp.chaser.sh/sessions/sess_019ec0d0-a88a-73f2-9741-8030dc82a854",
6  "created_at": "2026-06-13T11:49:20.651182Z",
7  "expires_at": "2026-06-13T11:59:20.650185Z"
8}

The session transitions from creating to ready in ~15–25 seconds. The cdp_url field appears when ready.

GET /v1/sessions

List sessions in the authenticated workspace, newest first. Cursor-paged.

$curl -s "https://api.chaser.sh/v1/sessions?limit=10" \
>  -H "Authorization: Bearer $CHASER_KEY" | jq

Query parameters:

ParameterTypeDefaultDescription
limitinteger20Max results per page. Range: 1–100.
cursorstring—Cursor from previous response’s next_cursor.

Response 200:

1{
2  "object": "list",
3  "data": [
4    {
5      "id": "sess_019ec0d0-a88a-73f2-9741-8030dc82a854",
6      "object": "session",
7      "status": "ready",
8      "device": "Android 10 - Chrome 137 (Mobile)",
9      "cdp_url": "wss://cdp.chaser.sh/sessions/sess_019ec0d0-a88a-73f2-9741-8030dc82a854",
10      "bytes_up": 22500,
11      "bytes_down": 25503,
12      "proxy_ip": null,
13      "proxy_region": null,
14      "created_at": "2026-06-13T11:49:20.651182Z",
15      "ready_at": "2026-06-13T11:49:38.102017Z",
16      "expires_at": "2026-06-13T11:59:20.650185Z",
17      "ended_at": null,
18      "ended_reason": null
19    }
20  ],
21  "next_cursor": "MjAyNi0wNi0xM1QxMTo0OToyMC42NTExODIrMDA6MDB8MDE5ZWMwZDAt...",
22  "has_more": true
23}

GET /v1/sessions/:id

Get a single session by ID.

$curl -s "https://api.chaser.sh/v1/sessions/sess_019ec0b4-b174-7e90-91b3-02032470cb24" \
>  -H "Authorization: Bearer $CHASER_KEY" | jq

Response 200:

1{
2  "id": "sess_019ec0d0-a88a-73f2-9741-8030dc82a854",
3  "object": "session",
4  "status": "ready",
5  "device": "Android 10 - Chrome 137 (Mobile)",
6  "cdp_url": "wss://cdp.chaser.sh/sessions/sess_019ec0d0-a88a-73f2-9741-8030dc82a854",
7  "bytes_up": 22500,
8  "bytes_down": 25503,
9  "proxy_ip": null,
10  "proxy_region": null,
11  "created_at": "2026-06-13T11:49:20.651182Z",
12  "ready_at": "2026-06-13T11:49:38.102017Z",
13  "expires_at": "2026-06-13T11:59:20.650185Z",
14  "ended_at": null,
15  "ended_reason": null
16}
FieldDescription
statuscreating, ready, closed, or error
cdp_urlWebSocket CDP endpoint. Present from creation.
deviceHuman-readable device description.
bytes_upTotal bytes uploaded (cumulative).
bytes_downTotal bytes downloaded (cumulative).
proxy_ipEgress proxy IP. Populated once connected.
proxy_regionEgress proxy region.
ready_atWhen the session became ready.
ended_atWhen the session ended (if closed).
ended_reasonWhy the session ended (if closed).

Errors:

StatusCodeMeaning
404session_not_foundSession doesn’t exist or doesn’t belong to your workspace.

DELETE /v1/sessions/:id

Delete a session. Stops egress, releases the proxy, marks ended_reason: "client_delete".

$curl -s -X DELETE "https://api.chaser.sh/v1/sessions/sess_019ec0b4-b174-7e90-91b3-02032470cb24" \
>  -H "Authorization: Bearer $CHASER_KEY" \
>  -w "\nHTTP %{http_code}\n"

Response: 204 (no body).

Errors:

StatusCodeMeaning
409session_not_openSession is already closed/expired. That’s fine — it’s already stopped.

POST /v1/sessions/:id/screenshot

Capture the session framebuffer as a PNG.

$curl -s "https://api.chaser.sh/v1/sessions/sess_019ec0d0-a88a-73f2-9741-8030dc82a854/screenshot" \
>  -X POST \
>  -H "Authorization: Bearer $CHASER_KEY" \
>  -o screenshot.png \
>  -w "HTTP %{http_code}, size: %{size_download} bytes\n"

Response: Raw PNG bytes (image/png). No JSON wrapping.

Errors:

StatusCodeMeaning
409session_not_openSession is not in ready state.
404session_not_foundSession doesn’t exist or doesn’t belong to your workspace.

POST /v1/sessions/:id/preview-token

Mint a token for the live-view WebSocket stream.

$curl -s "https://api.chaser.sh/v1/sessions/sess_019ec0d0-a88a-73f2-9741-8030dc82a854/preview-token" \
>  -X POST \
>  -H "Authorization: Bearer $CHASER_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{}' | jq

Request body: Empty JSON object {}. Reserved for future options.

Response 200:

1{
2  "url": "wss://stream.chaser.sh/sessions/sess_019ec0d0-a88a-73f2-9741-8030dc82a854/preview?token=eyJ...",
3  "expires_at": "2026-06-13T11:54:41.836Z",
4  "input_enabled": true,
5  "fps": 5
6}
FieldDescription
urlWebSocket URL for the preview stream. Open in the dashboard.
expires_atToken validity. Mint a new token to resume.
input_enabledWhether click/tap input is forwarded to the session.
fpsFrame rate (currently 5).

Errors:

StatusCodeMeaning
409session_not_openSession is not in ready state.
404session_not_foundSession doesn’t exist or doesn’t belong to your workspace.