Appearance
Fresh 🌱
Create a browser session ​
Create a new browser session from within an action.
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:
/browsers:
post:
tags:
- Browsers
summary: Create a browser session
description: Create a new browser session from within an action.
operationId: postBrowsers
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'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
'529':
$ref: '#/components/responses/CapacityExhausted'
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 browser = await client.browsers.create();
console.log(browser.session_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 = client.browsers.create()
print(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"
components:
schemas:
BrowserRequest:
type: object
description: |
Parameters for creating a browser session.
properties:
invocation_id:
type: string
description: action invocation ID
example: rr33xuugxj9h0bkf1rdt2bet
persistence:
$ref: '#/components/schemas/BrowserPersistence'
deprecated: true
x-deprecated-reason: Use timeout_seconds (up to 72 hours) and Profiles instead
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 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
start_url:
type: string
description: >-
Optional URL to open when the browser session is created. Navigation
is best-effort, so navigation failures do not prevent the session
from being created.
example: https://example.com
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
persistence:
$ref: '#/components/schemas/BrowserPersistence'
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: Start URL requested for the session, if provided.
example: https://example.com
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'
required:
- created_at
- cdp_ws_url
- webdriver_ws_url
- session_id
- stealth
- headless
- timeout_seconds
BrowserPersistence:
type: object
description: 'DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.'
deprecated: true
x-deprecated-reason: Use timeout_seconds (up to 72 hours) and Profiles instead
properties:
id:
type: string
description: 'DEPRECATED: Unique identifier for the persistent browser session.'
example: my-awesome-browser-for-user-1234
required:
- id
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
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
BrowserUsage:
type: object
description: Session usage metrics.
properties:
uptime_ms:
type: integer
description: Time in milliseconds the session was actively running.
required:
- uptime_ms
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'
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'
CapacityExhausted:
description: Capacity exhausted, unable to fulfill request at this time
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer