Appearance
Fresh 🌱
Update browser session ​
Update a browser session.
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/{id}:
patch:
tags:
- Browsers
summary: Update browser session
description: Update a browser session.
operationId: patchBrowsersById
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
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'
'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 browser = await
client.browsers.update('htzv5orfit78e1m2biiifpbv');
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.update(
id="htzv5orfit78e1m2biiifpbv",
)
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.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"
components:
schemas:
BrowserUpdateRequest:
type: object
description: Request body for updating a browser session.
properties:
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.
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
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
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.
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
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
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
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'
NotFound:
description: Resource not found
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