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
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
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
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'
ManagedAuthError:
type: object
description: >-
Extended error response for managed auth operations with recovery
context
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code for programmatic handling
enum:
- login_form_not_found
- navigation_confused
- domain_not_allowed
- stuck_in_loop
- max_attempts_reached
- website_error
- network_error
- element_not_found
- credentials_invalid
- mfa_required
- external_action_required
- unsupported_auth_method
- bot_detected
- captcha_blocked
- session_expired
- no_active_flow
- flow_failed
- awaiting_input_timeout
- external_action_timeout
- max_steps_exceeded
- browser_error
- internal_error
example: login_form_not_found
message:
type: string
description: Human-readable error message suitable for display
example: >-
We couldn't find a login form on this page. The website may have
changed its layout, or the login URL might be incorrect.
details:
type: string
description: Additional technical details for debugging (not shown to end users)
example: >-
Searched for login forms at https://example.com/login, found 0 form
elements
doc_url:
type: string
format: uri
description: Link to documentation about this error
example: https://docs.onkernel.com/errors/login_form_not_found
recoverable:
type: boolean
description: Whether the user can retry or take action to resolve this error
example: true
InvokeResponse:
type: object
properties:
id:
type: string
description: ID of the invocation
example: rr33xuugxj9h0bkf1rdt2bet
action_name:
type: string
description: Name of the action invoked
example: analyze
status:
type: string
description: Status of the invocation
enum:
- queued
- running
- succeeded
- failed
example: queued
status_reason:
type: string
description: Status reason
example: Invocation queued for execution
output:
type: string
description: >-
The return value of the action that was invoked, rendered as a JSON
string. This could be: string, number, boolean, array, object, or
null.
example: '{"result":"success","data":"processed input"}'
required:
- id
- action_name
- status
Invocation:
type: object
properties:
id:
type: string
description: ID of the invocation
example: rr33xuugxj9h0bkf1rdt2bet
app_name:
type: string
description: Name of the application
example: my-app
version:
type: string
description: Version label for the application
example: 1.0.0
action_name:
type: string
description: Name of the action invoked
example: analyze
payload:
type: string
description: >-
Payload provided to the invocation. This is a string that can be
parsed as JSON.
example: '{"data":"example input"}'
output:
type: string
description: >-
Output produced by the action, rendered as a JSON string. This could
be: string, number, boolean, array, object, or null.
example: '{"result":"success","data":"processed input"}'
started_at:
type: string
format: date-time
description: RFC 3339 Nanoseconds timestamp when the invocation started
example: 2024-05-19T15:30:00.000000000Z07:00
finished_at:
type: string
format: date-time
nullable: true
description: >-
RFC 3339 Nanoseconds timestamp when the invocation finished (null if
still running)
example: 2024-05-19T15:30:05.000000000Z07:00
status:
type: string
description: Status of the invocation
enum:
- queued
- running
- succeeded
- failed
example: succeeded
status_reason:
type: string
description: Status reason
example: Invocation completed successfully
required:
- id
- app_name
- version
- action_name
- started_at
- status
Tags:
type: object
maxProperties: 50
description: User-defined key-value tags.
propertyNames:
type: string
minLength: 1
maxLength: 128
pattern: ^[A-Za-z0-9 _.:/=+@-]+$
additionalProperties:
type: string
minLength: 0
maxLength: 256
pattern: ^[A-Za-z0-9 _.:/=+@-]*$
example:
team: backend
env: staging
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
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'
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
chrome_policy:
type: object
additionalProperties: true
description: >
Custom Chrome enterprise policy overrides applied to this browser
session. 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/
telemetry:
$ref: '#/components/schemas/BrowserTelemetryRequestConfig'
nullable: true
description: >
Telemetry configuration for the browser session. Set enabled to true
to start capture using VM defaults, or provide browser category
settings. If omitted, null, set to an empty object ({}), set to
enabled: false without browser category settings, or all four
categories are explicitly disabled, capture is not started.
required: []
BrowserUsage:
type: object
description: Session usage metrics.
properties:
uptime_ms:
type: integer
description: Time in milliseconds the session was actively running.
required:
- uptime_ms
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
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.
BrowserTelemetryConfig:
type: object
description: Active telemetry configuration for a browser session.
properties:
browser:
$ref: '#/components/schemas/BrowserTelemetryCategoriesConfig'
description: Per-category enable/disable flags.
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.
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.
BrowserTelemetryCategoryConfig:
type: object
description: Per-category telemetry configuration.
properties:
enabled:
type: boolean
description: >-
Whether this category is captured. Operational categories (control,
connection, system, captcha) default to true; set false to opt out.
CDP categories (console, network, page, interaction) and screenshot
default to false; set true to opt in.
BrowserEventSource:
type: object
description: Provenance metadata identifying which producer emitted the event.
required:
- kind
properties:
kind:
type: string
enum:
- cdp
- kernel_api
- extension
- local_process
description: >-
Event producer. cdp: Chrome DevTools Protocol events from the
browser. kernel_api: Kernel API server. extension: injected Chrome
extension. local_process: system process running alongside the
browser.
event:
type: string
description: >-
Producer-specific event name (e.g. Runtime.consoleAPICalled for
CDP-sourced console events, Runtime.exceptionThrown for uncaught
exceptions).
metadata:
type: object
description: Producer-specific context (e.g. CDP target/session/frame IDs).
additionalProperties:
type: string
BrowserCallStack:
type: object
description: >-
CDP Runtime.StackTrace representing the JavaScript call stack at the
time of an event. Fields use CDP naming conventions rather than
snake_case to match the Chrome DevTools Protocol wire format.
required:
- callFrames
properties:
description:
type: string
description: Optional label for the stack trace (e.g. async cause).
callFrames:
type: array
description: Ordered list of call frames, outermost first.
items:
type: object
required:
- functionName
- scriptId
- url
- lineNumber
- columnNumber
properties:
functionName:
type: string
description: >-
JavaScript function name, or empty string for anonymous
functions.
scriptId:
type: string
description: CDP script identifier.
url:
type: string
description: URL or name of the script file.
lineNumber:
type: integer
description: Zero-based line number within the script.
columnNumber:
type: integer
description: Zero-based column number within the line.
parent:
$ref: '#/components/schemas/BrowserCallStack'
description: Parent stack trace for async stacks.
BrowserHttpHeaders:
type: object
description: >-
HTTP headers map forwarded as-is from CDP without normalization. Values
are typically strings but may be any JSON type.
additionalProperties: true
BrowserTargetType:
type: string
description: CDP target type of the page that produced the event.
enum:
- page
- background_page
- service_worker
- shared_worker
- other
BrowserEventContext:
type: object
description: >-
Browser event context stamped by the browser monitor onto all
CDP-sourced events. Identifies the target, frame, and navigation epoch
in which the event occurred.
properties:
session_id:
type: string
description: CDP session identifier for the target connection.
target_id:
type: string
description: Browser target identifier (stable across navigations within a tab).
target_type:
$ref: '#/components/schemas/BrowserTargetType'
frame_id:
type: string
description: CDP frame identifier within the target.
loader_id:
type: string
description: CDP document loader identifier, reset on each navigation.
url:
type: string
description: >-
URL relevant to this event — page URL for navigation and page
events, request URL for network events.
nav_seq:
type: integer
format: int64
description: >-
Monotonically increasing navigation sequence number, incremented on
each top-level navigation within the target.
BrowserConsoleLogEvent:
type: object
title: console_log
description: >-
A browser console log event (console.log, console.info, console.warn,
etc.).
required:
- ts
- type
- category
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: console_log
category:
type: string
const: console
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
level:
type: string
description: >-
CDP Runtime.consoleAPICalled type, passed through unfiltered
from Chrome. error is routed to console_error events
instead; all other CDP console types appear here. See CDP
spec for the full enum.
text:
type: string
description: First console argument coerced to string.
args:
type: array
description: All console arguments coerced to strings.
items:
type: string
stack_trace:
$ref: '#/components/schemas/BrowserCallStack'
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserConsoleErrorEvent:
type: object
title: console_error
description: >
A browser console error or uncaught JavaScript exception event. Emitted
from two distinct CDP sources with different data shapes.
Runtime.consoleAPICalled (console.error calls) produces level, text,
args, and stack_trace. Runtime.exceptionThrown (uncaught exceptions)
produces text, line, column, source_url, and stack_trace. Fields not
applicable to the source are absent.
required:
- ts
- type
- category
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: console_error
category:
type: string
const: console
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
required:
- text
properties:
text:
type: string
description: >
Human-readable error text, as the browser console would
display it. For console.error() calls, the first argument
coerced to a string. For uncaught exceptions, the prefix and
error message, e.g. "Uncaught Error: boom" or "Uncaught (in
promise) TypeError: x is not a function".
stack_trace:
$ref: '#/components/schemas/BrowserCallStack'
level:
type: string
description: >-
CDP console type value, always "error". Present only when
sourced from Runtime.consoleAPICalled.
args:
type: array
description: >-
All console arguments coerced to strings. Present only when
sourced from Runtime.consoleAPICalled.
items:
type: string
line:
type: integer
description: >-
Line number in the script where the exception was thrown.
Present only when sourced from Runtime.exceptionThrown.
column:
type: integer
description: >-
Column number in the script where the exception was thrown.
Present only when sourced from Runtime.exceptionThrown.
source_url:
type: string
description: >-
URL of the script file that threw the exception. Present
only when sourced from Runtime.exceptionThrown.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserNetworkRequestEvent:
type: obje
# --- truncated at 32 KB (565 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kernel/refs/heads/main/openapi/kernel-openapi-original.yml