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
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
BrowserRequest:
type: object
description: |
Parameters for creating a browser session.
properties:
invocation_id:
type: string
description: action invocation ID
example: rr33xuugxj9h0bkf1rdt2bet
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
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/BrowserTelemetryConfig'
nullable: true
description: >-
Telemetry configuration for the browser session. If provided,
telemetry capture starts with the specified category filter when the
session is created. If omitted, no telemetry capture is 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:
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/BrowserTelemetryConfig'
nullable: true
description: >
Telemetry configuration. Omit, set to null, or set to an empty
object ({}) to leave the existing configuration unchanged (no-op).
To enable capture for all categories using VM defaults, set browser
to an empty object ({"browser": {}}). To stop capture, set every
category's enabled to false.
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.
BrowserTelemetryCategoryConfig:
type: object
description: Per-category telemetry configuration.
properties:
enabled:
type: boolean
description: Whether this category is captured. Defaults to true if omitted.
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
description: >-
A browser console log event (console.log, console.info, console.warn,
etc.).
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: console_log
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
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
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: console_error
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
required:
- text
properties:
text:
type: string
description: Error message text. Present in both source paths.
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: object
description: A browser network request sent event.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: network_request
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
request_id:
type: string
description: CDP request identifier, unique within the session.
method:
type: string
description: HTTP method as sent on the wire (e.g. GET, POST).
document_url:
type: string
description: URL of the document that initiated the request.
headers:
$ref: '#/components/schemas/BrowserHttpHeaders'
description: Request headers.
resource_type:
type: string
description: >-
CDP Network.ResourceType for the request, passed through
as-is from Chrome. Known values include Document, Fetch,
XHR, Script, Stylesheet, Image, Media, Font, TextTrack,
EventSource, WebSocket, Manifest, Prefetch, Other, and more.
initiator_type:
type: string
description: >-
CDP Initiator.type indicating what caused the request,
passed through as-is from Chrome. Known values include
script, parser, preload, and other.
post_data:
type: string
description: Request body for POST/PUT requests, if available.
is_redirect:
type: boolean
description: True if this request is the result of a redirect.
redirect_url:
type: string
description: >-
Original URL before the redirect, present when is_redirect
is true.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserNetworkResponseEvent:
type: object
description: >-
A browser network response received event. Fired after the response body
is fully received, not when headers arrive.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: network_response
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
request_id:
type: string
description: >-
CDP request identifier matching the originating
network_request event.
method:
type: string
description: HTTP method of the original request.
status:
type: integer
description: HTTP response status code.
status_text:
type: string
description: HTTP response status text (e.g. OK, Not Found).
headers:
$ref: '#/components/schemas/BrowserHttpHeaders'
description: Response headers.
mime_type:
type: string
description: >-
MIME type of the response (e.g. text/html,
application/json).
resource_type:
type: string
description: >-
CDP Network.ResourceType for the request, passed through
as-is from Chrome. Known values include Document, Fetch,
XHR, Script, Stylesheet, Image, Media, Font, TextTrack,
EventSource, WebSocket, Manifest, Prefetch, Other, and more.
body:
type: string
description: Truncated response body, present only for text MIME types.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserNetworkLoadingFailedEvent:
type: object
description: >-
A browser network loading failed event. If the request was already in
flight when CDP attached (no prior network_request was emitted for it),
url, frame_id, loader_id, and resource_type are absent;
BrowserEventContext is partially populated in that case.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: network_loading_failed
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
request_id:
type: string
description: >-
CDP request identifier matching the originating
network_request event.
error_text:
type: string
description: >-
Network error description (e.g.
net::ERR_CONNECTION_REFUSED).
canceled:
type: boolean
description: >-
True if the request was canceled by the browser or page
script.
resource_type:
type: string
description: >-
CDP Network.ResourceType for the request, passed through
as-is from Chrome. Known values include Document, Fetch,
XHR, Script, Stylesheet, Image, Media, Font, TextTrack,
EventSource, WebSocket, Manifest, Prefetch, Other, and more.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserNetworkIdleEvent:
type: object
d
# --- truncated at 32 KB (476 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kernel-so/refs/heads/main/openapi/kernel-openapi.yml