REST API reference
Manage browser sessions, connection URLs, signed viewers, and workspace usage.
Request conventions
Base URL: https://api.tabfleet.com. Authenticate with Authorization: Bearer YOUR_TABFLEET_API_KEY. Use JSON bodies and Content-Type: application/json. Responses are not cached.
Browser actions such as navigation and snapshots are available through MCP or an external CDP controller; there is no public REST /action endpoint. Manage account sign-in, workspace creation, and API keys through the dashboard.
POST /v1/sessions
Create a browser. Requires a Browser control key and an Idempotency-Key containing 8–128 letters, digits, underscores, or hyphens. A new session returns 201; a retained matching retry returns 200 without launching again. Changing options with the same ID returns 409.
A retry of a failed or closed session does not relaunch it while its record is retained. A hard lease does not keep an idle browser alive.
| Body field | Type / default | Range |
|---|---|---|
| durationSeconds | integer · 300 | 60–3600 seconds |
| idleTimeoutSeconds | integer · 60 | 60–600 seconds |
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"createdAt": "2026-09-12T12:00:00.000Z",
"expiresAt": "2026-09-12T12:05:00.000Z",
"endedAt": null,
"idleTimeoutSeconds": 120,
"closeReason": null,
"allocatedSeconds": 2,
"cdpUrl": "wss://api.tabfleet.com/v1/sessions/SESSION_ID/connect?token=TOKEN",
"connectionTokenTtlSeconds": 298
}GET /v1/sessions
Returns {sessions: [...], retainedHistoryLimit: 100} with up to 100 newest workspace session records. List entries contain public session fields but no connection URL. Operational history is not an artifact store.
GET /v1/sessions/:id
Returns one public session object. Status values are creating, active, closing, closed, or failed. IDs outside the authenticated workspace return 404.
allocatedSeconds estimates elapsed service allocation; it is not a provider billing measurement. endedAt remains null until the session is finalized.
DELETE /v1/sessions/:id
Requires Browser control. Disconnects the browser’s controller and viewer, then closes the session. Returns 200 when closed or 202 while cleanup retries. Repeating the call on an ended session is safe. Unused reserved time is returned after confirmed cleanup.
POST /v1/sessions/:id/connection
Requires Browser control and an active browser. Returns the session object with a fresh cdpUrl and connectionTokenTtlSeconds. New connection tokens last up to five minutes, capped by the lease.
Connect by WebSocket to the returned /v1/sessions/:id/connect?token=… URL. One external controller may be attached at a time. An existing controller connection is governed by the session lifetime, not the token’s new-connection expiration.
POST /v1/sessions/:id/viewer
Returns {viewerUrl: "wss://api.tabfleet.com/v1/sessions/SESSION_ID/view?token=…"} for a restricted page-scoped WebSocket. This is a stream connection, not an HTML viewer link. Read-only keys cannot send input or navigation commands.
For a ready-to-embed HTML viewer, use /share below. Up to eight dashboard and standalone viewers can connect to the same browser. Closing one viewer leaves the others connected.
DELETE /v1/sessions/:id/share
Requires Browser control. Revokes every signed viewer link for this session and immediately disconnects its signed viewer. Returns {revoked: true, sessionId: "…"}. The browser and its agent remain running. Newly minted links work normally.
GET or POST /v1/viewer-settings
GET returns {origins: [], version: 0} for the default policy. POST requires Browser control and accepts {origins: ["https://your-app.example"]} to replace the allowlist.
Use at most 20 exact HTTPS origins, each at most 256 characters, without paths, trailing slashes, or wildcards. [] disables embedding. Changing this setting revokes every existing signed viewer link in the workspace, including connected signed viewers. See the embedding guide.
GET /v1/usage
Returns cumulative session counts, allocation estimates, active session count, and the current workspace budget. Use budget.availableSeconds when choosing the next lease duration. Full leases reserve trial time before launch.
{
"completedSessions": 1,
"failedSessions": 0,
"allocatedMilliseconds": 38000,
"activeSessions": 0,
"inProgressAllocatedMilliseconds": 0,
"budget": {
"allowanceSeconds": 1800,
"chargedSeconds": 38,
"reservedSeconds": 0,
"suspended": false,
"availableSeconds": 1762
},
"measurement": "service_allocation_not_provider_billing"
}GET /health
Public endpoint returning {status: "ok"}. This checks the API process, not available browser capacity or readiness to provision a session.
Errors and retries
REST errors use {error: {code: "…", message: "…"}}. Respect Retry-After when present. Reuse the same creation idempotency key only for retries of the same launch. See troubleshooting for recovery by error code.
Paginate session history
GET /v1/sessions accepts limit (1–100, default 100) and cursor. Responses retain sessions and retainedHistoryLimit and add limit, hasMore, and nextCursor. Pass the returned nextCursor unchanged on the next request; null means the end of the retained history.
Results are ordered by creation time descending, then session ID descending. Cursors are bound to your workspace. Newly created sessions appear when you restart from the first page; an ongoing traversal does not include newer arrivals. Statuses may change and expired history can disappear between requests.
Pagination does not extend retention: Tabfleet keeps at most 100 completed sessions plus active sessions, with cleanup performed periodically. A cursor is a position, not an access credential; every request still requires your workspace API key. Invalid or cross-workspace cursors return 400 invalid_pagination. MCP list_sessions accepts the same optional limit and cursor inputs.
GET https://api.tabfleet.com/v1/sessions?limit=20
Authorization: Bearer YOUR_API_KEY
# Continue with nextCursor from the response:
GET https://api.tabfleet.com/v1/sessions?limit=20&cursor=NEXT_CURSOR