openapi: 3.0.0 info: title: Browserbase API description: Browserbase API for 3rd party developers version: v1 servers: - url: "https://api.browserbase.com" description: Public endpoint variables: {} paths: /v1/agents: post: operationId: Agents_create summary: Create an Agent description: Create a reusable agent. An agent defines a `systemPrompt` and `resultSchema` that guide its behavior for every run. Only `name` is required; an agent created with no `systemPrompt` behaves like an unconfigured run. requestBody: required: true content: application/json: schema: type: object properties: name: description: Human-readable name for the agent. Used to identify the agent in the dashboard and API responses. type: string maxLength: 255 minLength: 1 systemPrompt: description: System prompt that steers the agent's behavior on every run that uses this agent. type: string minLength: 1 resultSchema: description: "An optional [JSON Schema](https://json-schema.org/specification) object. If provided, runs that reference this agent will aim to return a `result` that conforms to this schema when they complete. Can be overridden per run by passing `resultSchema` on the run request." type: object additionalProperties: true properties: {} additionalProperties: false required: - name responses: "201": description: The agent has been created. content: application/json: schema: $ref: "#/components/schemas/Agent" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agent = await bb.agents.create({ name: "Job Finder", systemPrompt: "Use official company career pages.", }); console.log(agent); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agent = bb.agents.create( name="Job Finder", system_prompt="Use official company career pages.", ) print(agent) - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/agents \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{ "name": "Job Finder", "systemPrompt": "Use official company career pages." }' get: operationId: Agents_list summary: List Agents description: List agents across your account. Supports filtering by creation time. parameters: - name: startAt in: query description: "Only return agents created on or after this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-19T00:00:00Z." required: false schema: type: string format: date-time - name: endAt in: query description: "Only return agents created on or before this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-20T00:00:00Z." required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return. required: false schema: type: integer default: 20 maximum: 1000 minimum: 1 - name: cursor in: query description: Pagination cursor. Pass the nextCursor from the previous response to fetch the next page. Omit to start from the first page. required: false schema: type: string responses: "200": description: The page of matching agents. content: application/json: schema: description: A page of agents. type: object properties: data: description: The page of matching agents. type: array items: $ref: "#/components/schemas/Agent" limit: description: The maximum number of results returned in this page. type: integer nextCursor: description: Cursor for the next page. Pass it back as `cursor` on the next request to continue paging. null when there are no more results. anyOf: - type: string nullable: true required: - data - limit - nextCursor x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agents = await bb.agents.list({ limit: 20 }); console.log(agents); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agents = bb.agents.list(limit=20) print(agents) - lang: bash label: cURL source: |- curl --request GET \ --url 'https://api.browserbase.com/v1/agents?limit=20' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" /v1/agents/runs: post: operationId: AgentRuns_create summary: Run an Agent description: "Run a browser agent to complete the `task` by using web search and browser tooling. Optionally pass `agentId` to run a [custom agent](/reference/api/create-an-agent) you've created." requestBody: required: true content: application/json: schema: type: object properties: agentId: description: "Optionally run a specific [custom agent](/reference/api/create-an-agent) you've created by ID. The run will use the agent's `systemPrompt` and `resultSchema` unless overridden." type: string task: description: A natural language description of the task the agent should accomplish. type: string minLength: 1 resultSchema: description: "An optional [JSON Schema](https://json-schema.org/specification) object. If provided, the agent will aim to return a `result` that conforms to this schema when the run completes. Overrides the referenced agent's default `resultSchema` for this run only." type: object additionalProperties: true properties: {} browserSettings: description: "Browser configuration for the agent's session. When omitted, runner defaults apply." type: object additionalProperties: false properties: context: type: object additionalProperties: false properties: id: description: The Context ID. type: string persist: description: Whether to persist the context after browsing. Defaults to false. type: boolean required: - id proxies: description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations." anyOf: - type: array items: anyOf: - $ref: "#/components/schemas/BrowserbaseProxyConfig" - $ref: "#/components/schemas/ExternalProxyConfig" - $ref: "#/components/schemas/NoneProxyConfig" - type: boolean verified: description: Set true to enable Browserbase Verified for the session. type: boolean variables: description: "Optional named variables the agent can reference as placeholders, i.e. `%variable%`. Each entry pairs a `value` the placeholder resolves to with an optional `description` that hints to the agent when it should be used. Values are not persisted." type: object additionalProperties: additionalProperties: false type: object properties: value: description: The value the placeholder resolves to when the agent uses it. type: string description: description: Optional hint to the agent describing what this variable represents and when to use it. type: string required: - value additionalProperties: false required: - task responses: "201": description: The agent run has been created in `pending` state. content: application/json: schema: $ref: "#/components/schemas/AgentRun" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const run = await bb.agents.runs.create({ agentId: "agent-id", task: "Find the pricing page on example.com.", }); console.log(run); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) run = bb.agents.runs.create( agent_id="agent-id", task="Find the pricing page on example.com.", ) print(run) - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/agents/runs \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{ "agentId": "agent-id", "task": "Find the pricing page on example.com." }' get: operationId: AgentRuns_list summary: List Runs description: "List runs across your account. Supports filtering by status, by the agent they reference, and by creation time." parameters: - name: status in: query description: |- Current status of the run. - `PENDING` - agent will run soon - `RUNNING` - agent is currently running - `COMPLETED` - agent has finished running - `FAILED` - agent has failed the run - `STOPPED` - run was stopped by the user - `TIMED_OUT` - run exceeded maximum time required: false schema: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - STOPPED - TIMED_OUT - name: agentId in: query description: Only return runs that reference this agent ID. required: false schema: type: string - name: startAt in: query description: "Only return runs created on or after this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-19T00:00:00Z." required: false schema: type: string format: date-time - name: endAt in: query description: "Only return runs created on or before this timestamp (inclusive). ISO 8601 / RFC 3339, e.g. 2026-01-20T00:00:00Z." required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return. required: false schema: type: integer default: 20 maximum: 1000 minimum: 1 - name: cursor in: query description: Pagination cursor. Pass the nextCursor from the previous response to fetch the next page. Omit to start from the first page. required: false schema: type: string responses: "200": description: The page of matching agent runs. content: application/json: schema: description: A page of agent runs. type: object properties: data: description: The page of matching agent runs. type: array items: $ref: "#/components/schemas/AgentRun" limit: description: The maximum number of results returned in this page. type: integer nextCursor: description: Cursor for the next page. Pass it back as `cursor` on the next request to continue paging. null when there are no more results. anyOf: - type: string nullable: true required: - data - limit - nextCursor x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const runs = await bb.agents.runs.list({ status: "COMPLETED", limit: 20, }); console.log(runs); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) runs = bb.agents.runs.list(status="COMPLETED", limit=20) print(runs) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/runs \ --get \ --data-urlencode 'status=COMPLETED' \ --data-urlencode 'limit=20' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/runs/{runId}": get: operationId: AgentRuns_get summary: Get a Run description: "Retrieve the current status and details of a run, including its result and associated session information. To fetch the run's messages, use [List Run Messages](/reference/api/list-run-messages)." parameters: - name: runId in: path description: The run ID. required: true schema: type: string responses: "200": description: The agent run. content: application/json: schema: $ref: "#/components/schemas/AgentRun" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const run = await bb.agents.runs.retrieve("run-id"); console.log(run); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) run = bb.agents.runs.retrieve("run-id") print(run) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/runs/run-id \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/runs/{runId}/messages": get: operationId: AgentRuns_messages summary: List Run Messages description: |- Returns a paginated list of messages produced by a run, in chronological order, with the oldest messages first. Messages conform to the [AI SDK UIMessage format](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message). parameters: - name: since in: query description: "The `id` of the last message you've already received. The response will contain messages produced after that one, in chronological order. Omit on the first call. Pass the previous response's `nextSince` value to continue paging or to poll for new messages." required: false schema: type: string - name: limit in: query description: Maximum number of messages to return. required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: all in: query description: "Return every message after `since` in one response, ignoring `limit`." required: false schema: type: boolean default: false - name: runId in: path description: The run ID. required: true schema: type: string format: uuid responses: "200": description: "The page of messages, in chronological order, with the oldest messages first." content: application/json: schema: type: object properties: data: description: "The page of messages, in chronological order, with the oldest messages first." type: array items: type: object required: - id - createdAt - message properties: id: type: string createdAt: type: string format: date-time message: description: An AI SDK response message (assistant or tool). type: object additionalProperties: true properties: role: type: string enum: - assistant - tool content: description: Plain string (assistant text) or an array of typed parts. oneOf: - type: string - type: array items: type: object required: - type additionalProperties: true properties: type: description: text | reasoning | file | tool-call | tool-result type: string text: type: string toolCallId: type: string toolName: type: string input: {} output: {} mediaType: type: string data: type: string required: - role - content nextSince: description: "The `id` of the last message in `data`. Pass it back as `since` on the next request to continue paging, or to poll for new messages. `null` only when the run has no messages yet; in that case, omit `since` and retry." type: string nullable: true required: - data - nextSince x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const messages = await bb.agents.runs.listMessages("run-id", { limit: 20, }); console.log(messages); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) messages = bb.agents.runs.list_messages("run-id", limit=20) print(messages) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/runs/run-id/messages \ --get \ --data-urlencode 'limit=20' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/runs/{runId}/stop": post: operationId: AgentRuns_stop summary: Stop a Run description: Request that an in-progress run stop. The run winds down and transitions to `STOPPED`. Stopping a run that has already finished returns a conflict. parameters: - name: runId in: path description: The run ID. required: true schema: type: string responses: "202": description: The stop has been requested. Poll the run until its status is `STOPPED` to confirm it wound down. content: application/json: schema: $ref: "#/components/schemas/AgentRun" x-codeSamples: - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/agents/runs/run-id/stop \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/agents/{agentId}": get: operationId: Agents_get summary: Get an Agent description: Retrieve an agent by ID. parameters: - name: agentId in: path description: The agent ID. required: true schema: type: string responses: "200": description: The agent. content: application/json: schema: $ref: "#/components/schemas/Agent" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agent = await bb.agents.retrieve("agent-id"); console.log(agent); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agent = bb.agents.retrieve("agent-id") print(agent) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/agents/agent-id \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" patch: operationId: Agents_update summary: Update an Agent description: Update an existing agent. Only the fields provided in the body are modified; omitted fields are left unchanged. parameters: - name: agentId in: path description: The agent ID. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: description: Human-readable name for the agent. Used to identify the agent in the dashboard and API responses. type: string maxLength: 255 minLength: 1 systemPrompt: description: New system prompt that steers the agent's behavior on every run that uses this agent. type: string minLength: 1 resultSchema: description: "An optional [JSON Schema](https://json-schema.org/specification) object. If provided, runs that reference this agent will aim to return a `result` that conforms to this schema when they complete. Can be overridden per run by passing `resultSchema` on the run request." type: object additionalProperties: true properties: {} additionalProperties: false responses: "200": description: The updated agent. content: application/json: schema: $ref: "#/components/schemas/Agent" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const agent = await bb.agents.update("agent-id", { name: "Official Job Finder", }); console.log(agent); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) agent = bb.agents.update("agent-id", name="Official Job Finder") print(agent) - lang: bash label: cURL source: |- curl --request PATCH \ --url https://api.browserbase.com/v1/agents/agent-id \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{"name":"Official Job Finder"}' delete: operationId: Agents_delete summary: Delete an Agent description: Delete an agent. Runs that already referenced this agent are unaffected. parameters: - name: agentId in: path description: The agent ID. required: true schema: type: string responses: "204": description: "The agent has been deleted. Idempotent: deleting an already-deleted or non-existent agent returns 204." x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); await bb.agents.delete("agent-id"); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) bb.agents.delete("agent-id") - lang: bash label: cURL source: |- curl --request DELETE \ --url https://api.browserbase.com/v1/agents/agent-id \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" /v1/certificates: post: operationId: Certificates_upload summary: Upload a Certificate requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary required: - file responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Certificate" get: operationId: Certificates_list summary: List Certificates responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/Certificate" "/v1/certificates/{id}": get: operationId: Certificates_get summary: Get a Certificate parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Certificate" delete: operationId: Certificates_delete summary: Delete a Certificate parameters: - name: id in: path required: true schema: type: string responses: "204": description: "There is no content to send for this request, but the headers may be useful." /v1/contexts: post: operationId: Contexts_create summary: Create a Context requestBody: content: application/json: schema: type: object properties: projectId: description: "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." type: string name: description: "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." type: string maxLength: 128 minLength: 1 responses: "201": description: The request has succeeded and a new resource has been created as a result. content: application/json: schema: type: object properties: id: type: string publicKey: description: The public key to encrypt the user-data-directory. type: string cipherAlgorithm: description: The cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm. type: string initializationVectorSize: description: "The initialization vector size used to encrypt the user-data-directory. [Read more about how to use it](/features/contexts)." type: integer format: uint8 required: - id - publicKey - cipherAlgorithm - initializationVectorSize "/v1/contexts/{id}": get: operationId: Contexts_get summary: Get a Context parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Context" delete: operationId: Contexts_delete summary: Delete a Context parameters: - name: id in: path required: true schema: type: string responses: "204": description: "There is no content to send for this request, but the headers may be useful." /v1/downloads: get: operationId: Downloads_list summary: List Downloads description: List all downloads for a session with optional filtering and pagination. parameters: - name: sessionId in: query description: Filter downloads by session ID (required). required: true schema: type: string - name: filename in: query description: Filter by exact filename match. required: false schema: type: string maxLength: 255 - name: mimeType in: query description: Filter by MIME type. required: false schema: type: string maxLength: 255 - name: minSize in: query description: Minimum file size in bytes. required: false schema: type: number minimum: 0 - name: maxSize in: query description: Maximum file size in bytes. required: false schema: type: number minimum: 0 - name: createdAfter in: query description: Filter downloads created on or after this timestamp. required: false schema: type: string format: date-time - name: createdBefore in: query description: Filter downloads created on or before this timestamp. required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return. required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: offset in: query description: Number of results to skip for pagination. required: false schema: type: integer default: 0 minimum: 0 responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: downloads: type: array items: $ref: "#/components/schemas/Download" total: description: Total count of matching downloads. type: integer minimum: 0 limit: type: integer offset: type: integer required: - downloads - total - limit - offset "/v1/downloads/{id}": get: operationId: Downloads_get summary: Get a Download description: "Get download metadata (Accept: application/json) or file content (Accept: application/octet-stream)." parameters: - name: id in: path description: The download ID. required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Download" application/octet-stream: schema: type: string format: binary delete: operationId: Downloads_delete summary: Delete a Download description: Delete a download file from storage and mark as deleted. parameters: - name: id in: path description: The download ID to delete. required: true schema: type: string responses: "204": description: There is no content to send for this request. /v1/extensions: post: operationId: Extensions_upload summary: Upload an Extension requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary required: - file responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Extension" "/v1/extensions/{id}": get: operationId: Extensions_get summary: Get an Extension parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Extension" delete: operationId: Extensions_delete summary: Delete an Extension parameters: - name: id in: path required: true schema: type: string responses: "204": description: "There is no content to send for this request, but the headers may be useful." /v1/fetch: post: operationId: Fetch_create summary: Fetch a Page description: "Fetch a page and return its content, headers, and metadata." requestBody: required: true content: application/json: schema: type: object properties: url: description: The URL to fetch type: string format: uri allowRedirects: description: Whether to follow HTTP redirects type: boolean default: false allowInsecureSsl: description: Whether to bypass TLS certificate verification type: boolean default: false proxies: description: Whether to enable proxy support for the request type: boolean default: false format: description: Output format for the response content. `raw` (default) returns the response body unchanged; `json` returns structured data (requires `schema`); `markdown` returns the page as markdown. default: raw anyOf: - type: string enum: - raw - type: string enum: - json - type: string enum: - markdown schema: description: JSON Schema describing the desired structure of the response. Only used when `format` is `json`. type: object additionalProperties: {} required: - url responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: id: description: Unique identifier for the fetch request type: string statusCode: description: HTTP status code of the fetched response type: integer headers: description: Response headers as key-value pairs type: object additionalProperties: type: string content: anyOf: - type: string - type: object additionalProperties: {} description: The response body content. A string for `raw` and `markdown` formats; a structured object for `json` format (the schema-extracted result). contentType: description: The MIME type of the response type: string encoding: description: The character encoding of the response type: string required: - id - statusCode - headers - content - contentType - encoding "400": description: "Invalid request body, or the requested `format` is not supported for the fetched response's content type." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message "402": description: Free plan quota exceeded for the requested format. content: application/json: schema: description: Free plan quota exceeded for the requested format. "403": description: Project is not enabled for the requested format. Only `raw` is available without enablement. content: application/json: schema: description: Project is not enabled for the requested format. Only `raw` is available without enablement. "429": description: Concurrent fetch request limit exceeded. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message "502": description: The fetched response was too large or TLS certificate verification failed. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message - id "503": description: The fetch service is temporarily unavailable. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message - id "504": description: The fetch request timed out. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string id: description: Unique identifier for the fetch request type: string required: - statusCode - error - message - id /v1/functions: get: operationId: Functions_list summary: List Functions parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Function" total: type: integer minimum: 0 required: - data - total /v1/functions/builds: get: operationId: FunctionBuilds_list summary: List Function Builds parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: status in: query required: false schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/FunctionBuild" total: type: integer minimum: 0 required: - data - total "/v1/functions/builds/{id}": get: operationId: FunctionBuilds_get summary: Get a Function Build parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/FunctionBuild" "/v1/functions/builds/{id}/logs": get: operationId: FunctionBuilds_getLogs summary: Get Function Build Logs parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: logs: type: array items: $ref: "#/components/schemas/FunctionBuildLog" total: type: integer minimum: 0 required: - logs - total "/v1/functions/invocations/{id}": get: operationId: Invocations_get summary: Get an Invocation parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: allOf: - $ref: "#/components/schemas/Invocation" - type: object properties: cause: type: object properties: code: type: string enum: - TIMED_OUT - INTERNAL_ERROR - WORKLOAD_ERROR message: type: string minLength: 1 required: - code "/v1/functions/invocations/{id}/logs": get: operationId: Invocations_getLogs summary: Get Invocation Logs parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: logs: type: array items: $ref: "#/components/schemas/InvocationLog" total: type: integer minimum: 0 required: - logs - total "/v1/functions/versions/{id}": get: operationId: FunctionVersions_get summary: Get a Function Version parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/FunctionVersion" "/v1/functions/versions/{id}/invocations": get: operationId: FunctionVersions_listInvocations summary: List Invocations for a Function Version parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: status in: query required: false schema: type: string - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: results: type: array items: $ref: "#/components/schemas/Invocation" total: type: integer minimum: 0 required: - results - total "/v1/functions/{id}": get: operationId: Functions_get summary: Get a Function parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Function" "/v1/functions/{id}/invoke": post: operationId: Functions_invoke summary: Invoke a Function parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: params: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} sessionCreateParams: type: object properties: extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string browserSettings: type: object properties: context: type: object properties: id: description: The Context ID. type: string persist: description: Whether or not to persist the context after browsing. Defaults to `false`. type: boolean required: - id extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string viewport: type: object properties: width: description: The width of the browser. type: integer height: description: The height of the browser. type: integer blockAds: description: Enable or disable ad blocking in the browser. Defaults to `false`. type: boolean solveCaptchas: description: Enable or disable captcha solving in the browser. Defaults to `true`. type: boolean recordSession: description: Enable or disable session recording. Defaults to `true`. type: boolean logSession: description: Enable or disable session logging. Defaults to `true`. type: boolean advancedStealth: description: "Advanced Browser Stealth Mode. Deprecated: use `verified` instead." type: boolean deprecated: true verified: description: Verified Browser Mode type: boolean captchaImageSelector: description: "Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string captchaInputSelector: description: "Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string os: description: "Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet" type: string enum: - windows - mac - linux - mobile - tablet size: description: "[NOT IN DOCS] Resource size of the browser." type: string default: small enum: - small - medium - large enableNativeSelectPolyfill: description: "[NOT IN DOCS] Enable native select polyfill. This gives support a break-glass option to disable the polyfill." type: boolean enablePdfViewer: description: "[NOT IN DOCS] Enable PDF viewer. This gives support a break-glass option to enable the viewer when users want to view PDFs in-browser." type: boolean extensions: description: "[NOT IN DOCS] List of pre-installed extension names and custom extension ids to enable on the browser" type: array items: type: string enum: - onepassword - browser-events default: [] allowedDomains: description: "An optional list of allowed domains for the session. If you pass one or more domains, Browserbase restricts top-level (main-frame) page navigations to the listed domains and their subdomains. For example, `example.com` also permits `www.example.com` and `a.b.example.com`, but not `notexample.com`. Matching is domain-based, not full-URL. An empty list (the default) disables the restriction entirely. Browserbase enforces only main-frame navigations; it does not block iframe/subframe loads or other in-page resource requests (images, scripts, XHR, etc.)." type: array items: type: string default: [] ignoreCertificateErrors: description: "Enable or disable ignoring of certificate errors in the browser. Defaults to `false`, so TLS certificate validation is enforced; set to `true` to ignore certificate errors (for example, to reach hosts with expired or self-signed certificates)." type: boolean proxies: description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations." anyOf: - type: array items: anyOf: - $ref: "#/components/schemas/BrowserbaseProxyConfig" - $ref: "#/components/schemas/ExternalProxyConfig" - $ref: "#/components/schemas/NoneProxyConfig" - type: boolean proxySettings: description: Supplementary proxy settings. Optional. type: object properties: caCertificates: description: The TLS certificate IDs to trust. Optional. type: array items: format: uuid type: string default: [] userMetadata: description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)." type: object additionalProperties: true properties: {} timeout: description: Duration in seconds after which the function invocation will automatically end. Defaults to 900 (15 minutes). type: integer default: 900 maximum: 900 minimum: 60 responses: "202": description: "The request has been accepted for processing, but processing has not yet completed." content: application/json: schema: $ref: "#/components/schemas/Invocation" "/v1/functions/{id}/versions": get: operationId: Functions_listVersions summary: List Function Versions parameters: - name: offset in: query required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: id in: path required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: results: type: array items: $ref: "#/components/schemas/FunctionVersion" total: type: integer minimum: 0 required: - results - total /v1/projects: get: operationId: Projects_list summary: List Projects responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/Project" "/v1/projects/{id}": get: operationId: Projects_get summary: Get a Project parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Project" "/v1/projects/{id}/usage": get: operationId: Projects_usage summary: Get Project Usage parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/ProjectUsage" /v1/search: post: operationId: Search_web summary: Web Search description: Perform a web search and return structured results. requestBody: required: true content: application/json: schema: type: object properties: query: description: The search query string type: string maxLength: 200 minLength: 1 numResults: description: Number of results to return (1-25) type: integer default: 10 maximum: 25 minimum: 1 required: - query responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: requestId: description: Unique identifier for the request type: string query: description: The search query that was executed type: string results: description: List of search results type: array items: type: object properties: id: description: Unique identifier for the result type: string url: description: The URL of the search result type: string title: description: The title of the search result type: string author: description: Author of the content if available type: string publishedDate: description: Publication date in ISO 8601 format type: string format: date-time image: description: Image URL if available type: string favicon: description: Favicon URL type: string required: - id - url - title required: - requestId - query - results /v1/sessions: get: operationId: Sessions_list summary: List Sessions parameters: - name: status in: query required: false schema: type: string enum: - PENDING - RUNNING - ERROR - TIMED_OUT - COMPLETED - name: q in: query description: "Query sessions by user metadata. See [Querying Sessions by User Metadata](/features/sessions#querying-sessions-by-user-metadata) for the schema of this query." required: false schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/Session" post: operationId: Sessions_create summary: Create a Session requestBody: content: application/json: schema: type: object properties: projectId: description: "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." type: string extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string browserSettings: type: object properties: context: type: object properties: id: description: The Context ID. type: string persist: description: Whether or not to persist the context after browsing. Defaults to `false`. type: boolean required: - id extensionId: description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)." type: string viewport: type: object properties: width: description: The width of the browser. type: integer height: description: The height of the browser. type: integer blockAds: description: Enable or disable ad blocking in the browser. Defaults to `false`. type: boolean solveCaptchas: description: Enable or disable captcha solving in the browser. Defaults to `true`. type: boolean recordSession: description: Enable or disable session recording. Defaults to `true`. type: boolean logSession: description: Enable or disable session logging. Defaults to `true`. type: boolean advancedStealth: description: "Advanced Browser Stealth Mode. Deprecated: use `verified` instead." type: boolean deprecated: true verified: description: Verified Browser Mode type: boolean captchaImageSelector: description: "Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string captchaInputSelector: description: "Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)" type: string os: description: "Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet" type: string enum: - windows - mac - linux - mobile - tablet allowedDomains: description: "An optional list of allowed domains for the session. If you pass one or more domains, Browserbase restricts top-level (main-frame) page navigations to the listed domains and their subdomains. For example, `example.com` also permits `www.example.com` and `a.b.example.com`, but not `notexample.com`. Matching is domain-based, not full-URL. An empty list (the default) disables the restriction entirely. Browserbase enforces only main-frame navigations; it does not block iframe/subframe loads or other in-page resource requests (images, scripts, XHR, etc.)." type: array items: type: string default: [] ignoreCertificateErrors: description: "Enable or disable ignoring of certificate errors in the browser. Defaults to `false`, so TLS certificate validation is enforced; set to `true` to ignore certificate errors (for example, to reach hosts with expired or self-signed certificates)." type: boolean timeout: description: "Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`. Minimum 60 seconds, maximum 21600 seconds (6 hours)." type: integer maximum: 21600 minimum: 60 x-stainless-param: api_timeout keepAlive: description: Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above. type: boolean proxies: description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations." anyOf: - type: array items: anyOf: - $ref: "#/components/schemas/BrowserbaseProxyConfig" - $ref: "#/components/schemas/ExternalProxyConfig" - $ref: "#/components/schemas/NoneProxyConfig" - type: boolean proxySettings: description: Supplementary proxy settings. Optional. type: object properties: caCertificates: description: The TLS certificate IDs to trust. Optional. type: array items: format: uuid type: string default: [] region: description: The region where the Session should run. type: string default: us-west-2 enum: - us-west-2 - us-east-1 - eu-central-1 - ap-southeast-1 userMetadata: description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)." type: object additionalProperties: true properties: {} responses: "201": description: The request has succeeded and a new resource has been created as a result. content: application/json: schema: allOf: - $ref: "#/components/schemas/Session" - type: object properties: connectUrl: description: WebSocket URL to connect to the Session. type: string format: uri seleniumRemoteUrl: description: HTTP URL to connect to the Session. type: string format: uri signingKey: description: Signing key to use when connecting to the Session via HTTP. type: string required: - connectUrl - seleniumRemoteUrl - signingKey x-codeSamples: - lang: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/sessions \ --header 'Content-Type: application/json' \ --header 'X-BB-API-Key: ' \ --data '{}' - lang: JavaScript source: |- fetch('https://api.browserbase.com/v1/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-BB-API-Key': '' }, body: JSON.stringify({}) }) - lang: Python source: |- import requests url = "https://api.browserbase.com/v1/sessions" payload = {} headers = { "X-BB-API-Key": "", "Content-Type": "application/json" } response = requests.request("POST", url, json=payload, headers=headers) print(response.text) - lang: PHP source: |- "https://api.browserbase.com/v1/sessions", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => "{}", CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "X-BB-API-Key: " ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.browserbase.com/v1/sessions\"\n\n\tpayload := strings.NewReader(\"{}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"X-BB-API-Key\", \"\")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: Java source: |- HttpResponse response = Unirest.post("https://api.browserbase.com/v1/sessions") .header("X-BB-API-Key", "") .header("Content-Type", "application/json") .body("{}") .asString(); "/v1/sessions/{id}": get: operationId: Sessions_get summary: Get a Session parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: allOf: - $ref: "#/components/schemas/Session" - type: object properties: connectUrl: description: WebSocket URL to connect to the Session. type: string format: uri seleniumRemoteUrl: description: HTTP URL to connect to the Session. type: string format: uri signingKey: description: Signing key to use when connecting to the Session via HTTP. type: string post: operationId: Sessions_update summary: Update a Session parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: status: description: Set to `REQUEST_RELEASE` to request that the session complete. Use before session's timeout to avoid additional charges. type: string enum: - REQUEST_RELEASE required: - status responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/Session" "/v1/sessions/{id}/debug": get: operationId: Sessions_getDebug summary: Session Live URLs parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: $ref: "#/components/schemas/SessionLiveUrls" "/v1/sessions/{id}/logs": get: operationId: Sessions_getLogs summary: Session Logs parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: array items: $ref: "#/components/schemas/SessionLog" "/v1/sessions/{id}/recording/downloads": post: operationId: Sessions_createRecordingDownloads summary: Create Session Recording Downloads description: "Requests one downloadable MP4 per recorded page of a session. Assembly runs asynchronously and every page returns as `PENDING`. Re-posting re-enqueues all pages and retries any that failed. Poll the GET endpoint for per-page status and, on standard (non-BYOS) projects, download URLs." parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid responses: "202": description: Downloads enqueued. Poll the GET endpoint for status. content: application/json: schema: type: object properties: downloads: type: array items: $ref: "#/components/schemas/RecordingDownload" required: - downloads "404": description: "The session was not found, or it has no recording." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "409": description: The session has not ended. Recording downloads are available only after a session completes. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "410": description: The session's recording has aged out of its retention window and can no longer be assembled. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "422": description: "Recording was disabled for this session (`recordSession: false`), so there is nothing to assemble." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "502": description: Failed to reach the recording service. Retry the request. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message get: operationId: Sessions_listRecordingDownloads summary: List Session Recording Downloads description: "Returns the per-page download status for a session, with a short-lived signed URL for each completed page on standard (non-BYOS) projects." parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: downloads: type: array items: $ref: "#/components/schemas/RecordingDownload" required: - downloads "404": description: "The session was not found, or it has no recording." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "409": description: The session has not ended. Recording downloads are available only after a session completes. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "410": description: The session's recording has aged out of its retention window and can no longer be assembled. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "422": description: "Recording was disabled for this session (`recordSession: false`), so there is nothing to download." content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "502": description: Failed to reach the recording service. Retry the request. content: application/json: schema: type: object properties: statusCode: description: HTTP status code type: integer error: description: HTTP error name type: string message: description: Human-readable error message type: string required: - statusCode - error - message "/v1/sessions/{id}/replays": get: operationId: Sessions_getReplay summary: Get Session Replay description: "Returns page metadata for a session replay, including timing information and the URL of each page's HLS playlist." parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: pages: type: array items: $ref: "#/components/schemas/ReplayPage" pageCount: type: integer required: - pages - pageCount "/v1/sessions/{id}/replays/{pageId}": get: operationId: Sessions_getReplayPage summary: Get Replay Page description: Returns an HLS VOD media playlist (.m3u8) for a specific page of a session replay. parameters: - name: id in: path description: Session ID required: true schema: type: string format: uuid - name: pageId in: path required: true schema: type: string maxLength: 3 pattern: ^\d+$ responses: "200": description: The request has succeeded. content: application/vnd.apple.mpegurl: schema: type: string "/v1/sessions/{id}/uploads": post: operationId: Sessions_uploadFile summary: Create Session Uploads parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary required: - file responses: "200": description: The request has succeeded. content: application/json: schema: type: object properties: message: type: string required: - message /v1/webhooks: post: operationId: Webhooks_create summary: Create a Webhook description: "Register an HTTPS endpoint to receive events for this project. The response includes the signing secret, which is shown only here and when the secret is rotated. Store it before discarding the response. An endpoint may only be registered once per project." requestBody: required: true content: application/json: schema: type: object properties: endpoint: description: HTTPS URL that event deliveries are POSTed to. Must be publicly reachable. type: string format: uri maxLength: 2048 pattern: "^https://[^/?#]+" eventTypes: description: Event types this webhook subscribes to. Unknown types are rejected. type: array items: type: string enum: - functions.builds.running - functions.builds.completed - functions.builds.failed - functions.invocations.pending - functions.invocations.running - functions.invocations.completed - functions.invocations.failed minItems: 1 uniqueItems: true additionalProperties: false required: - endpoint - eventTypes responses: "201": description: The webhook has been created. content: application/json: schema: description: "The created webhook, including its signing secret." allOf: - $ref: "#/components/schemas/Webhook" - type: object properties: secret: description: "HMAC-SHA256 signing secret, prefixed `whsec_`. Shown once here; store it now. Use it to verify the signature on every delivery." type: string required: - secret x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const webhook = await bb.webhooks.create({ endpoint: "https://example.com/browserbase/events", eventTypes: ["functions.invocations.completed"], }); console.log(webhook.secret); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) webhook = bb.webhooks.create( endpoint="https://example.com/browserbase/events", event_types=["functions.invocations.completed"], ) print(webhook.secret) - lang: bash label: cURL source: |- curl --request POST \ --url https://api.browserbase.com/v1/webhooks \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{ "endpoint": "https://example.com/browserbase/events", "eventTypes": ["functions.invocations.completed"] }' get: operationId: Webhooks_list summary: List Webhooks description: "List the project's webhooks, newest first. Signing secrets are not included. Page by passing the previous response's `nextCursor` as `cursor`; a null `nextCursor` means there are no further pages." parameters: - name: limit in: query description: Maximum number of results to return. required: false schema: type: integer default: 20 maximum: 100 minimum: 1 - name: cursor in: query description: Cursor from a previous response's `nextCursor`. Omit for the first page. required: false schema: type: string responses: "200": description: A page of webhooks. content: application/json: schema: description: A page of webhooks. Signing secrets are not included. type: object properties: data: description: "The page of webhooks, newest first." type: array items: $ref: "#/components/schemas/Webhook" limit: description: The maximum number of results returned in this page. type: integer nextCursor: description: Cursor for the next page. Pass it back as `cursor` to continue paging. null when there are no more results. anyOf: - type: string nullable: true required: - data - limit - nextCursor x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const { data } = await bb.webhooks.list(); console.log(data); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) page = bb.webhooks.list() print(page.data) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/webhooks \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/webhooks/{id}": get: operationId: Webhooks_get summary: Get a Webhook description: Retrieve a single webhook by ID. The signing secret is not included; it is only ever returned on create and rotate. parameters: - name: id in: path description: The webhook ID. required: true schema: type: string format: uuid responses: "200": description: The webhook. content: application/json: schema: $ref: "#/components/schemas/Webhook" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const webhook = await bb.webhooks.retrieve(""); console.log(webhook); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) webhook = bb.webhooks.retrieve("") print(webhook) - lang: bash label: cURL source: |- curl --request GET \ --url https://api.browserbase.com/v1/webhooks/ \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" patch: operationId: Webhooks_update summary: Update a Webhook description: "Update a webhook's endpoint URL, its subscribed event types, or both. Omitted fields are left unchanged. `eventTypes` replaces the existing subscription rather than adding to it. The signing secret is unaffected." parameters: - name: id in: path description: The webhook ID. required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: endpoint: description: HTTPS URL that event deliveries are POSTed to. Must be publicly reachable. type: string format: uri maxLength: 2048 pattern: "^https://[^/?#]+" eventTypes: description: Event types this webhook subscribes to. Unknown types are rejected. type: array items: type: string enum: - functions.builds.running - functions.builds.completed - functions.builds.failed - functions.invocations.pending - functions.invocations.running - functions.invocations.completed - functions.invocations.failed minItems: 1 uniqueItems: true additionalProperties: false minProperties: 1 responses: "200": description: The webhook after the update. content: application/json: schema: $ref: "#/components/schemas/Webhook" x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const webhook = await bb.webhooks.update("", { eventTypes: [ "functions.invocations.completed", "functions.invocations.failed", ], }); console.log(webhook); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) webhook = bb.webhooks.update( "", event_types=[ "functions.invocations.completed", "functions.invocations.failed", ], ) print(webhook) - lang: bash label: cURL source: |- curl --request PATCH \ --url https://api.browserbase.com/v1/webhooks/ \ --header 'Content-Type: application/json' \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \ --data '{ "eventTypes": [ "functions.invocations.completed", "functions.invocations.failed" ] }' delete: operationId: Webhooks_delete summary: Delete a Webhook description: Delete a webhook. Deliveries stop immediately and the signing secret is retired. Events that occurred before the delete are not replayed if the endpoint is registered again. parameters: - name: id in: path description: The webhook ID. required: true schema: type: string format: uuid responses: "204": description: The webhook has been deleted. x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); await bb.webhooks.delete(""); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) bb.webhooks.delete("") - lang: bash label: cURL source: |- curl --request DELETE \ --url https://api.browserbase.com/v1/webhooks/ \ --header "X-BB-API-Key: $BROWSERBASE_API_KEY" "/v1/webhooks/{id}/secret": post: operationId: Webhooks_rotateSecret summary: Rotate a Webhook signing secret description: Issue a new signing secret for a webhook. By default the previous secret keeps verifying for 24 hours so a receiver can be updated without dropping deliveries; pass `revokeImmediately` to end that window at once. The new secret is returned only here. parameters: - name: id in: path description: The webhook ID. required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: revokeImmediately: description: Expire the old secret at once instead of honouring it for 24 hours. Use when responding to a leak; deliveries signed with the old secret stop verifying immediately. type: boolean default: false additionalProperties: false responses: "200": description: The new signing secret. content: application/json: schema: description: The new signing secret. Shown once; store it now. type: object properties: secret: description: "The new signing secret, prefixed `whsec_`." type: string required: - secret "429": description: "Too many previous secrets are still inside their grace window. Wait for one to expire, or retry with `revokeImmediately`." content: application/json: schema: description: "Too many previous secrets are still inside their grace window. Wait for one to expire, or retry with `revokeImmediately`." x-codeSamples: - lang: javascript label: Node.js source: |- import Browserbase from "@browserbasehq/sdk"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); const { secret } = await bb.webhooks.rotateSecret(""); console.log(secret); - lang: python label: Python source: |- import os from browserbase import Browserbase bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"]) rotated = bb.webhooks.rotate_secret("") print(rotated.secret) - lang: bash label: cURL source: 'curl --request POST https://api.browserbase.com/v1/webhooks//secret --header "X-BB-API-Key: $BROWSERBASE_API_KEY"' components: schemas: Agent: description: A reusable agent. Referenced by `agentId` to apply a system prompt to every run that uses the agent. type: object properties: agentId: description: Unique identifier for the agent. Use this value as `agentId` when creating an agent run. type: string name: description: Human-readable name for the agent. Used to identify the agent in the dashboard and API responses. type: string systemPrompt: description: System prompt applied to every run that uses this agent. type: string resultSchema: description: "[JSON Schema](https://json-schema.org/specification) that runs referencing this agent will aim to conform their `result` to. Can be overridden per run by passing `resultSchema` on the run request." type: object additionalProperties: true properties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - agentId - name - createdAt - updatedAt AgentRun: description: One execution of an agent against a task. Created in `pending` and transitioned through `running` → `completed`/`failed` by the runner. type: object properties: runId: description: Unique identifier for the run. type: string agentId: description: "The ID of the agent applied to this run, if any. Omitted for ad-hoc runs." type: string task: description: The original task description. type: string status: description: |- Current status of the run. - `PENDING` - agent will run soon - `RUNNING` - agent is currently running - `COMPLETED` - agent has finished running - `FAILED` - agent has failed the run - `STOPPED` - run was stopped by the user - `TIMED_OUT` - run exceeded maximum time type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - STOPPED - TIMED_OUT sessionId: description: The Browserbase session ID powering this run. type: string sandboxId: description: External sandbox identifier assigned by the runner. Optional. type: string resultSchema: description: "Per-run [JSON Schema](https://json-schema.org/specification) override for the result shape. When unset, the agent's default `resultSchema` applies." type: object additionalProperties: true properties: {} result: description: "The agent's structured result for the run. Only present when the run has finished and output is available. The result conforms to the provided [JSON Schema](https://json-schema.org/specification) when one is set." type: object additionalProperties: true properties: {} cause: type: object properties: code: description: "Structured failure code (e.g., RUNNER_HEARTBEAT_LOST)." type: string maxLength: 64 message: description: Human-readable failure detail. type: string maxLength: 500 required: - code startedAt: type: string format: date-time endedAt: type: string format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - runId - task - status - createdAt - updatedAt BrowserbaseProxyConfig: type: object properties: type: description: Type of proxy. Always use 'browserbase' for the Browserbase managed proxy network. type: string enum: - browserbase geolocation: description: Geographic location for the proxy. Optional. type: object properties: city: description: Name of the city. Use spaces for multi-word city names. Optional. type: string state: description: US state code (2 characters). Must also specify US as the country. Optional. type: string maxLength: 2 minLength: 2 pattern: "^[A-Za-z]{2}$" country: description: Country code in ISO 3166-1 alpha-2 format type: string maxLength: 2 minLength: 2 pattern: "^[A-Za-z]{2}$" required: - country domainPattern: description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional." type: string required: - type Certificate: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the uploaded Certificate. type: string required: - id - createdAt - updatedAt - projectId Context: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the uploaded Context. type: string name: description: "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." type: string maxLength: 128 minLength: 1 required: - id - createdAt - updatedAt - projectId Download: type: object properties: id: description: Unique identifier for the download. type: string sessionId: description: The Session ID this download belongs to. type: string filename: description: The filename of the downloaded file. type: string mimeType: description: The MIME type of the file. type: string size: description: File size in bytes. type: number checksum: description: SHA256 checksum of the file. type: string createdAt: description: Timestamp when the file was downloaded. type: string format: date-time required: - id - sessionId - filename - mimeType - size - checksum - createdAt Extension: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time fileName: type: string minLength: 1 projectId: description: The Project ID linked to the uploaded Extension. type: string required: - id - createdAt - updatedAt - fileName - projectId ExternalProxyConfig: type: object properties: type: description: Type of proxy. Always 'external' for this config. type: string enum: - external server: description: Server URL for external proxy. Required. type: string domainPattern: description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional." type: string username: description: Username for external proxy authentication. Optional. type: string password: description: Password for external proxy authentication. Optional. type: string required: - type - server Function: type: object properties: id: type: string format: uuid projectId: type: string format: uuid name: type: string minLength: 1 createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - projectId - name - createdAt - updatedAt FunctionBuild: type: object properties: id: type: string format: uuid projectId: type: string format: uuid request: type: object properties: entrypoint: type: string minLength: 1 functionNames: type: array items: minLength: 1 type: string required: - entrypoint status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED createdAt: type: string format: date-time updatedAt: type: string format: date-time startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time builtFunctions: type: array items: allOf: - $ref: "#/components/schemas/Function" - type: object properties: createdVersion: $ref: "#/components/schemas/FunctionVersion" required: - createdVersion cause: type: object properties: code: type: string enum: - NO_MANIFESTS_FOUND - TOO_MANY_MANIFESTS - MANIFEST_TOO_LARGE - INVALID_SESSION_CREATE_PARAMS - TIMED_OUT message: type: string minLength: 1 required: - code required: - id - projectId - request - status - createdAt - updatedAt - startedAt - expiresAt FunctionBuildLog: type: object properties: message: type: string timestamp: type: number required: - message - timestamp FunctionVersion: type: object properties: id: type: string format: uuid projectId: type: string format: uuid functionId: type: string format: uuid functionBuildId: type: string format: uuid sessionCreateParams: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} userParamsSchema: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - projectId - functionId - functionBuildId - createdAt - updatedAt Invocation: type: object properties: id: type: string format: uuid projectId: type: string format: uuid functionId: type: string format: uuid versionId: type: string format: uuid sessionId: type: string format: uuid region: type: string minLength: 1 params: description: JSON object that can be stored in a JSONB column type: object additionalProperties: true properties: {} status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED results: description: Any JSON-serializable value that can be stored in a JSONB column anyOf: - type: string - type: number - type: boolean - type: array items: {} - additionalProperties: true type: object properties: {} nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time required: - id - projectId - functionId - versionId - sessionId - status - createdAt - updatedAt - startedAt - expiresAt InvocationLog: type: object properties: message: type: string timestamp: type: number required: - message - timestamp NoneProxyConfig: type: object properties: type: description: Type of proxy. Always 'none' for this config. type: string enum: - none domainPattern: description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional." type: string required: - type Project: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time name: type: string minLength: 1 ownerId: type: string defaultTimeout: type: integer maximum: 21600 minimum: 60 concurrency: description: The maximum number of sessions that this project can run concurrently. type: integer minimum: 1 required: - id - createdAt - updatedAt - name - ownerId - defaultTimeout - concurrency ProjectUsage: type: object properties: browserMinutes: type: integer minimum: 0 proxyBytes: type: integer minimum: 0 required: - browserMinutes - proxyBytes RecordingDownload: type: object properties: pageId: description: 'Recorded page (tab) within the session, e.g. "0", "1".' type: string status: $ref: "#/components/schemas/RecordingDownloadStatus" downloadUrl: description: "Short-lived signed CDN URL, re-minted each GET. Present only when COMPLETED on a standard (non-BYOS) project." type: string completedAt: description: When the MP4 was created. Present only when COMPLETED on a standard (non-BYOS) project. type: string format: date-time required: - pageId - status RecordingDownloadStatus: description: "Per-page MP4 assembly state. `NOT_REQUESTED`: no download has been requested for the session yet. `PENDING`: assembly is enqueued or in progress. `COMPLETED`: the MP4 is ready. `FAILED`: assembly failed; POST again to retry." type: string enum: - NOT_REQUESTED - PENDING - COMPLETED - FAILED ReplayPage: type: object properties: pageId: type: string url: type: string startTimeMs: type: integer endTimeMs: type: integer required: - pageId - url - startTimeMs - endTimeMs Session: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: description: The Project ID linked to the Session. type: string startedAt: type: string format: date-time endedAt: type: string format: date-time expiresAt: type: string format: date-time status: type: string enum: - PENDING - RUNNING - ERROR - TIMED_OUT - COMPLETED proxyBytes: description: "Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)" type: integer keepAlive: description: Indicates if the Session was created to be kept alive upon disconnections type: boolean contextId: description: Optional. The Context linked to the Session. type: string region: description: The region where the Session is running. type: string enum: - us-west-2 - us-east-1 - eu-central-1 - ap-southeast-1 userMetadata: description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)." type: object additionalProperties: true properties: {} required: - id - createdAt - updatedAt - projectId - status - proxyBytes - keepAlive - region - startedAt - expiresAt SessionLiveUrls: type: object properties: debuggerFullscreenUrl: type: string format: uri debuggerUrl: type: string format: uri pages: type: array items: type: object properties: id: type: string url: type: string format: uri faviconUrl: type: string format: uri title: type: string debuggerUrl: type: string format: uri debuggerFullscreenUrl: type: string format: uri required: - id - url - faviconUrl - title - debuggerUrl - debuggerFullscreenUrl wsUrl: type: string format: uri required: - debuggerFullscreenUrl - debuggerUrl - pages - wsUrl SessionLog: type: object properties: method: type: string pageId: type: integer sessionId: type: string request: type: object properties: timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer params: type: object additionalProperties: true properties: {} rawBody: type: string required: - params - rawBody response: type: object properties: timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer result: type: object additionalProperties: true properties: {} rawBody: type: string required: - result - rawBody timestamp: description: milliseconds that have elapsed since the UNIX epoch type: integer frameId: type: string loaderId: type: string required: - method - pageId - sessionId Webhook: description: A delivery endpoint for a project. Browserbase POSTs a signed event to it whenever one of its subscribed event types occurs. The signing secret is returned only when it is created or rotated. type: object properties: id: description: Unique identifier for the webhook. type: string projectId: description: The project the webhook belongs to. type: string endpoint: description: HTTPS URL that event deliveries are POSTed to. Must be publicly reachable. type: string format: uri maxLength: 2048 pattern: "^https://[^/?#]+" eventTypes: description: Event types this webhook subscribes to. Unknown types are rejected. type: array items: type: string enum: - functions.builds.running - functions.builds.completed - functions.builds.failed - functions.invocations.pending - functions.invocations.running - functions.invocations.completed - functions.invocations.failed minItems: 1 uniqueItems: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - projectId - endpoint - eventTypes - createdAt - updatedAt securitySchemes: BrowserbaseAuth: type: apiKey in: header name: X-BB-API-Key description: "Your [Browserbase API Key](https://www.browserbase.com/settings)." tags: [] security: - BrowserbaseAuth: []