Appearance
Fresh 🌱
Create a browser pool ​
Create a new browser pool with the specified configuration and size.
OpenAPI ​
yaml
openapi: 3.1.0
info:
title: Kernel 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.
- name: Browser Replays
description: Record and manage browser session video replays.
- name: Profiles
description: Create, list, retrieve, and delete browser profiles.
- name: Browser Filesystem
description: Read, write, and manage files on the browser instance.
- name: Browser Computer Controls
description: Control mouse, keyboard, and screen on the browser instance.
- name: Browser Playwright
description: Execute Playwright code against the browser instance.
- name: Browser Processes
description: Execute and manage processes on the browser instance.
- name: Browser Logs
description: Stream logs from the browser instance.
- name: Extensions
description: Create, list, retrieve, and delete browser extensions.
- name: Proxies
description: Create and manage proxy configurations for routing browser traffic.
- name: Browser Pools
description: Create and manage browser pools for acquiring and releasing browsers.
- name: Managed Auth
description: >-
Create and manage auth connections for automated credential capture and
login.
- name: Credentials
description: Create and manage credentials for authentication.
- name: Credential Providers
description: Configure external credential providers like 1Password.
- name: Apps
description: List applications and versions.
- name: Deployments
description: Create and manage app deployments and stream deployment events.
- name: Invocations
description: Invoke actions and stream or query invocation status and events.
- name: Projects
description: Create and manage projects for resource isolation within an organization.
paths:
/browser_pools:
post:
tags:
- Browser Pools
summary: Create a browser pool
description: Create a new browser pool with the specified configuration and size.
operationId: postBrowserPools
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'
security:
- bearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import Kernel from '@onkernel/sdk';
const client = new Kernel({
apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted
});
const browserPool = await client.browserPools.create({ size: 10 });
console.log(browserPool.id);
- lang: Python
source: |-
import os
from kernel import Kernel
client = Kernel(
api_key=os.environ.get("KERNEL_API_KEY"), # This is the default and can be omitted
)
browser_pool = client.browser_pools.create(
size=10,
)
print(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"
components:
schemas:
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 open when a browser is created for the pool.
Navigation is best-effort, so navigation failures do not prevent the
pool from filling. Reused browsers keep the page left by the
previous lease.
example: https://example.com
required:
- size
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
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
BrowserExtension:
type: object
description: >
Extension selection for the browser session. Provide either id or name
of an extension uploaded to Kernel.
properties:
id:
type: string
description: Extension ID to load for this browser session
name:
type: string
minLength: 1
maxLength: 255
pattern: ^[a-zA-Z0-9._-]{1,255}$
description: >-
Extension name to load for this browser session (instead of id).
Must be 1-255 characters, using letters, numbers, dots, underscores,
or hyphens.
oneOf:
- required:
- id
- required:
- name
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,
768x1024, 800x1600.
Viewports outside this list may exhibit unstable live view or recording
behavior.
If refresh_rate is not provided, it will be automatically determined
based on the resolution
(higher resolutions use lower refresh rates to keep bandwidth
reasonable).
properties:
width:
type: integer
description: Browser window width in pixels.
minimum: 320
maximum: 7680
example: 1280
height:
type: integer
description: Browser window height in pixels.
minimum: 240
maximum: 4320
example: 800
refresh_rate:
type: integer
description: >-
Display refresh rate in Hz. If omitted, automatically determined
from width and height.
example: 60
required:
- width
- height
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'
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
responses:
BadRequest:
description: Bad Request - invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - missing or invalid authorization token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden - insufficient permissions or plan
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Conflict:
description: Conflict - resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Too Many Requests - rate limit exceeded
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer