Hivebrowser
API Reference

Sessions

Create, list, inspect, and stop managed browser sessions.

Use whenYou need a live browser

Use sessions for rendering, login flows, screenshots, or Playwright.

ControlTimeout and stop explicitly

Set timeoutSec, close the client, and stop the session after work.

DebugKeep runtime evidence

Persist the session id and use live preview, snapshots, logs, and replay for failed runs.

API Boundary

Owns
Runtime capacity and connection

Create capacity, return the CDP connectUrl, and expose debugging evidence.

Prod
Close the path explicitly

Persist the session id, set timeoutSec, and stop when work is done.

Handoff
Use keepAlive only when needed

Reserve keepAlive for human inspection or process handoff. See Sessions.

List Sessions

GET/v1/sessionsShow endpoint detailsHide endpoint details
GET/v1/sessions

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Session list

Response example
{
  "data": {
    "items": [
      {
        "id": "string",
        "teamId": "string",
        "status": "PENDING",
        "closeReason": "USER_REQUEST",
        "browserPlatform": "WINDOWS",
        "browserVersion": "string",
        "region": "string",
        "runnerId": "string",
        "profileId": "string",
        "endpoints": {
          "connectUrl": "http://example.com",
          "wsEndpoint": "http://example.com",
          "liveUrl": "http://example.com",
          "webdriverUrl": "http://example.com",
          "computerActionUrl": "http://example.com"
        },
        "proxy": {
          "server": "string",
          "username": "string",
          "password": "string",
          "bypass": [
            "string"
          ]
        },
        "viewport": {
          "width": 1,
          "height": 1,
          "deviceScaleFactor": 0
        },
        "timeoutSec": 0,
        "keepAlive": true,
        "metadata": {
          "property1": null,
          "property2": null
        },
        "startedAt": "2019-08-24T14:15:22Z",
        "closedAt": "2019-08-24T14:15:22Z",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "total": 0,
    "page": 1,
    "pageSize": 0
  }
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}

Create a Session

POST/v1/sessionsShow endpoint detailsHide endpoint details
POST/v1/sessions

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Request Body

application/jsonRequired
browserPlatformstring

Target platform for browser emulation

Value in: "WINDOWS" | "MACOS" | "ANDROID"
browserVersionstring

Specific browser version to use

Minimum length: 1
regionstring

Preferred region for session placement

Minimum length: 1
profileobject

Browser profile to attach to this session

Show Attributes
profileIdRequiredstring

ID of the profile to attach

Minimum length: 1
modestring

Access mode for the attached profile

Default: "READ_ONLY"Value in: "READ_ONLY" | "READ_WRITE"
persistChangesboolean

Whether to persist changes back to the profile on session close

Default: false
proxyobject

Proxy configuration for this session

Show Attributes
serverRequiredstring

Proxy server URL (e.g., http://proxy.example.com:8080)

Minimum length: 1
usernamestring

Proxy authentication username

Minimum length: 1
passwordstring

Proxy authentication password

Minimum length: 1
bypassarray<string>

List of hosts to bypass the proxy

viewportobject

Browser viewport dimensions

Show Attributes
widthRequiredinteger

Viewport width in pixels

Minimum: 1
heightRequiredinteger

Viewport height in pixels

Minimum: 1
deviceScaleFactornumber

Device scale factor (DPR)

timeoutSecinteger

Session timeout in seconds (max 24 hours)

Minimum: 1Maximum: 86400
keepAliveboolean

Keep session alive after client disconnects

Default: false
metadataobject

Arbitrary key-value metadata for the session

Show Attributes
[key: string]unknown
cURL
curl -X POST "https://api.hivebrowser.ai/v1/sessions" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{    "browserPlatform": "WINDOWS",    "browserVersion": "string",    "region": "string",    "profile": {      "profileId": "string",      "mode": "READ_ONLY",      "persistChanges": false    },    "proxy": {      "server": "string",      "username": "string",      "password": "string",      "bypass": [        "string"      ]    },    "viewport": {      "width": 1,      "height": 1,      "deviceScaleFactor": 0    },    "timeoutSec": 1,    "keepAlive": false,    "metadata": {      "property1": null,      "property2": null    }  }'
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions", {  headers: {    "Authorization": "Bearer <token>"  },  body: JSON.stringify({    "browserPlatform": "WINDOWS",    "browserVersion": "string",    "region": "string",    "profile": {      "profileId": "string",      "mode": "READ_ONLY",      "persistChanges": false    },    "proxy": {      "server": "string",      "username": "string",      "password": "string",      "bypass": [        "string"      ]    },    "viewport": {      "width": 1,      "height": 1,      "deviceScaleFactor": 0    },    "timeoutSec": 1,    "keepAlive": false,    "metadata": {      "property1": null,      "property2": null    }  })});
Response 201

Session created

Response example
{
  "data": {
    "id": "string",
    "teamId": "string",
    "status": "PENDING",
    "closeReason": "USER_REQUEST",
    "browserPlatform": "WINDOWS",
    "browserVersion": "string",
    "region": "string",
    "runnerId": "string",
    "profileId": "string",
    "endpoints": {
      "connectUrl": "http://example.com",
      "wsEndpoint": "http://example.com",
      "liveUrl": "http://example.com",
      "webdriverUrl": "http://example.com",
      "computerActionUrl": "http://example.com"
    },
    "proxy": {
      "server": "string",
      "username": "string",
      "password": "string",
      "bypass": [
        "string"
      ]
    },
    "viewport": {
      "width": 1,
      "height": 1,
      "deviceScaleFactor": 0
    },
    "timeoutSec": 0,
    "keepAlive": true,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "startedAt": "2019-08-24T14:15:22Z",
    "closedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Response 400

Invalid request payload

Response example
{
  "error": "string",
  "message": "string"
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}
Response 429

Quota exceeded (concurrent sessions or runtime)

Response example
{
  "error": "string",
  "message": "string"
}
Response 503

Session creation failed (no healthy runner available)

Response example
{
  "error": "string",
  "message": "string"
}

Get a Session

GET/v1/sessions/{id}Show endpoint detailsHide endpoint details
GET/v1/sessions/{id}

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Path Parameters

idRequiredstring

Session ID

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions/string" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Session details

Response example
{
  "data": {
    "id": "string",
    "teamId": "string",
    "status": "PENDING",
    "closeReason": "USER_REQUEST",
    "browserPlatform": "WINDOWS",
    "browserVersion": "string",
    "region": "string",
    "runnerId": "string",
    "profileId": "string",
    "endpoints": {
      "connectUrl": "http://example.com",
      "wsEndpoint": "http://example.com",
      "liveUrl": "http://example.com",
      "webdriverUrl": "http://example.com",
      "computerActionUrl": "http://example.com"
    },
    "proxy": {
      "server": "string",
      "username": "string",
      "password": "string",
      "bypass": [
        "string"
      ]
    },
    "viewport": {
      "width": 1,
      "height": 1,
      "deviceScaleFactor": 0
    },
    "timeoutSec": 0,
    "keepAlive": true,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "startedAt": "2019-08-24T14:15:22Z",
    "closedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}
Response 404

Resource not found

Response example
{
  "error": "string",
  "message": "string"
}

Stop a Session

POST/v1/sessions/{id}/stopShow endpoint detailsHide endpoint details
POST/v1/sessions/{id}/stop

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Path Parameters

idRequiredstring

Session ID

cURL
curl -X POST "https://api.hivebrowser.ai/v1/sessions/string/stop" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string/stop", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Session stopped

Response example
{
  "data": {
    "id": "string",
    "teamId": "string",
    "status": "PENDING",
    "closeReason": "USER_REQUEST",
    "browserPlatform": "WINDOWS",
    "browserVersion": "string",
    "region": "string",
    "runnerId": "string",
    "profileId": "string",
    "endpoints": {
      "connectUrl": "http://example.com",
      "wsEndpoint": "http://example.com",
      "liveUrl": "http://example.com",
      "webdriverUrl": "http://example.com",
      "computerActionUrl": "http://example.com"
    },
    "proxy": {
      "server": "string",
      "username": "string",
      "password": "string",
      "bypass": [
        "string"
      ]
    },
    "viewport": {
      "width": 1,
      "height": 1,
      "deviceScaleFactor": 0
    },
    "timeoutSec": 0,
    "keepAlive": true,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "startedAt": "2019-08-24T14:15:22Z",
    "closedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}
Response 404

Resource not found

Response example
{
  "error": "string",
  "message": "string"
}
Response 502

Failed to stop session on runner

Response example
{
  "error": "string",
  "message": "string"
}

Live Session Preview

GET/v1/sessions/{id}/liveShow endpoint detailsHide endpoint details
GET/v1/sessions/{id}/live

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Path Parameters

idRequiredstring

Session ID

Query Parameters

tokenstring

Live access token for unauthenticated access

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions/string/live?token=string" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string/live?token=string", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

HTML live preview page

Response example
"string"
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}
Response 404

Resource not found

Response example
{
  "error": "string",
  "message": "string"
}

Live Session Snapshot

GET/v1/sessions/{id}/live/snapshotShow endpoint detailsHide endpoint details
GET/v1/sessions/{id}/live/snapshot

Authorization

AuthorizationRequiredBearer <token>

API key passed as a Bearer token in the Authorization header.

In: header

x-hivebrowser-api-key<token>

API key passed directly in the x-hivebrowser-api-key header.

In: header

Path Parameters

idRequiredstring

Session ID

Query Parameters

tokenstring

Live access token for unauthenticated access

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions/string/live/snapshot?token=string" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string/live/snapshot?token=string", {  headers: {    "Authorization": "Bearer <token>"  }});
Response 200

Screenshot image

Response example
"string"
Response 401

Missing or invalid API key

Response example
{
  "error": "string",
  "message": "string"
}
Response 404

Resource not found

Response example
{
  "error": "string",
  "message": "string"
}

On this page

API BoundaryList SessionsCreate a SessionGet a SessionStop a SessionLive Session PreviewLive Session Snapshot