Kernel Browser Pools API
Create and manage browser pools for acquiring and releasing browsers.
OpenAPI Specification
openapi: 3.1.0
info:
title: Kernel API Keys Browser Pools 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: Browser Pools
description: Create and manage browser pools for acquiring and releasing browsers.
paths:
/browser_pools:
post:
operationId: postBrowserPools
tags:
- Browser Pools
summary: Create a browser pool
description: Create a new browser pool with the specified configuration and size.
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPoolRequest'
responses:
'201':
description: Browser pool created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPool'
'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'
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 browserPool = await client.browserPools.create({ size: 10 });\n\nconsole.log(browserPool.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_pool = client.browser_pools.create(\n size=10,\n)\nprint(browser_pool.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\tbrowserPool, err := client.BrowserPools.New(context.TODO(), kernel.BrowserPoolNewParams{\n\t\tSize: 10,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browserPool.ID)\n}\n"
get:
operationId: getBrowserPools
tags:
- Browser Pools
summary: List browser pools
description: List browser pools owned by the caller's organization.
security:
- bearerAuth: []
responses:
'200':
description: List of browser pools
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BrowserPool'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'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 browserPools = await client.browserPools.list();\n\nconsole.log(browserPools);"
- 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_pools = client.browser_pools.list()\nprint(browser_pools)"
- 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\tbrowserPools, err := client.BrowserPools.List(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browserPools)\n}\n"
/browser_pools/{id_or_name}:
get:
operationId: getBrowserPoolsByIdOrName
tags:
- Browser Pools
summary: Get browser pool details
description: Retrieve details for a single browser pool by its ID or name.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser pool ID or name
responses:
'200':
description: Browser pool details
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPool'
'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\nconst browserPool = await client.browserPools.retrieve('id_or_name');\n\nconsole.log(browserPool.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_pool = client.browser_pools.retrieve(\n \"id_or_name\",\n)\nprint(browser_pool.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\tbrowserPool, err := client.BrowserPools.Get(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browserPool.ID)\n}\n"
patch:
operationId: updateBrowserPoolsByIdOrName
tags:
- Browser Pools
summary: Update a browser pool
description: Updates the configuration used to create browsers in the pool.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser pool ID or name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPoolUpdateRequest'
responses:
'200':
description: Browser pool details
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPool'
'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'
'429':
$ref: '#/components/responses/TooManyRequests'
'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 browserPool = await client.browserPools.update('id_or_name', { size: 10 });\n\nconsole.log(browserPool.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_pool = client.browser_pools.update(\n id_or_name=\"id_or_name\",\n size=10,\n)\nprint(browser_pool.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\tbrowserPool, err := client.BrowserPools.Update(\n\t\tcontext.TODO(),\n\t\t\"id_or_name\",\n\t\tkernel.BrowserPoolUpdateParams{\n\t\t\tSize: 10,\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browserPool.ID)\n}\n"
delete:
operationId: deleteBrowserPoolsByIdOrName
tags:
- Browser Pools
summary: Delete a browser pool
description: Delete a browser pool and all browsers in it. By default, deletion is blocked if browsers are currently leased. Use force=true to terminate leased browsers.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser pool ID or name
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPoolDeleteRequest'
responses:
'204':
description: Browser pool deleted successfully
'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.browserPools.delete('id_or_name');"
- 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.browser_pools.delete(\n id_or_name=\"id_or_name\",\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.BrowserPools.Delete(\n\t\tcontext.TODO(),\n\t\t\"id_or_name\",\n\t\tkernel.BrowserPoolDeleteParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
/browser_pools/{id_or_name}/acquire:
post:
operationId: acquireFromBrowserPoolByIdOrName
tags:
- Browser Pools
summary: Acquire a browser from the pool
description: 'Long-polling endpoint to acquire a browser from the pool. Returns immediately when a browser
is available, or returns 204 No Content when the poll times out. The client should retry
the request to continue waiting for a browser. The acquired browser will use the pool''s
timeout_seconds for its idle timeout.
'
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser pool ID or name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPoolAcquireRequest'
responses:
'200':
description: Browser acquired successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Browser'
'204':
description: Poll timed out, no browser available. Retry the request to continue waiting.
'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\nconst response = await client.browserPools.acquire('id_or_name');\n\nconsole.log(response.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)\nresponse = client.browser_pools.acquire(\n id_or_name=\"id_or_name\",\n)\nprint(response.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\tresponse, err := client.BrowserPools.Acquire(\n\t\tcontext.TODO(),\n\t\t\"id_or_name\",\n\t\tkernel.BrowserPoolAcquireParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.SessionID)\n}\n"
/browser_pools/{id_or_name}/release:
post:
operationId: releaseToBrowserPoolByIdOrName
tags:
- Browser Pools
summary: Release a browser back to the pool
description: Release a browser back to the pool, optionally recreating the browser instance.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser pool ID or name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BrowserPoolReleaseRequest'
responses:
'204':
description: Browser released successfully
'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.browserPools.release('id_or_name', { session_id: 'ts8iy3sg25ibheguyni2lg9t' });"
- 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.browser_pools.release(\n id_or_name=\"id_or_name\",\n session_id=\"ts8iy3sg25ibheguyni2lg9t\",\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.BrowserPools.Release(\n\t\tcontext.TODO(),\n\t\t\"id_or_name\",\n\t\tkernel.BrowserPoolReleaseParams{\n\t\t\tSessionID: \"ts8iy3sg25ibheguyni2lg9t\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
/browser_pools/{id_or_name}/flush:
post:
operationId: flushBrowserPoolByIdOrName
tags:
- Browser Pools
summary: Flush all idle browsers in the pool
description: Destroys all idle browsers in the pool; leased browsers are not affected.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Browser pool ID or name
responses:
'204':
description: Pool flushed successfully
'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.browserPools.flush('id_or_name');"
- 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.browser_pools.flush(\n \"id_or_name\",\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.BrowserPools.Flush(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
components:
schemas:
ErrorDetail:
type: object
properties:
code:
type: string
description: Lower-level error code providing more specific detail
example: invalid_input
message:
type: string
description: Further detail about the error
example: Provided version string is not semver compliant
BrowserTelemetryCategoryConfig:
type: object
description: Per-category telemetry configuration.
properties:
enabled:
type: boolean
description: Whether this category is captured. Defaults to true if omitted.
BrowserPoolRequest:
type: object
description: 'Parameters for creating a browser pool. All browsers in the pool will be created with the same configuration.
'
properties:
name:
type: string
pattern: ^[a-zA-Z0-9._-]{1,255}$
description: Optional name for the browser pool. Must be unique within the project.
example: my-pool
size:
type: integer
description: 'Number of browsers to maintain in the pool. The maximum size is determined by your
organization''s pooled sessions limit (the sum of all pool sizes cannot exceed your limit).
'
minimum: 1
example: 10
fill_rate_per_minute:
type: integer
description: Percentage of the pool to fill per minute. Defaults to 10%.
minimum: 0
maximum: 25
default: 10
timeout_seconds:
type: integer
description: Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds if not specified
minimum: 60
maximum: 86400
default: 600
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. Defaults to false.
example: false
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 belonging to the caller's org.
viewport:
$ref: '#/components/schemas/BrowserViewport'
kiosk_mode:
type: boolean
description: If true, launches the browser in kiosk mode to hide address bar and tabs in live view.
example: true
chrome_policy:
type: object
additionalProperties: true
description: 'Custom Chrome enterprise policy overrides applied to all browsers in this pool. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/
'
start_url:
type: string
description: 'Optional URL to navigate to when a new browser is warmed into the pool. Best-effort: failures to navigate do not fail pool fill. Only applied to newly-warmed browsers; browsers reused via release/acquire keep whatever URL the previous lease left them on. Accepts any URL Chromium can resolve, including chrome:// pages.'
example: https://example.com
required:
- size
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Application-specific error code (machine-readable)
example: bad_request
message:
type: string
description: Human-readable error description for debugging
example: 'Missing required field: app_name'
details:
type: array
description: Additional error details (for multiple errors)
items:
$ref: '#/components/schemas/ErrorDetail'
inner_error:
$ref: '#/components/schemas/ErrorDetail'
BrowserPool:
type: object
description: A browser pool containing multiple identically configured browsers.
properties:
id:
type: string
description: Unique identifier for the browser pool
example: iv25ujqf37x3j07dwoffegqr
name:
type: string
description: Browser pool name, if set
example: my-pool
available_count:
type: integer
description: Number of browsers currently available in the pool
example: 85
acquired_count:
type: integer
description: Number of browsers currently acquired from the pool
example: 15
created_at:
type: string
format: date-time
description: Timestamp when the browser pool was created
browser_pool_config:
$ref: '#/components/schemas/BrowserPoolRequest'
description: Configuration used to create all browsers in this pool
required:
- id
- available_count
- acquired_count
- created_at
- browser_pool_config
BrowserTelemetryConfig:
type: object
description: Telemetry configuration for a browser session.
properties:
browser:
$ref: '#/components/schemas/BrowserTelemetryCategoriesConfig'
description: Per-category enable/disable flags. If omitted, all categories are captured.
BrowserTelemetryCategoriesConfig:
type: object
description: Per-category telemetry capture settings.
properties:
console:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Console output (log, warn, error) and uncaught exceptions.
page:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP.
interaction:
$ref: '#/components/schemas/BrowserTelemetryCategoryConfig'
description: User interaction events including clicks, keydowns, and scroll-settled events.
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.
BrowserPoolReleaseRequest:
type: object
description: Request body for releasing a browser back to the pool.
properties:
session_id:
type: string
description: Browser session ID to release back to the pool
example: ts8iy3sg25ibheguyni2lg9t
reuse:
type: boolean
description: Whether to reuse the browser instance or destroy it and create a new one. Defaults to true.
default: true
example: false
required:
- session_id
BrowserPoolAcquireRequest:
type: object
description: Request body for acquiring a browser from the pool.
properties:
acquire_timeout_seconds:
type: integer
description: Maximum number of seconds to wait for a browser to be available. Defaults to the calculated time it would take to fill the pool at the currently configured fill rate.
required: []
BrowserProfile:
type: object
description: 'Profile selection for the browser session. Provide either id or name. If specified, the
matching profile will be loaded into the browser session. Profiles must be created beforehand.
'
properties:
id:
type: string
description: Profile ID to load for this browser session
name:
type: string
minLength: 1
maxLength: 255
pattern: ^[a-zA-Z0-9._-]{1,255}$
description: Profile name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
save_changes:
type: boolean
description: If true, save changes made during the session back to the profile when the session ends.
default: false
oneOf:
- required:
- id
- required:
- name
BrowserPoolUpdateRequest:
type: object
description: 'Parameters for updating a browser pool. All browsers in the pool will be created with the same configuration.
'
allOf:
- $ref: '#/components/schemas/BrowserPoolRequest'
- type: object
properties:
discard_all_idle:
type: boolean
description: Whether to discard all idle browsers and rebuild the pool immediately. Defaults to false.
example: false
default: false
BrowserUsage:
type: object
description: Session usage metrics.
properties:
uptime_ms:
type: integer
description: Time in milliseconds the session was actively running.
required:
- uptime_ms
Profile:
type: object
description: Browser profile metadata.
properties:
id:
type: string
description: Unique identifier for the profile
name:
type: string
nullable: true
description: Optional, easier-to-reference name for the profile
created_at:
type: string
format: date-time
description: Timestamp when the profile was created
updated_at:
type: string
format: date-time
description: Timestamp when the profile was last updated
last_used_at:
type: string
format: date-time
description: Timestamp when the profile was last used
required:
- id
- created_at
BrowserPoolRef:
type: object
description: Browser pool this session was acquired from, if any.
properties:
id:
type: string
description: Browser pool ID
name:
type: string
description: Browser pool name, if set
required:
- id
BrowserPoolDeleteRequest:
type: object
description: 'Parameters for deleting a browser pool.
'
properties:
force:
type: boolean
default: false
description: If true, force delete even if browsers are currently leased. Leased browsers will be terminated.
required: []
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
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.
'
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
BrowserViewport:
type: object
description: 'Initial browser window size in pixels with optional refresh rate.
If omitted, image defaults apply (1920x1080@25).
For GPU images, the default is 1920x1080@60.
Arbitrary viewport dimensions and refresh rates are accepted.
Known-good presets include:
2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60.
For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10:
800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x102
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kernel-so/refs/heads/main/openapi/kernel-so-browser-pools-api-openapi.yml