openapi: 3.1.0
info:
title: Kernel API Keys Browsers API
description: Developer tools and cloud infrastructure for AI agents to use web browsers
version: 0.1.0
servers:
- url: https://api.onkernel.com
description: API Server
security:
- bearerAuth: []
tags:
- name: Browsers
description: Create and manage browser sessions.
paths:
/browsers:
post:
operationId: postBrowsers
tags:
- Browsers
summary: Create a browser session
description: Create a new browser session from within an action.
security:
- bearerAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Browser'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
'529':
$ref: '#/components/responses/CapacityExhausted'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst browser = await client.browsers.create();\n\nconsole.log(browser.session_id);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nbrowser = client.browsers.create()\nprint(browser.session_id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.New(context.TODO(), kernel.BrowserNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n"
get:
operationId: getBrowsers
tags:
- Browsers
summary: List browser sessions
description: List all browser sessions with pagination support. Use status parameter to filter by session state.
security:
- bearerAuth: []
parameters:
- name: status
in: query
required: false
description: Filter sessions by status. "active" returns only active sessions (default), "deleted" returns only soft-deleted sessions, "all" returns both.
schema:
type: string
enum:
- active
- deleted
- all
default: active
- name: include_deleted
in: query
required: false
deprecated: true
description: 'Deprecated: Use status=all instead. When true, includes soft-deleted browser sessions in the results alongside active sessions.'
schema:
type: boolean
default: false
- name: limit
in: query
required: false
description: Maximum number of results to return. Defaults to 20, maximum 100.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
required: false
description: Number of results to skip. Defaults to 0.
schema:
type: integer
minimum: 0
default: 0
- name: query
in: query
required: false
description: Search browsers by name, session ID, profile ID, proxy ID, or pool name.
schema:
type: string
- name: tags
in: query
required: false
style: deepObject
explode: true
description: 'Filter sessions by tag key-value pairs using deepObject style, e.g. ?tags[team]=backend&tags[env]=staging. Multiple pairs are ANDed: a session must match every supplied pair exactly.
'
schema:
type: object
additionalProperties:
type: string
responses:
'200':
description: List of browsers
headers:
X-Limit:
description: The limit used for pagination
schema:
type: integer
X-Offset:
description: The offset used for pagination
schema:
type: integer
X-Has-More:
description: Whether more results are available
schema:
type: boolean
X-Next-Offset:
description: The offset where the next page starts. 0 when there are no more results.
schema:
type: integer
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Browser'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const browserListResponse of client.browsers.list()) {\n console.log(browserListResponse.session_id);\n}"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\npage = client.browsers.list()\npage = page.items[0]\nprint(page.session_id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Browsers.List(context.TODO(), kernel.BrowserListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
/browsers/{id_or_name}:
get:
operationId: getBrowsersByIdOrName
tags:
- Browsers
summary: Get browser session details
description: Get information about a browser session.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser session ID or name
example: htzv5orfit78e1m2biiifpbv
- name: include_deleted
in: query
required: false
description: When true, includes soft-deleted browser sessions in the lookup.
schema:
type: boolean
default: false
responses:
'200':
description: Browser session retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Browser'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst browser = await client.browsers.retrieve('htzv5orfit78e1m2biiifpbv');\n\nconsole.log(browser.session_id);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nbrowser = client.browsers.retrieve(\n id_or_name=\"htzv5orfit78e1m2biiifpbv\",\n)\nprint(browser.session_id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.Get(\n\t\tcontext.TODO(),\n\t\t\"htzv5orfit78e1m2biiifpbv\",\n\t\tkernel.BrowserGetParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n"
patch:
operationId: patchBrowsersByIdOrName
tags:
- Browsers
summary: Update browser session
description: Update a browser session.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser session ID or name
example: htzv5orfit78e1m2biiifpbv
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserUpdateRequest'
responses:
'200':
description: Browser session updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Browser'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst browser = await client.browsers.update('htzv5orfit78e1m2biiifpbv');\n\nconsole.log(browser.session_id);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nbrowser = client.browsers.update(\n id_or_name=\"htzv5orfit78e1m2biiifpbv\",\n)\nprint(browser.session_id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.Update(\n\t\tcontext.TODO(),\n\t\t\"htzv5orfit78e1m2biiifpbv\",\n\t\tkernel.BrowserUpdateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n"
delete:
operationId: deleteBrowsersByIdOrName
tags:
- Browsers
summary: Delete a browser session by ID or name.
description: Delete a browser session by ID or name
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser session ID or name
example: htzv5orfit78e1m2biiifpbv
responses:
'204':
description: Browser session deleted successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.browsers.deleteByID('htzv5orfit78e1m2biiifpbv');"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nclient.browsers.delete_by_id(\n \"htzv5orfit78e1m2biiifpbv\",\n)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Browsers.DeleteByID(context.TODO(), \"htzv5orfit78e1m2biiifpbv\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
/browsers/{id}/extensions:
post:
operationId: uploadExtensionsToBrowser
tags:
- Browsers
summary: Ad-hoc upload one or more unpacked extensions to a running browser instance.
description: Loads one or more unpacked extensions and restarts Chromium on the browser instance.
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
extensions:
type: array
description: List of extensions to upload and activate
items:
type: object
properties:
zip_file:
type: string
format: binary
description: Zip archive containing an unpacked Chromium extension (must include manifest.json)
name:
type: string
description: Folder name to place the extension under /home/kernel/extensions/<name>
minLength: 1
maxLength: 255
pattern: ^[a-zA-Z0-9._-]{1,255}$
required:
- zip_file
- name
required:
- extensions
responses:
'201':
description: Extensions uploaded, Chromium restarted, and DevTools is ready
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.browsers.loadExtensions('id', {\n extensions: [{ name: 'name', zip_file: fs.createReadStream('path/to/file') }],\n});"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nclient.browsers.load_extensions(\n id=\"id\",\n extensions=[{\n \"name\": \"name\",\n \"zip_file\": b\"Example data\",\n }],\n)"
- lang: Go
source: "package main\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"io\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Browsers.LoadExtensions(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserLoadExtensionsParams{\n\t\t\tExtensions: []kernel.BrowserLoadExtensionsParamsExtension{{\n\t\t\t\tName: \"name\",\n\t\t\t\tZipFile: io.Reader(bytes.NewBuffer([]byte(\"Example data\"))),\n\t\t\t}},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
/browsers/{id}/curl:
post:
summary: Make an HTTP request through the browser's network stack
description: 'Sends an HTTP request through Chrome''s HTTP request stack, inheriting
the browser''s TLS fingerprint, cookies, proxy configuration, and headers.
Returns a structured JSON response with status, headers, body, and timing.
'
operationId: browserCurl
tags:
- Browsers
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserCurlRequest'
responses:
'200':
description: Response from target URL
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserCurlResult'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
'502':
description: Upstream transport failure
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserCurlTransportError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.curl('id', { url: 'url' });\n\nconsole.log(response.body);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.curl(\n id=\"id\",\n url=\"url\",\n)\nprint(response.body)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Curl(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserCurlParams{\n\t\t\tURL: \"url\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Body)\n}\n"
components:
schemas:
BrowserTelemetryCategoriesConfig:
type: object
description: 'Per-category telemetry capture settings layered onto the default set. The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.'
properties:
console:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Console output (log, warn, error) and uncaught exceptions. CDP category; off by default.
page:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. CDP category; off by default.
interaction:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: User interaction events including clicks, keydowns, and scroll-settled events. CDP category; off by default.
network:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: HTTP request and response metadata including URL, method, status code, and timing. Request post data is forwarded as-is from CDP. Text response bodies are truncated at 8 KB for structured types (JSON, XML, form data) and 4 KB for other text types. Binary responses (images, fonts, media) are excluded. CDP category; off by default.
control:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Agent-driven actions against the browser, such as inbound calls to the in-VM API. On by default.
connection:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Client attach/detach lifecycle for the CDP proxy and live view. On by default.
system:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Browser VM health, such as out-of-memory kills and managed-service crashes. On by default.
screenshot:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Periodic base64-encoded viewport screenshots. High volume; off by default and must be opted into.
captcha:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Captcha solve attempt outcomes. On by default.
BrowserViewportUpdate:
description: Viewport configuration for updating a browser session. Extends BrowserViewport with update-only options.
allOf:
- $ref: '#/components/schemas/BrowserViewport'
- type: object
properties:
force:
type: boolean
default: false
description: 'If true, allow the viewport change even when a live view or recording/replay is active.
Active recordings will be gracefully stopped and restarted at the new resolution as
separate segments. If false (default), the resize is refused when a live view or recording is active.
'
BrowserTelemetryRequestConfig:
type: object
description: Telemetry request configuration for a browser session.
properties:
enabled:
type: boolean
description: Request shortcut for browser telemetry capture. True enables capture; with no browser category settings it captures the default set (control, connection, system, captcha), and any browser category settings are layered onto that default set. On update, enabled=true resolves the config fresh from the default set plus any provided categories, replacing the session's current selection rather than merging onto it; omit enabled to merge categories onto the current selection instead. False stops capture on update and starts no capture on create. enabled=false cannot be combined with browser category settings.
browser:
$ref: '#/components/schemas/BrowserTelemetryCategoriesConfig'
description: Per-category capture flags. The operational categories (control, connection, system, captcha) are captured whenever telemetry is enabled; set one to enabled=false to opt out. The CDP categories (console, network, page, interaction) and screenshot are off by default; set enabled=true to opt in. On create, provided categories layer onto the default set. On update, provided categories merge onto the session's current config; when no telemetry is active this falls back to the default set (matching create). If browser is omitted or empty, the default set is used. A browser config that disables every category stops capture on update and starts no capture on create.
Browser:
type: object
properties:
created_at:
type: string
format: date-time
description: When the browser session was created.
cdp_ws_url:
type: string
description: Websocket URL for Chrome DevTools Protocol connections to the browser session
example: wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi...
webdriver_ws_url:
type: string
description: Websocket URL for WebDriver BiDi connections to the browser session
example: wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi...
browser_live_view_url:
type: string
description: Remote URL for live viewing the browser session. Only available for non-headless browsers.
example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi...
base_url:
type: string
description: Metro-API HTTP base URL for this browser session.
example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel
headless:
type: boolean
description: Whether the browser session is running in headless mode.
example: false
stealth:
type: boolean
description: Whether the browser session is running in stealth mode.
example: false
gpu:
type: boolean
description: Whether GPU acceleration is enabled for the browser session (only supported for headful sessions).
example: false
session_id:
type: string
description: Unique identifier for the browser session
example: htzv5orfit78e1m2biiifpbv
name:
type: string
description: Human-readable name of the browser session, if one was set at creation.
example: checkout-flow-1
timeout_seconds:
type: integer
description: The number of seconds of inactivity before the browser session is terminated.
profile:
$ref: '#/components/schemas/Profile'
proxy_id:
type: string
description: ID of the proxy associated with this browser session, if any.
pool:
$ref: '#/components/schemas/BrowserPoolRef'
viewport:
$ref: '#/components/schemas/BrowserViewport'
kiosk_mode:
type: boolean
description: Whether the browser session is running in kiosk mode.
example: false
start_url:
type: string
description: URL the session was asked to navigate to on creation, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded.
example: https://example.com
chrome_policy:
type: object
additionalProperties: true
description: 'Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names.
'
tags:
$ref: '#/components/schemas/Tags'
description: User-defined key-value tags that were set on this browser session, if any. Echoed back when present.
deleted_at:
type: string
format: date-time
description: When the browser session was soft-deleted. Only present for deleted sessions.
usage:
$ref: '#/components/schemas/BrowserUsage'
telemetry:
$ref: '#/components/schemas/BrowserTelemetryConfig'
nullable: true
description: Active telemetry configuration for the session, if any.
required:
- created_at
- cdp_ws_url
- webdriver_ws_url
- session_id
- stealth
- headless
- timeout_seconds
BrowserUpdateRequest:
type: object
description: Request body for updating a browser session.
properties:
name:
type: string
nullable: true
description: 'Human-readable name for the browser session. Omit to leave unchanged, set to an empty string to clear the name. When set, must be unique among active sessions within the project.
'
minLength: 1
maxLength: 255
pattern: ^[a-zA-Z0-9._-]{1,255}$
example: checkout-flow-1
tags:
$ref: '#/components/schemas/Tags'
nullable: true
description: 'User-defined key-value tags for the browser session. Omit to leave unchanged. Provide a map to replace the entire tag set (full replace, not a merge). Set to an empty object ({}) to clear all tags. Up to 50 pairs.
'
proxy_id:
type: string
nullable: true
description: ID of the proxy to use. Omit to leave unchanged, set to empty string to remove proxy.
disable_default_proxy:
type: boolean
description: If true, stealth browsers connect directly instead of using the default stealth proxy.
profile:
$ref: '#/components/schemas/BrowserProfile'
description: Profile to load into the browser session. Only allowed if the session does not already have a profile loaded.
viewport:
$ref: '#/components/schemas/BrowserViewportUpdate'
description: Viewport configuration to apply to the browser session.
telemetry:
$ref: '#/components/schemas/BrowserTelemetryRequestConfig'
nullable: true
description: 'Telemetry configuration. Omit, set to null, or set to an empty object ({}) to leave the existing configuration unchanged. Set enabled to true to enable capture using VM defaults. Set enabled to false to stop capture. Provide browser category settings for per-category updates. Explicitly disabling all four categories also stops capture.
'
BrowserCurlTransportError:
type: object
description: Transport-level error when the request could not complete.
required:
- message
properties:
message:
type: string
description: Human-readable error description.
net_error:
type: integer
description: Chromium net error code.
net_error_name:
type: string
description: Chromium net error name.
additionalProperties: false
BrowserRequest:
type: object
description: 'Parameters for creating a browser session.
'
properties:
invocation_id:
type: string
description: action invocation ID
example: rr33xuugxj9h0bkf1rdt2bet
name:
type: string
description: 'Optional human-readable name for the browser session, used to find it later in the dashboard. Must be unique among active sessions within the project. Can be changed later via PATCH /browsers/{id_or_name}.
'
minLength: 1
maxLength: 255
pattern: ^[a-zA-Z0-9._-]{1,255}$
example: checkout-flow-1
tags:
$ref: '#/components/schemas/Tags'
description: 'Optional user-defined key-value tags for the browser session, used to find and group sessions later. Can be changed later via PATCH /browsers/{id_or_name}. Up to 50 pairs.
'
stealth:
type: boolean
description: If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms.
example: true
headless:
type: boolean
description: If true, launches the browser using a headless image (no VNC/GUI). Defaults to false.
example: false
gpu:
type: boolean
description: If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan and headless=false.
example: false
timeout_seconds:
type: integer
description: The number of seconds of inactivity before the browser session is terminated. Activity includes CDP connections and live view connections. Defaults to 60 seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We check for inactivity every 5 seconds, so the actual timeout behavior you will see is +/- 5 seconds around the specified value.
minimum: 10
maximum: 259200
profile:
$ref: '#/components/schemas/BrowserProfile'
extensions:
type: array
description: List of browser extensions to load into the session. Provide each by id or name.
maxItems: 20
items:
$ref: '#/components/schemas/BrowserExtension'
proxy_id:
type: string
description: Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session.
viewport:
$ref: '#/components/schemas/BrowserViewport'
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kernel/refs/heads/main/openapi/kernel-browsers-api-openapi.yml