HTTP API
Authenticate project-resource calls and look up every current session, connection, handoff, and file endpoint.
Append /v1 to your instance root URL. Send Authorization: Bearer YOUR_PROJECT_KEY. Use HTTPS on public deployments.
JSON requests use camelCase fields and Content-Type application/json. Session and handoff creation require an Idempotency-Key header containing 1–128 characters.
Endpoints
Paths below are relative to /v1.
| Method | Path | Result |
|---|---|---|
| POST | /browser-sessions | 202, accepted session snapshot |
| GET | /browser-sessions | Paginated session list |
| GET | /browser-sessions/:id | Current session |
| PATCH | /browser-sessions/:id | Extend lifetime or configure idle timeout |
| POST | /browser-sessions/:id/touch | Renew idle activity; empty body |
| GET | /browser-sessions/:id/events | Authenticated SSE snapshots |
| POST | /browser-sessions/:id/close | 202 while closing, otherwise 200 |
| POST | /browser-sessions/:id/connections | 201, secret connection grant |
| POST | /browser-sessions/:id/handoffs | 202, handoff resource |
| GET | /browser-sessions/:id/handoffs/:handoff | Current handoff |
| POST | /browser-sessions/:id/handoffs/:handoff/complete | 202 while returning, otherwise 200 |
| POST | /browser-sessions/:id/files | Multipart upload |
| GET | /browser-sessions/:id/files | Paginated file list |
| GET | /browser-sessions/:id/files/:file | File metadata |
| GET | /browser-sessions/:id/files/:file/content | Binary content stream |
| DELETE | /browser-sessions/:id/files/:file | 204, no body |
| POST | /profiles | 201, Profile metadata; idempotency key required |
| GET | /profiles | Paginated Profile metadata |
| GET | /profiles/:id | Profile metadata |
| DELETE | /profiles/:id | 204; 409 while occupied |
Create a session
curl --fail-with-body "$TABSAIL_BASE_URL/v1/browser-sessions" \
-H "Authorization: Bearer $TABSAIL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: YOUR_UNIQUE_OPERATION_ID" \
--data '{"timeoutSeconds":300,"region":"auto","viewport":{"width":1000,"height":760},"metadata":{"purpose":"smoke-test"}}'| Field | Accepted value | If omitted |
|---|---|---|
| region | auto, west, asia | auto |
| timeoutSeconds | Integer 60–3,600 | Deployment's configured default |
| idleTimeoutSeconds | Integer 60–3,600, or null | Disabled |
| browser | Supported settings | Default browser configuration |
| profile | { id, persistOnClose? } | Fresh browser state |
| viewport | width and height integers 320–4,096 | Deployment's configured default |
| metadata | Up to 10 string entries; key ≤64, value ≤256 characters | Empty object |
Unknown create fields are rejected. Profile IDs are supported; customer proxy options are not available. A repeated accepted key can return the original creation snapshot; GET the resource to read its current state.
Connect, transfer, and close
A connection body is one of:
{"type":"cdp"}{"type":"live","mode":"view"}{"type":"live","mode":"control","handoffId":"YOUR_ACTIVE_HANDOFF_ID"}The last form requires an active handoff and human control. Grant URLs authorize access; keep them private.
Handoff creation accepts {"reason":"..."}, with up to 256 characters. Close and handoff completion should send an empty body. Wait for resource state rather than treating an accepted response as completion.
Upload uses multipart/form-data with one binary field named file. File operations require a ready, unexpired session. See File transfer.
Lists and updates
List parameters: limit 1–100, default 20; cursor from the prior response. Session lists accept status; file lists accept origin=upload|download. Responses contain items and nullable nextCursor.
The events endpoint sends complete session snapshots. It is not a durable event-history API. Prefer the SDK helpers for authenticated subscriptions, reconnect synchronization, and polling compatibility.
Failures use the structured error contract. An OpenAPI specification and interactive API playground are not yet published.