Browserbase

2026-10-22

Browserbase

Connection guide

Base URL: https://api-develop.deepraxis.ai/browserbase

Request header: X-BB-API-Key: $PRAXIS_API_KEY

Request ID response header: X-Request-Id

Set baseURL in the official SDK to use these endpoints. Proxies, stealth options, extensions and Selenium are unavailable; region and solveCaptchas are accepted but ignored. Context deletion returns 200 with deleted=true; session responses may also include currentUrl, clients and handoff.

OperationMethod and path
Create a sessionPOST /browserbase/v1/sessions
List sessionsGET /browserbase/v1/sessions
Get a sessionGET /browserbase/v1/sessions/{id}
Close a sessionPOST /browserbase/v1/sessions/{id}
Get live URLsGET /browserbase/v1/sessions/{id}/debug
Get session logsGET /browserbase/v1/sessions/{id}/logs
Get session recordingGET /browserbase/v1/sessions/{id}/recording
Create a contextPOST /browserbase/v1/contexts
Get a contextGET /browserbase/v1/contexts/{id}
Delete a contextDELETE /browserbase/v1/contexts/{id}

Create a session

POST /browserbase/v1/sessions● Supported

Browserbase

Request parameters

  • projectIdstring可选

    The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key.

  • extensionIdstring可选○ 未支持

    This configuration is unavailable.

  • browserSettingsobject可选
    ▸ 展开子字段（14）
    • contextobject可选
      ▸ 展开子字段（2）
      • idstring必填

        The Context ID.

      • persistboolean可选

        Whether or not to persist the context after browsing. Defaults to `false`.

    • extensionIdstring可选○ 未支持

      This configuration is unavailable.

    • viewportobject可选
      ▸ 展开子字段（2）
      • widthinteger可选

        The width of the browser.

      • heightinteger可选

        The height of the browser.

    • blockAdsboolean可选◐ 部分支持

      Accepted but ignored; does not enable this capability.

    • solveCaptchasboolean可选◐ 部分支持

      Accepted but ignored; does not enable this capability.

    • recordSessionboolean可选◐ 部分支持

      Accepted but ignored; does not enable this capability.

    • logSessionboolean可选◐ 部分支持

      Accepted but ignored; does not enable this capability.

    • advancedStealthboolean可选○ 未支持

      This configuration is unavailable.

    • verifiedboolean可选○ 未支持

      This configuration is unavailable.

    • captchaImageSelectorstring可选

      Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)

    • captchaInputSelectorstring可选

      Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)

    • osstring可选○ 未支持

      This configuration is unavailable.

      取值 windowsmaclinuxmobiletablet
    • allowedDomainsarray可选○ 未支持
      默认 []

      This configuration is unavailable.

    • ignoreCertificateErrorsboolean可选○ 未支持

      This configuration is unavailable.

  • timeoutinteger可选

    Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`. Minimum 60 seconds, maximum 21600 seconds (6 hours).

  • keepAliveboolean可选

    Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above.

  • proxiesunion可选◐ 部分支持

    Only omission, false or [{type: 'none'}] is accepted; other proxy configurations return 501.

  • proxySettingsobject可选

    Supplementary proxy settings. Optional.

    ▸ 展开子字段（1）
    • caCertificatesarray可选
      默认 []

      The TLS certificate IDs to trust. Optional.

  • regionstring可选◐ 部分支持
    默认 "us-west-2"

    Accepted but ignored; does not enable this capability.

    取值 us-west-2us-east-1eu-central-1ap-southeast-1
  • userMetadataobject可选

    Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata).

Returns

201

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 201

The request has succeeded and a new resource has been created as a result.

application/json

NameTypeDescription
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the Session.
startedAtstring
endedAtstring
expiresAtstring
statusstring
proxyBytesintegerBytes used via the Proxy
keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
contextIdstringOptional. The Context linked to the Session.
regionstringThe region where the Session is running.
userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.
connectUrlstringWebSocket URL to connect to the Session.
seleniumRemoteUrlstringHTTP URL to connect to the Session.
signingKeystringSigning key to use when connecting to the Session via HTTP.

List sessions

GET /browserbase/v1/sessions● Supported

Browserbase

Request parameters

  • statusstring可选
    取值 PENDINGRUNNINGERRORTIMED_OUTCOMPLETED
  • qstring可选

    Query sessions by user metadata. See [Querying Sessions by User Metadata](/features/sessions#querying-sessions-by-user-metadata) for the schema of this query.

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
[].idstring
[].createdAtstring
[].updatedAtstring
[].projectIdstringThe Project ID linked to the Session.
[].startedAtstring
[].endedAtstring
[].expiresAtstring
[].statusstring
[].proxyBytesintegerBytes used via the Proxy
[].keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
[].contextIdstringOptional. The Context linked to the Session.
[].regionstringThe region where the Session is running.
[].userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.

Get a session

GET /browserbase/v1/sessions/{id}● Supported

Browserbase

Request parameters

  • idstring必填

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the Session.
startedAtstring
endedAtstring
expiresAtstring
statusstring
proxyBytesintegerBytes used via the Proxy
keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
contextIdstringOptional. The Context linked to the Session.
regionstringThe region where the Session is running.
userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.
connectUrlstringWebSocket URL to connect to the Session.
seleniumRemoteUrlstringHTTP URL to connect to the Session.
signingKeystringSigning key to use when connecting to the Session via HTTP.

Close a session

POST /browserbase/v1/sessions/{id}● Supported

Browserbase

Request parameters

  • idstring必填
  • statusstring必填

    Set to `REQUEST_RELEASE` to request that the session complete. Use before session's timeout to avoid additional charges.

    取值 REQUEST_RELEASE

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the Session.
startedAtstring
endedAtstring
expiresAtstring
statusstring
proxyBytesintegerBytes used via the Proxy
keepAlivebooleanIndicates if the Session was created to be kept alive upon disconnections
contextIdstringOptional. The Context linked to the Session.
regionstringThe region where the Session is running.
userMetadataobjectArbitrary user metadata to attach to the session. To learn more about user metadata, see User Metadata.

Get live URLs

GET /browserbase/v1/sessions/{id}/debug● Supported

Browserbase

Request parameters

  • expiresIninteger可选

    Time-to-live of the generated live view URLs, in seconds. If omitted, the URLs expire with the session, up to a maximum of 21600 seconds (6 hours).

  • idstring必填

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
debuggerFullscreenUrlstring
debuggerUrlstring
pagesarray<object>
pages[].idstring
pages[].urlstring
pages[].faviconUrlstring
pages[].titlestring
pages[].debuggerUrlstring
pages[].debuggerFullscreenUrlstring
wsUrlstring

Get session logs

GET /browserbase/v1/sessions/{id}/logs● Supported

Browserbase

Request parameters

  • idstring必填

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
[].methodstring
[].pageIdinteger
[].sessionIdstring
[].requestobject
[].request.timestampintegermilliseconds that have elapsed since the UNIX epoch
[].request.paramsobject
[].request.rawBodystring
[].responseobject
[].response.timestampintegermilliseconds that have elapsed since the UNIX epoch
[].response.resultobject
[].response.rawBodystring
[].timestampintegermilliseconds that have elapsed since the UNIX epoch
[].frameIdstring
[].loaderIdstring

Get session recording

GET /browserbase/v1/sessions/{id}/recording● Supported

Browserbase

Request parameters

  • idstring必填

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
[].idstring
[].dataobjectSee rrweb documentation.
[].sessionIdstring
[].timestampintegermilliseconds that have elapsed since the UNIX epoch
[].typeinteger

Create a context

POST /browserbase/v1/contexts● Supported

Browserbase

Request parameters

  • projectIdstring可选

    The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key.

  • namestring可选

    Optional user-defined name for the Context. Leading and trailing whitespace is trimmed before storage. Names are unique within the project among active Contexts, compared case-insensitively.

Returns

201

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 201

The request has succeeded and a new resource has been created as a result.

application/json

NameTypeDescription
idstring
publicKeystringThe public key to encrypt the user-data-directory.
cipherAlgorithmstringThe cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm.
initializationVectorSizeintegerThe initialization vector size used to encrypt the user-data-directory. Read more about how to use it.

Get a context

GET /browserbase/v1/contexts/{id}● Supported

Browserbase

Request parameters

  • idstring必填

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

Response

HTTP 200

The request has succeeded.

application/json

NameTypeDescription
idstring
createdAtstring
updatedAtstring
projectIdstringThe Project ID linked to the uploaded Context.
namestringOptional user-defined name for the Context. Leading and trailing whitespace is trimmed before storage. Names are unique within the project among active Contexts, compared case-insensitively.

Delete a context

DELETE /browserbase/v1/contexts/{id}● Supported

Browserbase

Request parameters

  • idstring必填

Returns

200

Only the capabilities in the service guide are available; some upstream options are unavailable.

Errors contain statusCode, error and message; the native API adds code. The request ID is in X-Request-Id. Errors

Connection guide

Proxies, stealth options, extensions and Selenium are unavailable. region and solveCaptchas are accepted but ignored; region selection and CAPTCHA solving are not provided.

This endpoint returns 200 and a JSON acknowledgement; Browserbase returns 204.

Response

HTTP 200

Context deleted. Praxis returns JSON instead of Browserbase's 204.

application/json

NameTypeDescription
deletedboolean