diff --git a/specs/openapi.documented.yml b/specs/openapi.documented.yml new file mode 100644 index 0000000..787e175 --- /dev/null +++ b/specs/openapi.documented.yml @@ -0,0 +1,18249 @@ +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. + export: + $ref: '#/components/schemas/BrowserTelemetryExportConfig' + description: Where the session's captured telemetry is being exported. Omitted when the export state is unknown. + BrowserTelemetryExportConfig: + type: object + description: Active export state for a session's captured telemetry, by protocol. + properties: + otlp: + $ref: '#/components/schemas/BrowserTelemetryOTLPExportConfig' + description: Active OTLP export state. + BrowserTelemetryOTLPExportConfig: + type: object + description: Active OTLP export state for a browser session. + properties: + enabled: + type: boolean + description: Whether the session is exporting captured telemetry over OTLP. + destination: + type: string + description: ID of the OTLP destination the session is bound to. Omitted when the session is not exporting. + 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. + export: + $ref: '#/components/schemas/BrowserTelemetryExportRequestConfig' + description: Where to export this session's captured telemetry. Omit to capture without exporting. + 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. + BrowserTelemetryExportRequestConfig: + type: object + description: Export destinations for a session's captured telemetry, by protocol. Honored when creating a browser, including the browser a managed auth connection creates for a login. Browser pools do not support export and reject it; on a browser update it is ignored, so the session keeps the destination it was created with. + properties: + otlp: + $ref: '#/components/schemas/BrowserTelemetryOTLPExportRequestConfig' + description: Export captured telemetry over OTLP to one of the org's configured destinations. + BrowserTelemetryOTLPExportRequestConfig: + type: object + description: OTLP export settings for a browser session. + properties: + enabled: + type: boolean + description: Whether to export captured telemetry over OTLP. Setting destination implies enabled=true, so this only needs to be set explicitly to disable export (enabled=false with a destination is rejected). + destination: + $ref: '#/components/schemas/OTLPDestinationRef' + description: OTLP destination to export this session's captured telemetry to. Provide either id or name. Requires telemetry capture to be enabled. + OTLPDestinationRef: + type: object + description: | + OTLP destination selection. Provide either id or name. The destination must belong to the caller's org. + When selecting by name, the name must match exactly one destination in the org. Ambiguous names return a 400; use id for stable references. + properties: + id: + type: string + description: OTLP destination ID + name: + type: string + description: OTLP destination name + oneOf: + - required: + - id + - required: + - name + 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: object + title: network_request + description: A browser network request sent event. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: network_request + category: + type: string + const: network + 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 + title: network_response + description: A browser network response received event. Fired after the response body is fully received, not when headers arrive. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: network_response + category: + type: string + const: network + 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 + title: network_loading_failed + 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 + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: network_loading_failed + category: + type: string + const: network + 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 + title: network_idle + description: A browser network idle event emitted after a 500ms quiet period with no in-flight HTTP requests. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: network_idle + category: + type: string + const: network + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + $ref: '#/components/schemas/BrowserEventContext' + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageNavigationEvent: + type: object + title: page_navigation + description: A browser page navigation started event (CDP Page.frameNavigated). Carries nav context fields inline but not nav_seq, as this event resets the navigation epoch. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_navigation + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + url: + type: string + description: URL navigated to. + frame_id: + type: string + description: CDP frame identifier of the navigated frame. + parent_frame_id: + type: string + description: Parent frame identifier for subframe navigations; absent for top-level navigations. + loader_id: + type: string + description: New CDP document loader identifier assigned for this navigation. + session_id: + type: string + description: CDP session identifier. + target_id: + type: string + description: Browser target identifier. + target_type: + $ref: '#/components/schemas/BrowserTargetType' + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageDomContentLoadedEvent: + type: object + title: page_dom_content_loaded + description: A browser DOMContentLoaded event (CDP Page.domContentEventFired). + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_dom_content_loaded + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + cdp_timestamp: + type: number + description: Chrome monotonic clock value in seconds at which DOMContentLoaded fired, relative to browser process start (not Unix epoch). Use ts for wall-clock time. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageLoadEvent: + type: object + title: page_load + description: A browser page load event (CDP Page.loadEventFired). + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_load + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + cdp_timestamp: + type: number + description: Chrome monotonic clock value in seconds at which the load event fired, relative to browser process start (not Unix epoch). Use ts for wall-clock time. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageTabOpenedEvent: + type: object + title: page_tab_opened + description: A new browser tab or target was opened (CDP Target.attachedToTarget for page targets). Fires before a CDP session is attached to the new target, so session_id, frame_id, loader_id, and nav_seq are absent; this event does not compose BrowserEventContext. Consumers reading context fields generically should treat it as a special case. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_tab_opened + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + target_id: + type: string + description: CDP target identifier for the newly opened tab. + target_type: + $ref: '#/components/schemas/BrowserTargetType' + url: + type: string + description: Initial URL of the new tab. + title: + type: string + description: Initial page title of the new tab. + opener_id: + type: string + description: Target identifier of the tab that opened this one, if any. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageLayoutShiftEvent: + type: object + title: page_layout_shift + description: A browser cumulative layout shift (CLS) event from the Performance Timeline API. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_layout_shift + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + source_frame_id: + type: string + description: CDP frame identifier of the frame where the layout shift occurred. + time: + type: number + description: Performance Timeline timestamp of the layout shift in milliseconds. + duration: + type: number + description: Duration of the layout shift entry in milliseconds (always 0 for layout shifts per spec). + layout_shift_details: + type: object + additionalProperties: false + description: PerformanceLayoutShift attributes from the Performance Timeline entry. + properties: + value: + type: number + description: Layout shift score for this entry (contribution to CLS). + had_recent_input: + type: boolean + description: True if the layout shift was preceded by user input within 500ms, excluding it from CLS. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageLcpEvent: + type: object + title: page_lcp + description: A browser Largest Contentful Paint (LCP) event from the Performance Timeline API. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_lcp + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + source_frame_id: + type: string + description: CDP frame identifier of the frame where the LCP element was rendered. + time: + type: number + description: Performance Timeline timestamp of the LCP entry in milliseconds. + lcp_details: + type: object + additionalProperties: false + description: LargestContentfulPaint attributes from the Performance Timeline entry. + properties: + render_time: + type: number + description: Render time of the LCP element in milliseconds; 0 for cross-origin images without Timing-Allow-Origin. + load_time: + type: number + description: Load time of the LCP element in milliseconds. + size: + type: number + description: Visible area of the LCP element in pixels squared. + element_id: + type: string + description: id attribute of the LCP element, if present. + url: + type: string + description: URL of the LCP element for image or video elements. + node_id: + type: integer + description: CDP DOM node identifier of the LCP element. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageLayoutSettledEvent: + type: object + title: page_layout_settled + description: A browser layout settled event emitted 1 second after page load with no intervening layout shifts, indicating visual stability. Each layout shift resets the 1-second timer. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_layout_settled + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + $ref: '#/components/schemas/BrowserEventContext' + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserPageNavigationSettledEvent: + type: object + title: page_navigation_settled + description: Emitted when page_dom_content_loaded and page_layout_settled have both fired for the same navigation, indicating the page is loaded and visually stable. Independent of network_idle; a single pending request does not block it. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: page_navigation_settled + category: + type: string + const: page + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + $ref: '#/components/schemas/BrowserEventContext' + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserInteractionClickEvent: + type: object + title: interaction_click + description: A browser user click event captured via injected page script. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: interaction_click + category: + type: string + const: interaction + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + x: + type: integer + description: Viewport x-coordinate of the click in CSS pixels. + y: + type: integer + description: Viewport y-coordinate of the click in CSS pixels. + selector: + type: string + description: CSS selector path to the clicked element. + tag: + type: string + description: HTML tag name of the clicked element in uppercase (e.g. BUTTON, A, DIV). + text: + type: string + description: Visible text content of the clicked element, trimmed. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserInteractionKeyEvent: + type: object + title: interaction_key + description: A browser keyboard event captured via injected page script. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: interaction_key + category: + type: string + const: interaction + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + key: + type: string + description: Key value from the KeyboardEvent (e.g. Enter, Backspace, a). + selector: + type: string + description: CSS selector path to the element that had focus when the key was pressed. + tag: + type: string + description: HTML tag name of the focused element in uppercase (e.g. INPUT, TEXTAREA, DIV). + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserInteractionScrollSettledEvent: + type: object + title: interaction_scroll_settled + description: A browser scroll settled event emitted after scroll position stops changing, captured via injected page script. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: interaction_scroll_settled + category: + type: string + const: interaction + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + allOf: + - $ref: '#/components/schemas/BrowserEventContext' + - type: object + properties: + from_x: + type: integer + description: Scroll x-position at the start of the scroll gesture in CSS pixels. + from_y: + type: integer + description: Scroll y-position at the start of the scroll gesture in CSS pixels. + to_x: + type: integer + description: Final scroll x-position after the gesture settled in CSS pixels. + to_y: + type: integer + description: Final scroll y-position after the gesture settled in CSS pixels. + target_selector: + type: string + description: CSS selector path to the scrolled element. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserMonitorScreenshotEvent: + type: object + title: monitor_screenshot + description: A periodic screenshot of the browser viewport. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: monitor_screenshot + category: + type: string + const: screenshot + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + png: + type: string + contentEncoding: base64 + description: Base64-encoded PNG screenshot of the browser viewport. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserMonitorDisconnectedEvent: + type: object + title: monitor_disconnected + description: The CDP connection to Chrome was lost. Telemetry events may be dropped until monitor_reconnected arrives. Treat any in-progress computed state (network_idle, page_layout_settled) as unreliable until then. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: monitor_disconnected + category: + type: string + const: monitor + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + reason: + type: string + description: 'Reason for the disconnection. chrome_restarted: Chrome process restarted.' + enum: + - chrome_restarted + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserMonitorReconnectedEvent: + type: object + title: monitor_reconnected + description: The CDP connection to Chrome was successfully re-established after a disconnection. Events emitted during the gap are lost. Computed state is reset, so navigation and network tracking restart fresh from this point. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: monitor_reconnected + category: + type: string + const: monitor + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + reconnect_duration_ms: + type: integer + format: int64 + description: Wall-clock time in milliseconds taken to reconnect after the disconnection. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserMonitorReconnectFailedEvent: + type: object + title: monitor_reconnect_failed + description: The CDP connection to Chrome could not be re-established after exhausting all reconnection attempts. No further telemetry events will arrive on this session. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: monitor_reconnect_failed + category: + type: string + const: monitor + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + reason: + type: string + description: 'Reason for the reconnection failure. reconnect_exhausted: all retry attempts were used up without successfully restoring the CDP connection.' + enum: + - reconnect_exhausted + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserMonitorInitFailedEvent: + type: object + title: monitor_init_failed + description: The CDP session could not be initialized. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: monitor_init_failed + category: + type: string + const: monitor + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + properties: + step: + type: string + description: The CDP method or initialization step that failed (e.g. Target.setAutoAttach). + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserApiCallEvent: + type: object + description: An agent-driven HTTP call handled by the in-VM API server. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: api_call + category: + type: string + const: control + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - request_id + - operation_id + - status + - duration_ms + properties: + request_id: + type: string + description: Per-request identifier from the in-VM API request middleware. + operation_id: + type: string + description: OpenAPI operationId of the matched route (e.g. processExec, takeScreenshot). + status: + type: integer + description: HTTP response status code. + duration_ms: + type: number + description: Wall-clock duration of the handler in milliseconds. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserCdpConnectEvent: + type: object + description: An external client (e.g. customer SDK, Playwright, Puppeteer) connected to the CDP WebSocket proxy on this VM. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: cdp_connect + category: + type: string + const: connection + source: + $ref: '#/components/schemas/BrowserEventSource' + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserCdpDisconnectEvent: + type: object + description: An external client disconnected from the CDP WebSocket proxy on this VM. Pair with the immediately preceding cdp_connect on the same stream. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: cdp_disconnect + category: + type: string + const: connection + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - duration_ms + - message_count + - reason + properties: + duration_ms: + type: number + description: Wall-clock duration of the connection in milliseconds. + message_count: + type: integer + description: Number of CDP messages relayed across the connection in either direction. + reason: + type: string + x-go-type: string + description: 'Why the connection ended. client_close: the client initiated the close. upstream_changed: Chromium restarted mid-session and the proxy tore down so the client could reconnect against the new upstream. upstream_error: upstream dial or message pump errored. context_cancelled: the request context was cancelled (typically server shutdown).' + enum: + - client_close + - upstream_changed + - upstream_error + - context_cancelled + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserLiveViewConnectEvent: + type: object + description: A live view client connected to the headful browser's WebRTC server. Headful only; not emitted for headless images. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: live_view_connect + category: + type: string + const: connection + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - session_id + properties: + session_id: + type: string + description: Live view session identifier. Stable across reconnects, so a transient network blip can emit two events with the same session_id. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserLiveViewDisconnectEvent: + type: object + description: A live view client disconnected from the headful browser's WebRTC server. Pair with live_view_connect by session_id. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: live_view_disconnect + category: + type: string + const: connection + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - session_id + - duration_ms + properties: + session_id: + type: string + description: Live view session identifier; matches the corresponding live_view_connect event. + duration_ms: + type: number + description: Wall-clock duration of the connection in milliseconds. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserCaptchaSolveResultEvent: + type: object + description: A captcha solve attempt reached a terminal outcome. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: captcha_solve_result + category: + type: string + const: captcha + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - captcha_type + - status + - duration_ms + properties: + captcha_type: + type: string + x-go-type: string + description: Captcha vendor family. Provider-specific task names are normalized into this set; anything not covered is reported as other. + enum: + - hcaptcha + - recaptcha_v2 + - recaptcha_v3 + - turnstile + - geetest + - other + status: + type: string + x-go-type: string + description: 'Terminal outcome. success: solver returned a usable solution. failure: solver returned an error (see error_code). timeout: solver did not return within the caller''s wait budget. abandoned: caller cancelled or the page navigated away mid-solve.' + enum: + - success + - failure + - timeout + - abandoned + duration_ms: + type: number + description: Wall-clock duration from solve start to terminal outcome. + task_id: + type: string + description: Solver-assigned identifier. Opaque, useful for support cross-references. + website_host: + type: string + description: Host of the page where the captcha was solved. + website_path: + type: string + description: Path of the page where the captcha was solved. Query string excluded. + error_code: + type: string + description: Solver-specific error code on failure (e.g. ERROR_CAPTCHA_UNSOLVABLE). Absent on success. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserSystemOomKillEvent: + type: object + description: The Linux kernel OOM-killer terminated a process inside the VM. Fires for any process killed by the kernel due to memory exhaustion, including Chrome renderer subprocesses that are not supervised. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: system_oom_kill + category: + type: string + const: system + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - process_name + - pid + - rss_kb + properties: + process_name: + type: string + description: Comm of the killed process as reported by the kernel (max 15 chars, truncated by the kernel). + pid: + type: integer + description: PID of the killed process. + rss_kb: + type: integer + description: Resident set size of the killed process in KiB (sum of anon-rss, file-rss, and shmem-rss). + trigger_process_name: + type: string + description: Comm of the process whose allocation request caused the kernel to invoke the OOM-killer. Often the same as process_name but can differ. Max 15 chars. + trigger_pid: + type: integer + description: PID of the triggering process. Absent if the kernel did not emit the standard header line. + constraint: + type: string + x-go-type: string + description: Why the kernel decided to OOM-kill. none means global memory exhaustion; memcg means a cgroup memory limit was hit; cpuset / memory_policy are NUMA/policy-driven kills. Absent on kernels older than 5.0. + enum: + - none + - memcg + - cpuset + - memory_policy + mem_total_kb: + type: integer + description: Total system memory in KiB at the time of the kill. Assumes a 4 KiB page size. Absent if the kernel did not emit a parseable Mem-Info section. + mem_free_kb: + type: integer + description: Free system memory in KiB at the time of the kill. Assumes a 4 KiB page size. Does not include reclaimable caches. Absent if the kernel did not emit a parseable Mem-Info section. + top_tasks: + type: array + maxItems: 5 + description: Top processes by resident-set-size at the moment of the kill, sorted descending. Empty if the kernel did not emit the Tasks state table. Capped at 5 entries. + items: + type: object + additionalProperties: false + required: + - pid + - name + - rss_kb + properties: + pid: + type: integer + description: PID of the process. + name: + type: string + description: Comm of the process (max 15 chars, truncated by the kernel). + rss_kb: + type: integer + description: Resident set size in KiB at the moment of the kill. + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserServiceCrashedEvent: + type: object + description: A managed service exited unexpectedly. Intentional stops do not produce this event; only unexpected exits and terminal restart-give-up transitions do. + required: + - ts + - type + - category + - source + properties: + ts: + type: integer + format: int64 + description: Event timestamp in Unix microseconds. + type: + type: string + const: service_crashed + category: + type: string + const: system + source: + $ref: '#/components/schemas/BrowserEventSource' + data: + type: object + additionalProperties: false + required: + - service_name + - phase + properties: + service_name: + type: string + description: Program name of the crashed service (e.g. chromium, mutter, kernel-images-api). + pid: + type: integer + description: PID of the crashed process. Absent when the process manager gave up after exhausting restart attempts. + phase: + type: string + x-go-type: string + description: 'Lifecycle phase the crash occurred in. startup: the process died before reaching a healthy running state. running: a previously healthy process died unexpectedly. gave_up: the process manager exhausted its restart attempts and stopped trying.' + enum: + - startup + - running + - gave_up + truncated: + type: boolean + description: True if the data field was truncated due to size limits. + BrowserTelemetryEvent: + oneOf: + - $ref: '#/components/schemas/BrowserConsoleLogEvent' + - $ref: '#/components/schemas/BrowserConsoleErrorEvent' + - $ref: '#/components/schemas/BrowserNetworkRequestEvent' + - $ref: '#/components/schemas/BrowserNetworkResponseEvent' + - $ref: '#/components/schemas/BrowserNetworkLoadingFailedEvent' + - $ref: '#/components/schemas/BrowserNetworkIdleEvent' + - $ref: '#/components/schemas/BrowserPageNavigationEvent' + - $ref: '#/components/schemas/BrowserPageDomContentLoadedEvent' + - $ref: '#/components/schemas/BrowserPageLoadEvent' + - $ref: '#/components/schemas/BrowserPageTabOpenedEvent' + - $ref: '#/components/schemas/BrowserPageLayoutShiftEvent' + - $ref: '#/components/schemas/BrowserPageLcpEvent' + - $ref: '#/components/schemas/BrowserPageLayoutSettledEvent' + - $ref: '#/components/schemas/BrowserPageNavigationSettledEvent' + - $ref: '#/components/schemas/BrowserInteractionClickEvent' + - $ref: '#/components/schemas/BrowserInteractionKeyEvent' + - $ref: '#/components/schemas/BrowserInteractionScrollSettledEvent' + - $ref: '#/components/schemas/BrowserMonitorScreenshotEvent' + - $ref: '#/components/schemas/BrowserMonitorDisconnectedEvent' + - $ref: '#/components/schemas/BrowserMonitorReconnectedEvent' + - $ref: '#/components/schemas/BrowserMonitorReconnectFailedEvent' + - $ref: '#/components/schemas/BrowserMonitorInitFailedEvent' + - $ref: '#/components/schemas/BrowserApiCallEvent' + - $ref: '#/components/schemas/BrowserCdpConnectEvent' + - $ref: '#/components/schemas/BrowserCdpDisconnectEvent' + - $ref: '#/components/schemas/BrowserLiveViewConnectEvent' + - $ref: '#/components/schemas/BrowserLiveViewDisconnectEvent' + - $ref: '#/components/schemas/BrowserCaptchaSolveResultEvent' + - $ref: '#/components/schemas/BrowserSystemOomKillEvent' + - $ref: '#/components/schemas/BrowserServiceCrashedEvent' + discriminator: + propertyName: type + mapping: + console_log: '#/components/schemas/BrowserConsoleLogEvent' + console_error: '#/components/schemas/BrowserConsoleErrorEvent' + network_request: '#/components/schemas/BrowserNetworkRequestEvent' + network_response: '#/components/schemas/BrowserNetworkResponseEvent' + network_loading_failed: '#/components/schemas/BrowserNetworkLoadingFailedEvent' + network_idle: '#/components/schemas/BrowserNetworkIdleEvent' + page_navigation: '#/components/schemas/BrowserPageNavigationEvent' + page_dom_content_loaded: '#/components/schemas/BrowserPageDomContentLoadedEvent' + page_load: '#/components/schemas/BrowserPageLoadEvent' + page_tab_opened: '#/components/schemas/BrowserPageTabOpenedEvent' + page_layout_shift: '#/components/schemas/BrowserPageLayoutShiftEvent' + page_lcp: '#/components/schemas/BrowserPageLcpEvent' + page_layout_settled: '#/components/schemas/BrowserPageLayoutSettledEvent' + page_navigation_settled: '#/components/schemas/BrowserPageNavigationSettledEvent' + interaction_click: '#/components/schemas/BrowserInteractionClickEvent' + interaction_key: '#/components/schemas/BrowserInteractionKeyEvent' + interaction_scroll_settled: '#/components/schemas/BrowserInteractionScrollSettledEvent' + monitor_screenshot: '#/components/schemas/BrowserMonitorScreenshotEvent' + monitor_disconnected: '#/components/schemas/BrowserMonitorDisconnectedEvent' + monitor_reconnected: '#/components/schemas/BrowserMonitorReconnectedEvent' + monitor_reconnect_failed: '#/components/schemas/BrowserMonitorReconnectFailedEvent' + monitor_init_failed: '#/components/schemas/BrowserMonitorInitFailedEvent' + api_call: '#/components/schemas/BrowserApiCallEvent' + cdp_connect: '#/components/schemas/BrowserCdpConnectEvent' + cdp_disconnect: '#/components/schemas/BrowserCdpDisconnectEvent' + live_view_connect: '#/components/schemas/BrowserLiveViewConnectEvent' + live_view_disconnect: '#/components/schemas/BrowserLiveViewDisconnectEvent' + captcha_solve_result: '#/components/schemas/BrowserCaptchaSolveResultEvent' + system_oom_kill: '#/components/schemas/BrowserSystemOomKillEvent' + service_crashed: '#/components/schemas/BrowserServiceCrashedEvent' + description: | + Union type representing any browser telemetry event. Discriminated on `type`. Each event's `category` determines when it is captured. The CDP collector-health events (monitor_disconnected, monitor_reconnected, monitor_reconnect_failed, monitor_init_failed) use the `monitor` category, which is not user-configurable: it flows automatically whenever any CDP category (console, network, page, interaction) is captured, and is silent otherwise. monitor_screenshot uses the opt-in `screenshot` category. All other event types are controlled by their per-category enable/disable flags. + BrowserTelemetryEventEnvelope: + type: object + description: | + Envelope wrapping a browser telemetry event with its monotonic sequence number. Each SSE data: frame carries one envelope as JSON. The seq value is also emitted as the SSE id: field so clients can pass it as Last-Event-ID on reconnect. + required: + - seq + - event + properties: + seq: + type: integer + format: int64 + minimum: 1 + description: | + Process-monotonic sequence number assigned by the browser VM. Pass as Last-Event-ID on reconnect to resume without gaps. Gaps in received seq values indicate dropped events. + event: + $ref: '#/components/schemas/BrowserTelemetryEvent' + additionalProperties: false + 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 + ProfileRequest: + type: object + description: Request body for creating a profile. + properties: + name: + type: string + description: Optional name of the profile. Must be unique within the logical project; during the default-project migration, unscoped profiles and profiles in the org default project are treated as the same project. + required: [] + ProfileUpdateRequest: + type: object + required: + - name + properties: + name: + type: string + description: New profile name. Must be unique within the logical project; during the default-project migration, unscoped profiles and profiles in the org default project are treated as the same project. + minLength: 1 + maxLength: 255 + example: my-renamed-profile + 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 + BrowserPoolProfile: + type: object + description: | + Profile configuration for browsers in a pool. Provide either id or name. Profiles must + be created beforehand. Unlike single browser sessions, pools load the profile read-only + and never persist changes back to it, so save_changes is omitted here. Any save_changes + value sent on a pool profile is silently ignored rather than rejected. + properties: + id: + type: string + description: Profile ID to load for browsers in this pool + name: + type: string + minLength: 1 + maxLength: 255 + pattern: ^[a-zA-Z0-9._-]{1,255}$ + description: Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. + oneOf: + - required: + - id + - required: + - name + ProxyRef: + type: object + description: | + Proxy selection. Provide either id or name. The proxy must be in the same project as the resource referencing it. + When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references. + properties: + id: + type: string + description: Proxy ID + name: + type: string + description: Proxy name + 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, 768x1024@60, 390x844@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. Any positive integer is accepted. + minimum: 1 + example: 1280 + height: + type: integer + description: Browser window height in pixels. Any positive integer is accepted. + minimum: 1 + example: 800 + refresh_rate: + type: integer + description: Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height. + minimum: 1 + example: 60 + required: + - width + - height + 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. + Extension: + type: object + description: A browser extension uploaded to Kernel. + properties: + id: + type: string + description: Unique identifier for the extension + name: + type: string + nullable: true + description: Optional, easier-to-reference name for the extension. Must be unique within the project. + created_at: + type: string + format: date-time + description: Timestamp when the extension was created + size_bytes: + type: integer + description: Size of the extension archive in bytes + checksum: + type: string + nullable: true + minLength: 64 + maxLength: 64 + description: SHA-256 checksum, encoded as lowercase hexadecimal, of the exact uploaded extension archive bytes. This is not a normalized checksum of the extension contents; archive metadata, file ordering, and compression can change the checksum for otherwise identical contents. Omitted for legacy rows and server-repackaged Chrome Web Store extensions. + last_used_at: + type: string + format: date-time + nullable: true + description: Timestamp when the extension was last used + required: + - id + - created_at + - size_bytes + 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 + BrowserPoolConfig: + type: object + description: | + Effective browser pool configuration returned by the API. + properties: + size: + type: integer + description: | + Number of browsers maintained 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 + 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 + fill_rate_per_minute: + type: integer + description: Percentage of the pool to fill per minute. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here. + minimum: 0 + timeout_seconds: + type: integer + description: Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). + minimum: 10 + maximum: 259200 + 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. + example: false + profile: + allOf: + - $ref: '#/components/schemas/BrowserPoolProfile' + description: Profile selection for browsers in the pool. + refresh_on_profile_update: + type: boolean + description: | + When true, flush idle browsers when the profile the pool uses is updated, so pool browsers + pick up the latest profile data. When a profile is provided during creation, this defaults + to true. Requires a profile to be set on the pool. + example: true + 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 associated to the browser session. References a proxy in the same project as the browser session. + viewport: + allOf: + - $ref: '#/components/schemas/BrowserViewport' + description: Browser viewport used for newly-warmed browsers in this pool. + 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/ The serialized JSON payload is capped at 5 MiB. + start_url: + type: string + maxLength: 2048 + description: | + Optional URL to navigate to when a new browser is warmed into the pool. Best-effort: + failures to navigate do not fail pool fill. Only applied to newly-warmed browsers; + browsers reused via release/acquire keep whatever URL the previous lease left them on. + Accepts any URL Chromium can resolve, including chrome:// pages. + example: https://example.com + telemetry: + $ref: '#/components/schemas/BrowserTelemetryConfig' + nullable: true + description: Active telemetry configuration applied to browsers warmed into this pool, if any. + required: + - size + BrowserPoolCreateRequest: + type: object + description: | + Parameters for creating a browser pool. All browsers in the pool will be created with the same configuration. + properties: + 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 + 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 + fill_rate_per_minute: + type: integer + description: Percentage of the pool to fill per minute. Defaults to 25. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here. + minimum: 0 + default: 25 + timeout_seconds: + type: integer + description: Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours). + minimum: 10 + maximum: 259200 + default: 600 + stealth: + type: boolean + description: If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. Defaults to false. + default: false + example: true + headless: + type: boolean + description: If true, launches the browser using a headless image. Defaults to false. + default: false + example: false + profile: + allOf: + - $ref: '#/components/schemas/BrowserPoolProfile' + description: Profile selection for browsers in the pool. + refresh_on_profile_update: + type: boolean + description: | + When true, flush idle browsers when the profile the pool uses is updated, so pool browsers + pick up the latest profile data. When a profile is provided during creation, this defaults + to true. Requires a profile to be set on the pool. + example: true + default: false + 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: + allOf: + - $ref: '#/components/schemas/BrowserViewport' + description: Browser viewport used for newly-warmed browsers in this pool. + kiosk_mode: + type: boolean + description: If true, launches the browser in kiosk mode to hide address bar and tabs in live view. Defaults to false. + default: false + 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/ The serialized JSON payload is capped at 5 MiB. + start_url: + type: string + maxLength: 2048 + description: | + Optional URL to navigate to when a new browser is warmed into the pool. Best-effort: + failures to navigate do not fail pool fill. Only applied to newly-warmed browsers; + browsers reused via release/acquire keep whatever URL the previous lease left them on. + Accepts any URL Chromium can resolve, including chrome:// pages. + example: https://example.com + telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: | + Telemetry configuration applied to browsers warmed into this pool. Set enabled to true to start capture using the default set, or provide browser category settings. If omitted, null, set to an empty object ({}), set to enabled: false without browser category settings, or all four CDP categories are explicitly disabled, no telemetry is configured on the pool. Only applied to newly-warmed browsers. + required: + - size + BrowserPoolUpdateRequest: + type: object + description: | + Parameters for updating a browser pool. Omitted fields leave existing values unchanged. + properties: + size: + type: integer + description: | + If provided, replaces the 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 + name: + type: string + pattern: ^[a-zA-Z0-9._-]{1,255}$ + description: | + If provided, replaces the pool name. Empty string is a no-op; the pool name cannot + be cleared or reset to empty once assigned. + example: my-pool + fill_rate_per_minute: + type: integer + description: | + If provided, replaces the percentage of the pool to fill per minute. The cap is 25 + for most organizations but can be raised per-organization, so only the lower bound + is enforced here. + minimum: 0 + timeout_seconds: + type: integer + description: If provided, replaces the default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). + minimum: 10 + maximum: 259200 + stealth: + type: boolean + description: If provided, replaces whether browsers launch in stealth mode. + example: true + headless: + type: boolean + description: If provided, replaces whether browsers launch using a headless image. + example: false + profile: + allOf: + - $ref: '#/components/schemas/BrowserPoolProfile' + description: | + If provided, replaces the previously-selected profile. To clear the profile reference, + send `{ "id": "" }` or `{ "name": "" }`. An empty object (no id or name) is rejected + as 400. + refresh_on_profile_update: + type: boolean + description: | + If provided, replaces whether idle browsers are flushed when the profile the pool uses + is updated. When the pool's profile reference is changed (including newly attached) and + this field is omitted, it defaults to true. Re-sending the same profile reference leaves + this setting unchanged. Clearing the profile also disables this setting. Requires a + profile to be set on the pool. + example: true + extensions: + type: array + description: | + If provided, replaces the extension list. Empty array clears all previously-selected + extensions. Omit this field to leave extensions unchanged. + maxItems: 20 + items: + $ref: '#/components/schemas/BrowserExtension' + proxy_id: + type: string + description: Empty string clears the previously-selected proxy. Omit this field to leave the proxy unchanged. + viewport: + allOf: + - $ref: '#/components/schemas/BrowserViewport' + description: | + If provided, replaces the viewport with the new width/height/refresh_rate. Because + width and height are required and must be positive, the viewport cannot be cleared; + omit this field to leave it unchanged. + kiosk_mode: + type: boolean + description: If provided, replaces whether browsers launch in kiosk mode. + example: true + chrome_policy: + type: object + additionalProperties: true + description: | + If provided, replaces the custom Chrome enterprise policy overrides applied to all browsers in this pool. Empty object clears any previously-set policy. 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/ The serialized JSON payload is capped at 5 MiB. + start_url: + type: string + maxLength: 2048 + description: | + If provided, replaces the URL to navigate to when a new browser is warmed into the pool. + Empty string clears the previously-set URL. Omit this field to leave it unchanged. + example: https://example.com + telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: | + If provided, updates the pool's 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 the default set. Set enabled to false to clear the pool's telemetry. Provide browser category settings for per-category updates, merged onto the pool's current configuration. Only applied to browsers warmed after the update; browsers already in the pool keep their configuration until discarded. + discard_all_idle: + type: boolean + description: 'Whether to discard all idle browsers and rebuild them immediately with the new configuration. Defaults to false. Only browsers that are idle when the update runs are rebuilt. A browser that is in use during the update keeps its original configuration, and if it is later released with `reuse: true` it returns to the pool with that stale configuration until it is discarded (by this flag on a later update, or by flushing the pool).' + example: false + default: false + BrowserPoolDeleteRequest: + type: object + description: | + Parameters for deleting a browser pool. + properties: + force: + type: boolean + default: false + description: If true, force delete even if browsers are currently leased. Leased browsers will be terminated. + required: [] + 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/BrowserPoolConfig' + description: Configuration used to create all browsers in this pool + profile_id: + type: string + description: Resolved profile ID the pool is attached to. Omitted when no profile is attached. Authoritative for programmatic consumers; the profile inside `browser_pool_config` reflects the configured selector (echoed as sent on create). + example: iv25ujqf37x3j07dwoffegqr + extension_ids: + type: array + description: Resolved extension IDs attached to the pool, in configured load order. Empty when no extensions are attached. Authoritative for programmatic consumers; the extensions inside `browser_pool_config` reflect the configured selector (echoed as sent on create). + items: + type: string + required: + - id + - available_count + - acquired_count + - created_at + - browser_pool_config + - extension_ids + BrowserPoolAcquireRequest: + type: object + description: Request body for acquiring a browser from the pool. + properties: + acquire_timeout_seconds: + type: integer + description: Maximum number of seconds to wait for a browser to be available. Defaults to the calculated time it would take to fill the pool at the currently configured fill rate. + name: + type: string + description: | + Optional human-readable name for the acquired browser session, used to find it later in the dashboard. Must be unique among active sessions within the pool's project. Applies to this lease only and is cleared when the browser is released back to the pool. + 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 acquired browser session, used to find and group sessions later. Applies to this lease only and are cleared when the browser is released back to the pool. Up to 50 pairs. + start_url: + type: string + description: 'Optional URL to navigate the acquired browser to. Overrides the pool''s start_url for this acquire only. Best-effort: failures to navigate do not fail the acquire.' + example: https://example.com + telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: | + Telemetry override for the acquired browser, applied to this lease only. Merges onto the browser's current (pool-inherited) telemetry using the same per-category semantics as PATCH /browsers: provided categories override the current configuration, omitted categories are inherited. Set enabled to true to resolve the config fresh from the default set, or enabled to false to stop capture. When the browser is released back to the pool with reuse, its telemetry is reset to the pool's baseline, so the override does not carry over to the next lease. + required: [] + BrowserPoolReleaseRequest: + type: object + description: Request body for releasing a browser back to the pool. + properties: + session_id: + type: string + description: Browser session ID to release back to the pool + example: ts8iy3sg25ibheguyni2lg9t + reuse: + type: boolean + description: 'Whether to reuse the browser instance or destroy it and create a new one. Defaults to true. A reused browser keeps the configuration it was created with, so it does not pick up pool configuration changes made while it was in use. Release with `reuse: false`, or flush the pool afterward, to rebuild it with the current configuration.' + default: true + example: false + required: + - session_id + LogEvent: + type: object + description: A log entry from the application. + required: + - event + - message + - timestamp + properties: + event: + type: string + const: log + description: Event type identifier (always "log"). + timestamp: + type: string + format: date-time + description: Time the log entry was produced. + message: + type: string + description: Log message text. + AppVersionSummaryEvent: + type: object + description: Summary of an application version. + required: + - event + - timestamp + - id + - app_name + - version + - region + - actions + properties: + event: + type: string + const: app_version_summary + description: Event type identifier (always "app_version_summary"). + timestamp: + type: string + format: date-time + description: Time the state was reported. + id: + type: string + description: Unique identifier for the app version + 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 + region: + type: string + description: Deployment region code + example: aws.us-east-1a + const: aws.us-east-1a + actions: + type: array + description: List of actions available on the app + items: + $ref: '#/components/schemas/AppAction' + env_vars: + type: object + description: Environment variables configured for this app version. Not currently populated on streamed app_version_summary events. + additionalProperties: + type: string + AppAction: + type: object + description: An action available on the app + required: + - name + properties: + name: + type: string + description: Name of the action + example: analyze + input_schema: + type: object + nullable: true + description: JSON Schema (draft-07) describing the expected input payload. Null if schema could not be automatically generated. + additionalProperties: true + output_schema: + type: object + nullable: true + description: JSON Schema (draft-07) describing the expected output payload. Null if schema could not be automatically generated. + additionalProperties: true + ErrorEvent: + type: object + description: An error event from the application. + required: + - event + - timestamp + - error + properties: + event: + type: string + const: error + description: Event type identifier (always "error"). + timestamp: + type: string + format: date-time + description: Time the error occurred. + error: + $ref: '#/components/schemas/Error' + AppVersionSummary: + type: object + description: Summary of an application version. + properties: + id: + type: string + description: Unique identifier for the app version + 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 + region: + type: string + description: Deployment region code + example: aws.us-east-1a + const: aws.us-east-1a + deployment: + type: string + description: Deployment ID + actions: + type: array + description: List of actions available on the app + items: + $ref: '#/components/schemas/AppAction' + env_vars: + type: object + description: Environment variables configured for this app version. Values are redacted for API key, OAuth, and managed-auth callers, which receive every key with an empty string value. Only dashboard sessions receive the actual values. + additionalProperties: + type: string + required: + - id + - app_name + - version + - region + - deployment + - actions + - env_vars + InvocationUpdateRequest: + type: object + description: Request body for updating an invocation. + properties: + status: + type: string + description: New status for the invocation. + enum: + - succeeded + - failed + output: + type: string + description: Updated output of the invocation rendered as JSON string. + required: + - status + Deployment: + type: object + description: Deployment record information. + properties: + id: + type: string + description: Unique identifier for the deployment + example: rr33xuugxj9h0bkf1rdt2bet + status: + type: string + description: Current status of the deployment + enum: + - queued + - in_progress + - running + - failed + - stopped + example: queued + status_reason: + type: string + description: Status reason + example: Deployment in progress + region: + type: string + description: Deployment region code + example: aws.us-east-1a + const: aws.us-east-1a + entrypoint_rel_path: + type: string + description: Relative path to the application entrypoint + example: src/app.py + env_vars: + type: object + description: Environment variables configured for this deployment. Values are redacted for API key, OAuth, and managed-auth callers, which receive every key with an empty string value. Only dashboard sessions receive the actual values. + additionalProperties: + type: string + created_at: + type: string + format: date-time + description: Timestamp when the deployment was created + updated_at: + type: string + format: date-time + nullable: true + description: Timestamp when the deployment was last updated + source_type: + type: string + description: Origin of the deployed source code. This is read-only response provenance; `file` indicates an uploaded archive and `github` indicates a repository fetched by the API. + enum: + - file + - github + x-go-type-name: DeploymentSourceOrigin + example: github + source_url: + type: string + description: For GitHub-sourced deployments, the repository URL that was fetched. Omitted for file uploads. + example: https://github.com/org/repo + source_ref: + type: string + description: For GitHub-sourced deployments, the git ref as requested at deploy time (branch, tag, or commit SHA — not resolved to a commit). Omitted for file uploads. + example: main + source_path: + type: string + description: For GitHub-sourced deployments, the subpath within the repository that was used as the deploy root. Omitted when the repo root was used or for file uploads. + example: apps/api + source_checksum: + type: string + description: Hex-encoded SHA-256 checksum of the source archive. For file uploads, this hashes the uploaded archive; for GitHub-sourced deployments, this hashes the GitHub archive downloaded by the API. Omitted for deployments created before this field was recorded. + example: 3f4d0ea1bd2c5c1a1a1f0e9d8c7b6a5948372615049382716a5b4c3d2e1f0a9b + required: + - id + - status + - region + - created_at + DeploymentSource: + type: object + description: Source from which to fetch application code. + properties: + type: + type: string + description: Source type identifier. + enum: + - github + example: github + url: + type: string + description: Base repository URL (without blob/tree suffixes). + example: https://github.com/org/repo + ref: + type: string + description: Git ref (branch, tag, or commit SHA) to fetch. + example: main + path: + type: string + description: Path within the repo to deploy (omit to use repo root). + example: apps/api + entrypoint: + type: string + description: Relative path to the application entrypoint within the selected path. + example: src/index.ts + auth: + type: object + description: Authentication for private repositories. + properties: + method: + type: string + enum: + - github_token + description: Auth method + example: github_token + token: + type: string + format: password + description: GitHub PAT or installation access token + example: ghs_*** + required: + - method + - token + required: + - type + - url + - ref + - entrypoint + DeploymentRequest: + type: object + description: App deployment request. Provide either file+entrypoint_rel_path or source. + properties: + version: + type: string + description: Version of the application. Can be any string. + example: 1.0.0 + default: latest + file: + type: string + format: binary + description: ZIP file containing the application source directory + example: '@path/to/file.zip' + entrypoint_rel_path: + type: string + description: Relative path to the entrypoint of the application + example: src/app.py + source: + $ref: '#/components/schemas/DeploymentSource' + region: + type: string + description: Region for deployment. Currently we only support "aws.us-east-1a" + example: aws.us-east-1a + default: aws.us-east-1a + const: aws.us-east-1a + force: + type: boolean + description: Allow overwriting an existing app version + example: false + default: false + env_vars: + type: object + description: Map of environment variables to set for the deployed application. Each key-value pair represents an environment variable. + additionalProperties: + type: string + oneOf: + - required: + - file + - entrypoint_rel_path + - required: + - source + DeploymentStateEvent: + type: object + description: An event representing the current state of a deployment. + required: + - event + - deployment + - timestamp + properties: + event: + type: string + const: deployment_state + description: Event type identifier (always "deployment_state"). + deployment: + $ref: '#/components/schemas/Deployment' + timestamp: + type: string + format: date-time + description: Time the state was reported. + DeploymentEvent: + oneOf: + - $ref: '#/components/schemas/LogEvent' + - $ref: '#/components/schemas/DeploymentStateEvent' + - $ref: '#/components/schemas/AppVersionSummaryEvent' + - $ref: '#/components/schemas/ErrorEvent' + - $ref: '#/components/schemas/SSEHeartbeatEvent' + discriminator: + propertyName: event + mapping: + log: '#/components/schemas/LogEvent' + deployment_state: '#/components/schemas/DeploymentStateEvent' + app_version_summary: '#/components/schemas/AppVersionSummary' + error: '#/components/schemas/InternalError' + sse_heartbeat: '#/components/schemas/SSEHeartbeatEvent' + description: Union type representing any deployment event. + InvocationStateEvent: + type: object + description: An event representing the current state of an invocation. + required: + - event + - invocation + - timestamp + properties: + event: + type: string + const: invocation_state + description: Event type identifier (always "invocation_state"). + invocation: + $ref: '#/components/schemas/Invocation' + timestamp: + type: string + format: date-time + description: Time the state was reported. + InvocationEvent: + oneOf: + - $ref: '#/components/schemas/LogEvent' + - $ref: '#/components/schemas/InvocationStateEvent' + - $ref: '#/components/schemas/ErrorEvent' + - $ref: '#/components/schemas/SSEHeartbeatEvent' + discriminator: + propertyName: event + mapping: + log: '#/components/schemas/LogEvent' + invocation_state: '#/components/schemas/InvocationStateEvent' + error: '#/components/schemas/ErrorEvent' + sse_heartbeat: '#/components/schemas/SSEHeartbeatEvent' + description: Union type representing any invocation event. + ManagedAuthStateEvent: + type: object + description: An event representing the current state of a managed auth flow. + required: + - event + - timestamp + - flow_status + - flow_step + properties: + event: + type: string + const: managed_auth_state + description: Event type identifier (always "managed_auth_state"). + timestamp: + type: string + format: date-time + description: Time the state was reported. + flow_status: + type: string + enum: + - IN_PROGRESS + - SUCCESS + - FAILED + - EXPIRED + - CANCELED + description: Current flow status. + flow_step: + type: string + enum: + - DISCOVERING + - AWAITING_INPUT + - AWAITING_EXTERNAL_ACTION + - SUBMITTING + - COMPLETED + description: Current step in the flow. + flow_type: + type: string + enum: + - LOGIN + - REAUTH + description: Type of the current flow. + fields: + type: array + description: Canonical fields awaiting input. Prefer this over discovered_fields when present. + items: + $ref: '#/components/schemas/ManagedAuthField' + choices: + type: array + description: Canonical choices awaiting selection. Prefer this over pending_sso_buttons, mfa_options, and sign_in_options when present. + items: + $ref: '#/components/schemas/ManagedAuthChoice' + discovered_fields: + type: array + description: Fields awaiting input (present when flow_step=AWAITING_INPUT; may also be present with AWAITING_EXTERNAL_ACTION as fallback actions). + items: + $ref: '#/components/schemas/DiscoveredField' + mfa_options: + type: array + description: MFA method options (present when flow_step=AWAITING_INPUT; may also be present with AWAITING_EXTERNAL_ACTION as fallback actions). + items: + $ref: '#/components/schemas/MFAOption' + sign_in_options: + type: array + description: Non-MFA choices presented during the auth flow, such as account selection or org pickers (present when flow_step=AWAITING_INPUT; may also be present with AWAITING_EXTERNAL_ACTION as fallback actions). + items: + $ref: '#/components/schemas/SignInOption' + pending_sso_buttons: + type: array + description: SSO buttons available (present when flow_step=AWAITING_INPUT; may also be present with AWAITING_EXTERNAL_ACTION as fallback actions). + items: + $ref: '#/components/schemas/SSOButton' + external_action_message: + type: string + description: Instructions for external action (present when flow_step=AWAITING_EXTERNAL_ACTION). + website_error: + type: string + description: Visible error message from the website (e.g., 'Incorrect password'). Present when the website displays an error during login. + error_message: + type: string + description: Error message (present when flow_status=FAILED). + error_code: + type: string + description: Machine-readable error code (present when flow_status=FAILED). + post_login_url: + type: string + format: uri + description: URL where the browser landed after successful login. + live_view_url: + type: string + format: uri + description: Browser live view URL for debugging. + hosted_url: + type: string + format: uri + description: URL to redirect user to for hosted login. + ManagedAuthEvent: + oneOf: + - $ref: '#/components/schemas/ManagedAuthStateEvent' + - $ref: '#/components/schemas/ErrorEvent' + - $ref: '#/components/schemas/SSEHeartbeatEvent' + discriminator: + propertyName: event + mapping: + managed_auth_state: '#/components/schemas/ManagedAuthStateEvent' + error: '#/components/schemas/ErrorEvent' + sse_heartbeat: '#/components/schemas/SSEHeartbeatEvent' + description: Union type representing any managed auth event. + ManagedAuthTimelineEvent: + type: object + description: A single event in an auth connection's history — a login attempt, an automatic re-auth attempt, or a health check. + required: + - type + - id + - timestamp + - status + properties: + type: + type: string + enum: + - login + - reauth + - health_check + description: The kind of event. "login" and "reauth" are authentication attempts; "health_check" is a periodic session-validity check. + id: + type: string + description: Identifier of the underlying login/reauth session or health check. + timestamp: + type: string + format: date-time + description: When the event occurred. + status: + type: string + enum: + - IN_PROGRESS + - SUCCESS + - EXPIRED + - CANCELED + - FAILED + - AUTHENTICATED + - NEEDS_AUTH + description: | + Outcome of the event. For login/reauth events this is the flow status + (IN_PROGRESS, SUCCESS, EXPIRED, CANCELED, FAILED). For health_check events + it is the observed session state (AUTHENTICATED, NEEDS_AUTH). + previous_status: + type: string + enum: + - AUTHENTICATED + - NEEDS_AUTH + description: The session state observed before this event. Present for health_check events that recorded a prior state. + step: + type: string + enum: + - INITIALIZED + - DISCOVERING + - AWAITING_INPUT + - AWAITING_EXTERNAL_ACTION + - AWAITING_HUMAN_INTERVENTION + - SUBMITTING + - COMPLETED + - EXPIRED + description: The step the flow reached. Present for login/reauth events. + error_code: + type: string + description: Machine-readable error code. Present when a login/reauth event failed. + error_message: + type: string + description: Human-readable error message. Present when a login/reauth event failed. + website_error: + type: string + description: Visible error message from the website (e.g., 'Incorrect password'). Present when the website displayed an error during the attempt. + browser_session_id: + type: string + description: Browser session that produced the event, if one was created. + replay_id: + type: string + description: Replay recording ID for the event's browser session, if session recording was enabled. + telemetry_captured: + type: boolean + description: Whether browser telemetry capture started for this event's browser session. + updated_at: + type: string + format: date-time + description: When the event was last updated. Present for login/reauth events. + SSEHeartbeatEvent: + type: object + description: Heartbeat event sent periodically to keep SSE connection alive. + required: + - event + - timestamp + properties: + event: + type: string + const: sse_heartbeat + description: Event type identifier (always "sse_heartbeat"). + timestamp: + type: string + format: date-time + description: Time the heartbeat was sent. + BrowserReplay: + type: object + description: Information about a browser replay recording. + required: + - replay_id + properties: + replay_id: + type: string + description: Unique identifier for the replay recording. + started_at: + type: string + format: date-time + nullable: true + description: Timestamp when replay started + finished_at: + type: string + format: date-time + nullable: true + description: Timestamp when replay finished + replay_view_url: + type: string + description: URL for viewing the replay recording. + example: https://api.onkernel.com/browser/replays?jwt=eyJ0eXAi...&replay_id=7e2c1a9f-1234-4cde-9abc-ffeedd001122 + StartFsWatchRequest: + type: object + required: + - path + properties: + path: + type: string + description: Directory to watch. + recursive: + type: boolean + description: Whether to watch recursively. + default: false + additionalProperties: false + FileSystemEvent: + type: object + description: Filesystem change event. + required: + - type + - path + properties: + type: + type: string + enum: + - CREATE + - WRITE + - DELETE + - RENAME + description: Event type. + name: + type: string + description: Base name of the file or directory affected. + path: + type: string + description: Absolute path of the file or directory. + is_dir: + type: boolean + description: Whether the affected path is a directory. + FileInfo: + type: object + required: + - name + - path + - size_bytes + - is_dir + - mod_time + - mode + properties: + name: + type: string + description: Base name of the file or directory. + path: + type: string + description: Absolute path. + size_bytes: + type: integer + description: Size in bytes. 0 for directories. + is_dir: + type: boolean + description: Whether the path is a directory. + mod_time: + type: string + format: date-time + description: Last modification time. + mode: + type: string + description: File mode bits (e.g., "drwxr-xr-x" or "-rw-r--r--"). + ListFiles: + type: array + description: Array of file or directory information entries. + items: + $ref: '#/components/schemas/FileInfo' + CreateDirectoryRequest: + type: object + required: + - path + properties: + path: + type: string + description: Absolute directory path to create. + pattern: ^/.* + mode: + type: string + description: Optional directory mode (octal string, e.g. 755). Defaults to 755. + pattern: ^[0-7]{3,4}$ + additionalProperties: false + DeletePathRequest: + type: object + required: + - path + properties: + path: + type: string + description: Absolute path to delete. + pattern: ^/.* + additionalProperties: false + SetFilePermissionsRequest: + type: object + required: + - path + - mode + properties: + path: + type: string + description: Absolute path whose permissions are to be changed. + pattern: ^/.* + owner: + type: string + description: New owner username or UID. + group: + type: string + description: New group name or GID. + mode: + type: string + description: File mode bits (octal string, e.g. 644). + pattern: ^[0-7]{3,4}$ + additionalProperties: false + MovePathRequest: + type: object + required: + - src_path + - dest_path + properties: + src_path: + type: string + description: Absolute source path. + pattern: ^/.* + dest_path: + type: string + description: Absolute destination path. + pattern: ^/.* + additionalProperties: false + BrowserCurlRequest: + type: object + description: Request to make an HTTP request through the browser's network stack. + required: + - url + properties: + url: + type: string + description: Target URL (must be http or https). + method: + type: string + description: HTTP method. + enum: + - GET + - HEAD + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + default: GET + headers: + type: object + description: Custom headers merged with browser defaults. + additionalProperties: + type: string + body: + type: string + description: Request body (for POST/PUT/PATCH). + timeout_ms: + type: integer + description: Request timeout in milliseconds. + minimum: 1000 + maximum: 60000 + default: 30000 + response_encoding: + type: string + description: Encoding for the response body. Use base64 for binary content. + enum: + - utf8 + - base64 + default: utf8 + additionalProperties: false + BrowserCurlResult: + type: object + description: Structured response from the browser curl request. + required: + - status + - headers + - body + - duration_ms + properties: + status: + type: integer + description: HTTP status code from target. + headers: + type: object + description: Response headers (multi-value). + additionalProperties: + type: array + items: + type: string + body: + type: string + description: Response body (UTF-8 string or base64 depending on request). + duration_ms: + type: integer + description: Total request duration in milliseconds. + additionalProperties: false + BrowserCurlTransportError: + type: object + description: Transport-level error when the request could not complete. + required: + - message + properties: + message: + type: string + description: Human-readable error description. + net_error: + type: integer + description: Chromium net error code. + net_error_name: + type: string + description: Chromium net error name. + additionalProperties: false + ProcessExecRequest: + type: object + description: Request to execute a command synchronously. + required: + - command + properties: + command: + type: string + description: Executable or shell command to run. + args: + type: array + description: Command arguments. + items: + type: string + default: [] + cwd: + type: string + description: Working directory (absolute path) to run the command in. + nullable: true + pattern: ^/.* + env: + type: object + description: Environment variables to set for the process. + additionalProperties: + type: string + default: {} + as_user: + type: string + description: Run the process as this user. + nullable: true + as_root: + type: boolean + description: Run the process with root privileges. + default: false + timeout_sec: + type: integer + description: Maximum execution time in seconds. + nullable: true + additionalProperties: false + ProcessExecResult: + type: object + description: Result of a synchronous command execution. + properties: + exit_code: + type: integer + description: Process exit code. + stdout_b64: + type: string + description: Base64-encoded stdout buffer. + stderr_b64: + type: string + description: Base64-encoded stderr buffer. + duration_ms: + type: integer + description: Execution duration in milliseconds. + additionalProperties: false + ProcessSpawnRequest: + allOf: + - $ref: '#/components/schemas/ProcessExecRequest' + - type: object + properties: + allocate_tty: + type: boolean + description: Allocate a pseudo-terminal (PTY) for interactive shells. + default: false + rows: + type: integer + description: Initial terminal rows. Only used when allocate_tty is true. + minimum: 1 + maximum: 65535 + cols: + type: integer + description: Initial terminal columns. Only used when allocate_tty is true. + minimum: 1 + maximum: 65535 + ProcessResizeRequest: + type: object + description: Resize a PTY-backed process terminal. + required: + - rows + - cols + properties: + rows: + type: integer + minimum: 1 + maximum: 65535 + description: New terminal rows. + cols: + type: integer + minimum: 1 + maximum: 65535 + description: New terminal columns. + additionalProperties: false + ProcessSpawnResult: + type: object + description: Information about a spawned process. + properties: + process_id: + type: string + format: uuid + description: Server-assigned identifier for the process. + pid: + type: integer + description: OS process ID. + started_at: + type: string + format: date-time + description: Timestamp when the process started. + additionalProperties: false + ProcessStatus: + type: object + description: Current status of a process. + properties: + state: + type: string + enum: + - running + - exited + description: Process state. + exit_code: + type: integer + nullable: true + description: Exit code if the process has exited. + cpu_pct: + type: number + description: Estimated CPU usage percentage. + mem_bytes: + type: integer + description: Estimated resident memory usage in bytes. + additionalProperties: false + ProcessStdinRequest: + type: object + description: Data to write to the process standard input. + required: + - data_b64 + properties: + data_b64: + type: string + description: Base64-encoded data to write. + additionalProperties: false + ProcessStdinResult: + type: object + description: Result of writing to stdin. + properties: + written_bytes: + type: integer + description: Number of bytes written. + additionalProperties: false + ProcessKillRequest: + type: object + description: Signal to send to the process. + required: + - signal + properties: + signal: + type: string + enum: + - TERM + - KILL + - INT + - HUP + default: TERM + description: Signal to send. + additionalProperties: false + ProcessStreamEvent: + type: object + description: SSE payload representing process output or lifecycle events. + properties: + stream: + type: string + description: Source stream of the data chunk. + enum: + - stdout + - stderr + data_b64: + type: string + description: Base64-encoded data from the process stream. + event: + type: string + description: Lifecycle event type. + enum: + - exit + exit_code: + type: integer + description: Exit code when the event is "exit". + additionalProperties: false + ExecutePlaywrightRequest: + type: object + description: Request to execute Playwright code + required: + - code + properties: + code: + type: string + description: | + TypeScript/JavaScript code to execute. The code has access to 'page', 'context', and 'browser' variables. + It runs within a function, so you can use a return statement at the end to return a value. + This value is returned as the `result` property in the response. + Example: "await page.goto('https://example.com'); return await page.title();" + timeout_sec: + type: integer + description: Maximum execution time in seconds. Default is 60. + default: 60 + minimum: 1 + maximum: 300 + additionalProperties: false + ExecutePlaywrightResult: + type: object + description: Result of Playwright code execution + required: + - success + properties: + success: + type: boolean + description: Whether the code executed successfully + result: + description: The value returned by the code (if any) + error: + type: string + description: Error message if execution failed + stdout: + type: string + description: Standard output from the execution + stderr: + type: string + description: Standard error from the execution + additionalProperties: false + ManagedAuthExchangeRequest: + type: object + description: Request to exchange handoff code for JWT + required: + - code + properties: + code: + type: string + description: Handoff code from start endpoint + example: abc123xyz + additionalProperties: false + ManagedAuthExchangeResponse: + type: object + description: Response from exchange endpoint + required: + - invocation_id + - jwt + properties: + invocation_id: + type: string + description: Invocation ID + example: abc123xyz + jwt: + type: string + description: JWT token with invocation_id claim (30 minute TTL) + example: eyJ0eXAi... + additionalProperties: false + ManagedAuthField: + type: object + description: Canonical field awaiting user input. + required: + - id + - ref + - type + properties: + id: + type: string + description: Stable field identifier for canonical submit. + example: field_email + ref: + type: string + description: Credential reference name to store the submitted value under. + example: email + type: + type: string + enum: + - identifier + - password + - code + - totp_code + - totp_secret + - text + description: Managed-auth field type. + example: identifier + label: + type: string + description: Human-readable label shown to the user. + example: Email address + required: + type: boolean + description: Whether this field is required. + default: true + replace_existing: + type: boolean + description: Whether the submitted value must replace an existing credential after explicit rejection. + default: false + observed_selector: + type: string + nullable: true + description: Selector for the visible field, when available. + example: input[name="identifier"] + additionalProperties: false + ManagedAuthChoice: + type: object + description: Canonical auth-flow choice awaiting user selection. + required: + - id + - type + - label + properties: + id: + type: string + description: Stable choice identifier for canonical submit. + example: google + type: + type: string + enum: + - mfa_method + - sso_provider + - sign_in_method + - auth_method + - identifier_method + - account + - other + description: Choice type. + example: sso_provider + label: + type: string + description: Human-readable choice label. + example: Google + description: + type: string + nullable: true + description: Additional context for the choice. + observed_selector: + type: string + nullable: true + description: Selector for the visible choice, when available. + example: button:has-text("Google") + additionalProperties: false + DiscoveredField: + type: object + description: A discovered form field + properties: + name: + type: string + description: Field name + example: email + type: + type: string + enum: + - text + - email + - password + - tel + - number + - url + - code + - totp + description: Field type + example: email + label: + type: string + description: Field label + example: Email address + placeholder: + type: string + description: Field placeholder + example: you@example.com + required: + type: boolean + description: Whether field is required + default: true + example: true + selector: + type: string + description: CSS selector for the field + example: input#email + linked_mfa_type: + $ref: '#/components/schemas/MFAType' + nullable: true + description: If this field is associated with an MFA option, the type of that option (e.g., password field linked to "Enter password" option) + hint: + type: string + description: Contextual help text near the field that tells the user what to enter (e.g., "Enter the phone ending in (***) ***-**92") + example: Enter the phone ending in (***) ***-**92 + required: + - name + - type + - label + - selector + additionalProperties: false + MFAType: + type: string + enum: + - sms + - call + - email + - totp + - push + - password + - switch + description: The MFA delivery method type. Includes 'password' for auth method selection pages and 'switch' for generic method-switcher links like "Use another method" that do not name a specific method. + example: sms + MFAOption: + type: object + description: An MFA method option for verification + properties: + type: + $ref: '#/components/schemas/MFAType' + label: + type: string + description: The visible option text + example: Text me a code + target: + type: string + nullable: true + description: The masked destination (phone/email) if shown + example: '***-***-5678' + description: + type: string + nullable: true + description: Additional instructions from the site + example: We'll send a 6-digit code to your phone + required: + - type + - label + additionalProperties: false + SignInOption: + type: object + description: A non-MFA choice presented during the auth flow (e.g. account selection, org picker) + properties: + id: + type: string + description: Unique identifier for this option (used to submit selection back) + example: work-account + label: + type: string + description: Display text for the option + example: Work Account (user@company.com) + description: + type: string + nullable: true + description: Additional context such as email address or org name + example: user@company.com + required: + - id + - label + additionalProperties: false + SSOButton: + type: object + description: An SSO button for signing in with an external identity provider + properties: + selector: + type: string + description: XPath selector for the button + example: xpath=//button[contains(text(), 'Continue with Google')] + provider: + type: string + description: Identity provider name + example: google + label: + type: string + description: Visible button text + example: Continue with Google + required: + - selector + - provider + - label + additionalProperties: false + ManagedAuth: + type: object + description: Managed authentication that keeps a profile logged into a specific domain. Flow fields (flow_status, flow_step, discovered_fields, mfa_options) reflect the most recent login flow and are null when no flow has been initiated. + required: + - id + - profile_name + - domain + - status + - save_credentials + - record_session + properties: + id: + type: string + description: Unique identifier for the auth connection + example: ma_abc123xyz + profile_name: + type: string + description: Name of the profile associated with this auth connection + example: my-netflix-profile + domain: + type: string + description: Target domain for authentication + example: netflix.com + status: + type: string + enum: + - AUTHENTICATED + - NEEDS_AUTH + description: Current authentication status of the managed profile + example: AUTHENTICATED + last_auth_check_at: + type: string + format: date-time + description: When the most recent auth health check ran for this connection, regardless of outcome. Updated on every health check and does not by itself indicate that the profile is currently authenticated - use `status` for that. May be newer than `flow_expires_at` when a flow is still in progress because health checks continue to run in parallel. + example: "2025-01-15T10:30:00Z" + last_auth_at: + type: string + format: date-time + deprecated: true + description: Deprecated alias for `last_auth_check_at`. Despite the name, this is the last health-check timestamp, not the last successful authentication. Use `last_auth_check_at` instead. + example: "2025-01-15T10:30:00Z" + credential: + $ref: '#/components/schemas/CredentialReference' + can_reauth: + type: boolean + description: Whether Kernel can automatically re-authenticate this connection when the session expires. Requires a prior successful login plus either a Kernel credential or an external credential reference. See `can_reauth_reason` for the specific outcome. + example: true + can_reauth_reason: + type: string + description: |- + Machine-readable reason for the current value of `can_reauth`. + Affirmative values (re-auth is possible): + - `external_credential` — an external credential provider is attached + - `cua_has_credential` — CUA flow with a stored credential + - `has_credential` — Kernel credential is attached (optimistic; plan viability not checked) + - `viable_plans_found` — at least one stored login plan can be replayed + - `no_requirements_recorded` — no recorded credential requirements to fail against + - `requirements_satisfiable` — recorded requirements can be met by the attached credential + + Negative values (a human must complete the login flow): + - `no_prior_successful_login` — connection has never completed a successful login + - `no_credential` — no Kernel or external credential attached + - `no_viable_plans` — credential attached but no replayable login plan exists yet + - `viable_plans_require_external_action` — stored plans need an external step (email link, push, etc.) + - `requires_external_action` — recorded requirements include an external step + - `requires_totp_without_secret` — flow needs a TOTP code but no TOTP secret is stored + - `requires_sms_code` — flow needs an SMS code that cannot be received automatically + - `requires_email_code` — flow needs an email code that cannot be received automatically + enum: + - external_credential + - cua_has_credential + - has_credential + - viable_plans_found + - no_requirements_recorded + - requirements_satisfiable + - no_prior_successful_login + - no_credential + - no_viable_plans + - viable_plans_require_external_action + - requires_external_action + - requires_totp_without_secret + - requires_sms_code + - requires_email_code + example: has_credential + proxy_id: + type: string + description: ID of the proxy associated with this connection, if any. + allowed_domains: + type: array + items: + type: string + description: | + Additional domains that are valid for this auth flow (besides the primary domain). Useful when login pages redirect to different domains. + + The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified: + - Google: accounts.google.com + - Microsoft/Azure AD: login.microsoftonline.com, login.live.com + - Okta: *.okta.com, *.oktapreview.com + - Auth0: *.auth0.com, *.us.auth0.com, *.eu.auth0.com, *.au.auth0.com + - Apple: appleid.apple.com + - GitHub: github.com + - Facebook/Meta: www.facebook.com + - LinkedIn: www.linkedin.com + - Amazon Cognito: *.amazoncognito.com + - OneLogin: *.onelogin.com + - Ping Identity: *.pingone.com, *.pingidentity.com + example: + - login.netflix.com + - auth.netflix.com + login_url: + type: string + format: uri + description: Optional login page URL to skip discovery + example: https://example.com/login + post_login_url: + type: string + format: uri + description: URL where the browser landed after successful login + example: https://www.netflix.com/browse + flow_status: + type: string + enum: + - IN_PROGRESS + - SUCCESS + - FAILED + - EXPIRED + - CANCELED + nullable: true + description: Current flow status (null when no flow in progress) + example: IN_PROGRESS + flow_step: + type: string + enum: + - DISCOVERING + - AWAITING_INPUT + - AWAITING_EXTERNAL_ACTION + - SUBMITTING + - COMPLETED + nullable: true + description: Current step in the flow (null when no flow in progress) + example: AWAITING_INPUT + flow_type: + type: string + enum: + - LOGIN + - REAUTH + nullable: true + description: Type of the current flow (null when no flow in progress) + example: LOGIN + flow_expires_at: + type: string + format: date-time + nullable: true + description: When the current flow expires (null when no flow in progress). A flow past this timestamp is no longer valid and its `flow_status` will be `EXPIRED`. Clients may start a new login to supersede a stale `IN_PROGRESS` flow past this timestamp. + example: "2025-11-05T20:00:00Z" + fields: + type: array + nullable: true + description: Canonical fields awaiting input. Prefer this over discovered_fields when present. + items: + $ref: '#/components/schemas/ManagedAuthField' + choices: + type: array + nullable: true + description: Canonical choices awaiting selection. Prefer this over pending_sso_buttons, mfa_options, and sign_in_options when present. + items: + $ref: '#/components/schemas/ManagedAuthChoice' + discovered_fields: + type: array + nullable: true + description: Fields awaiting input (present when flow_step=awaiting_input; may also be present with awaiting_external_action as fallback actions) + items: + $ref: '#/components/schemas/DiscoveredField' + mfa_options: + type: array + nullable: true + description: MFA method options (present when flow_step=awaiting_input; may also be present with awaiting_external_action as fallback actions) + items: + $ref: '#/components/schemas/MFAOption' + sign_in_options: + type: array + nullable: true + description: Non-MFA choices presented during the auth flow, such as account selection or org pickers (present when flow_step=awaiting_input; may also be present with awaiting_external_action as fallback actions). + items: + $ref: '#/components/schemas/SignInOption' + pending_sso_buttons: + type: array + nullable: true + description: SSO buttons available (present when flow_step=awaiting_input; may also be present with awaiting_external_action as fallback actions) + items: + $ref: '#/components/schemas/SSOButton' + external_action_message: + type: string + nullable: true + description: Instructions for external action (present when flow_step=awaiting_external_action) + example: Tap 'Yes' on the Google prompt on your phone + website_error: + type: string + nullable: true + description: Visible error message from the website (e.g., 'Incorrect password'). Present when the website displays an error during login. + sso_provider: + type: string + nullable: true + description: SSO provider being used (e.g., google, github, microsoft) + example: google + error_message: + type: string + nullable: true + description: Error message (present when flow_status=failed) + example: Invalid password + error_code: + type: string + nullable: true + description: Machine-readable error code (present when flow_status=failed) + hosted_url: + type: string + format: uri + nullable: true + description: URL to redirect user to for hosted login (present when flow in progress) + example: https://auth.kernel.com/login/abc123xyz + live_view_url: + type: string + format: uri + nullable: true + description: Browser live view URL for debugging (present when flow in progress) + example: https://live.kernel.com/abc123xyz + browser_session_id: + type: string + nullable: true + description: | + ID of the underlying browser session driving the current flow (present when flow in progress). + Use this to inspect or terminate the browser session via the `/browsers` API. + example: bs_abc123xyz + health_check_interval: + type: integer + nullable: true + minimum: 300 + maximum: 86400 + description: | + Interval in seconds between automatic health checks. When set, the system periodically + verifies the authentication status and triggers re-authentication if needed. + Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum depends on your plan: + Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour). + example: 3600 + health_checks: + type: boolean + description: | + Whether periodic health checks are enabled for this connection. When false, the system + will not automatically verify authentication status, and `auto_reauth` has no effect on + the automatic flow (since re-auth is only triggered by a failed scheduled health check). + Manually triggering a health check via the API still works regardless of this setting. + example: true + auto_reauth: + type: boolean + description: | + Whether automatic re-authentication is permitted for this connection. This is an opt-in + flag only — it does not check whether re-auth is actually feasible. Even when true, + re-auth only runs when the system has what it needs to perform it (for example, saved + credentials for the required login fields), and only after a scheduled health check + detects an expired session — so this flag has no effect when `health_checks` is false. + When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` + instead of attempting re-auth. + example: true + save_credentials: + type: boolean + description: Whether credentials are saved after every successful login. One-time codes (TOTP, SMS, etc.) are not saved. + example: true + record_session: + type: boolean + description: Whether to record browser session replays for this connection by default. Useful for debugging login flows. Can be overridden per-login. + example: false + browser_telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: Browser telemetry configuration used by this connection's browser sessions by default. The exact create-browser configuration is preserved and can be overridden per-login. + additionalProperties: false + ManagedAuthCreateRequest: + type: object + description: Request to create an auth connection for a profile and domain + required: + - domain + - profile_name + properties: + domain: + type: string + description: Domain for authentication + example: netflix.com + profile_name: + type: string + description: Name of the profile to manage authentication for. If the profile does not exist, it is created automatically. + example: user-123 + login_url: + type: string + format: uri + description: Optional login page URL to skip discovery + example: https://netflix.com/login + proxy: + $ref: '#/components/schemas/ProxyRef' + credential: + $ref: '#/components/schemas/CredentialReference' + allowed_domains: + type: array + items: + type: string + description: | + Additional domains valid for this auth flow (besides the primary domain). Useful when login pages redirect to different domains. + + The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified: + - Google: accounts.google.com + - Microsoft/Azure AD: login.microsoftonline.com, login.live.com + - Okta: *.okta.com, *.oktapreview.com + - Auth0: *.auth0.com, *.us.auth0.com, *.eu.auth0.com, *.au.auth0.com + - Apple: appleid.apple.com + - GitHub: github.com + - Facebook/Meta: www.facebook.com + - LinkedIn: www.linkedin.com + - Amazon Cognito: *.amazoncognito.com + - OneLogin: *.onelogin.com + - Ping Identity: *.pingone.com, *.pingidentity.com + example: + - login.netflix.com + - auth.netflix.com + health_check_interval: + type: integer + minimum: 300 + maximum: 86400 + description: | + Interval in seconds between automatic health checks. When set, the system periodically + verifies the authentication status and triggers re-authentication if needed. + Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum depends on your plan: + Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour). + example: 3600 + health_checks: + type: boolean + default: true + description: | + Whether to enable periodic health checks. When false, the system will not automatically + verify authentication status, and `auto_reauth` has no effect on the automatic flow + (since re-auth is only triggered by a failed scheduled health check). Defaults to true. + example: true + auto_reauth: + type: boolean + default: true + description: | + Whether to permit automatic re-authentication when a scheduled health check detects an + expired session. This is an opt-in flag only — it does not check whether re-auth is + actually feasible. Even when true, re-auth only runs when the system has what it needs + to perform it (for example, saved credentials for the required login fields), and only + after a scheduled health check detects an expired session — so this flag has no effect + when `health_checks` is false. When false, expired sessions are marked as `NEEDS_AUTH` + instead of attempting re-auth. Defaults to true. + example: true + save_credentials: + type: boolean + default: true + description: Whether to save credentials after every successful login. Defaults to true. One-time codes (TOTP, SMS, etc.) are not saved. + example: true + record_session: + type: boolean + default: false + description: Whether to record browser sessions for this connection by default. Useful for debugging. Can be overridden per-login. Defaults to false. + example: false + browser_telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: Browser telemetry configuration used by this connection's browser sessions by default. Uses the exact create-browser configuration. Can be overridden per-login. + additionalProperties: false + ManagedAuthUpdateRequest: + type: object + description: Request to update an auth connection's configuration + properties: + login_url: + type: string + format: uri + description: Login page URL. Set to empty string to clear. + example: https://netflix.com/login + credential: + $ref: '#/components/schemas/CredentialReference' + allowed_domains: + type: array + items: + type: string + description: Additional domains valid for this auth flow (replaces existing list) + example: + - login.netflix.com + - auth.netflix.com + health_check_interval: + type: integer + minimum: 300 + maximum: 86400 + description: Interval in seconds between automatic health checks + example: 3600 + health_checks: + type: boolean + description: | + Whether periodic health checks are enabled. When set to false, the system will not + automatically verify authentication status, and `auto_reauth` has no effect on the + automatic flow (since re-auth is only triggered by a failed scheduled health check). + example: true + auto_reauth: + type: boolean + description: | + Whether automatic re-authentication is permitted for this connection. This is an opt-in + flag only — it does not check whether re-auth is actually feasible. Even when true, + re-auth only runs when the system has what it needs to perform it (for example, saved + credentials for the required login fields), and only after a scheduled health check + detects an expired session — so this flag has no effect when `health_checks` is false. + When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` + instead of attempting re-auth. + example: true + save_credentials: + type: boolean + description: Whether to save credentials after every successful login + example: true + record_session: + type: boolean + description: Whether to record browser sessions for this connection by default + example: false + browser_telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: Browser telemetry configuration used by future browser sessions for this connection. Uses the exact create-browser configuration. Set enabled to false to disable telemetry. + proxy: + $ref: '#/components/schemas/ProxyRef' + additionalProperties: false + LoginRequest: + type: object + description: Request to start a login flow + properties: + proxy: + $ref: '#/components/schemas/ProxyRef' + record_session: + type: boolean + description: Override the connection's default for recording this login's browser session. When omitted, the connection's record_session default is used. + example: true + browser_telemetry: + $ref: '#/components/schemas/BrowserTelemetryRequestConfig' + nullable: true + description: Override the connection's default browser telemetry configuration for this login. When omitted, the connection's browser_telemetry default is used. Uses the exact create-browser configuration. + additionalProperties: false + LoginResponse: + type: object + description: Response from starting a login flow + required: + - id + - flow_type + - hosted_url + - flow_expires_at + properties: + id: + type: string + description: Auth connection ID + example: ma_abc123xyz + flow_type: + type: string + enum: + - LOGIN + - REAUTH + description: Type of login flow started + example: LOGIN + hosted_url: + type: string + format: uri + description: URL to redirect user to for login + example: https://auth.kernel.com/login/abc123xyz + flow_expires_at: + type: string + format: date-time + description: When the login flow expires + example: "2025-11-05T20:00:00Z" + handoff_code: + type: string + description: One-time code for handoff (internal use) + example: aBcD123EfGh456IjKl789MnOp012QrStUvWxYzAbCdEf + live_view_url: + type: string + format: uri + description: Browser live view URL for watching the login flow + example: https://live.onkernel.com/abc123xyz + additionalProperties: false + SubmitFieldsRequest: + type: object + description: Request to submit field values, click an SSO button, select an MFA method, or select a sign-in option. Prefer canonical selected_choice_id/field_values when the API returns fields/choices; legacy fields/sso_button_selector/sso_provider/mfa_option_id/sign_in_option_id remain supported during deprecation. + properties: + field_values: + type: object + additionalProperties: + type: string + description: Canonical map of field ID to submitted value. + example: + field_email: user@example.com + field_password: secret + selected_choice_id: + type: string + description: Canonical choice ID selected by the user. + example: google + fields: + type: object + additionalProperties: + type: string + description: Map of field name to value + example: + email: user@example.com + password: secret + sso_button_selector: + type: string + description: XPath selector for the SSO button to click (ODA). Use sso_provider instead for CUA. + example: xpath=//button[contains(text(), 'Continue with Google')] + sso_provider: + type: string + description: SSO provider to click, matching the provider field from pending_sso_buttons (e.g., "google", "github"). Cannot be used with sso_button_selector. + example: google + mfa_option_id: + type: string + description: The MFA method type to select (when mfa_options were returned) + example: sms + sign_in_option_id: + type: string + description: The sign-in option ID to select (when sign_in_options were returned) + example: work-account + additionalProperties: false + SubmitFieldsResponse: + type: object + description: Response from submitting field values + required: + - accepted + properties: + accepted: + type: boolean + description: Whether the submission was accepted for processing + additionalProperties: false + Credential: + type: object + description: A stored credential for automatic re-authentication + required: + - id + - name + - domain + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the credential + example: cred_abc123xyz + name: + type: string + description: Unique name for the credential within the project + example: my-netflix-login + domain: + type: string + description: Target domain this credential is for + example: netflix.com + created_at: + type: string + format: date-time + description: When the credential was created + example: "2025-01-15T10:30:00Z" + updated_at: + type: string + format: date-time + description: When the credential was last updated + example: "2025-01-15T10:30:00Z" + has_values: + type: boolean + description: Whether this credential has stored values (email, password, etc.) + example: true + has_totp_secret: + type: boolean + description: Whether this credential has a TOTP secret configured for automatic 2FA + example: false + value_keys: + type: array + items: + type: string + description: The field names stored in this credential's values (e.g., username, password). Values themselves are never returned. Included on single-credential responses (create, get by id or name, update); omitted from list responses. + example: + - username + - password + sso_provider: + type: string + nullable: true + description: If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page. + example: google + totp_code: + type: string + description: Current 6-digit TOTP code. Only included in create/update responses when totp_secret was just set. + example: "847291" + totp_code_expires_at: + type: string + format: date-time + description: When the totp_code expires. Only included when totp_code is present. + example: "2025-01-15T10:30:30Z" + additionalProperties: false + CreateCredentialRequest: + type: object + description: Request to create a new credential + required: + - name + - domain + - values + properties: + name: + type: string + description: Unique name for the credential within the project + example: my-netflix-login + domain: + type: string + description: Target domain this credential is for + example: netflix.com + values: + type: object + description: Field name to value mapping (e.g., username, password) + additionalProperties: + type: string + example: + username: user@example.com + password: mysecretpassword + totp_secret: + type: string + description: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic 2FA during login. + example: JBSWY3DPEHPK3PXP + sso_provider: + type: string + description: If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page. + example: google + additionalProperties: false + UpdateCredentialRequest: + type: object + description: Request to update an existing credential + properties: + name: + type: string + description: New name for the credential + example: my-updated-login + values: + type: object + description: Field name to value mapping. Values are merged with existing values (new keys added, existing keys overwritten). + additionalProperties: + type: string + example: + username: user@example.com + password: newpassword + remove_value_keys: + type: array + items: + type: string + description: Field names to remove from the credential's stored values. Removals are applied before `values` are merged, so a key present in both is kept with its new value. + example: + - old_field + totp_secret: + type: string + description: Base32-encoded TOTP secret for generating one-time passwords. Spaces and formatting are automatically normalized. Set to empty string to remove. + example: JBSWY3DPEHPK3PXP + sso_provider: + type: string + nullable: true + description: If set, indicates this credential should be used with the specified SSO provider. Set to empty string or null to remove. + example: google + additionalProperties: false + CredentialProvider: + type: object + description: An external credential provider (e.g., 1Password) for automatic credential lookup + required: + - id + - provider_type + - name + - enabled + - priority + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the credential provider + example: credprov_abc123xyz + provider_type: + type: string + description: Type of credential provider + enum: + - onepassword + example: onepassword + name: + type: string + description: Human-readable name for this provider instance + example: my-1password + enabled: + type: boolean + description: Whether the provider is enabled for credential lookups + example: true + priority: + type: integer + description: Priority order for credential lookups (lower numbers are checked first) + example: 0 + created_at: + type: string + format: date-time + description: When the credential provider was created + example: "2025-01-15T10:30:00Z" + updated_at: + type: string + format: date-time + description: When the credential provider was last updated + example: "2025-01-15T10:30:00Z" + additionalProperties: false + CreateCredentialProviderRequest: + type: object + description: Request to create an external credential provider + required: + - provider_type + - name + - token + properties: + provider_type: + type: string + description: Type of credential provider + enum: + - onepassword + example: onepassword + name: + type: string + description: Human-readable name for this provider instance (unique per org) + example: my-1password + token: + type: string + description: Service account token for the provider (e.g., 1Password service account token) + example: ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... + cache_ttl_seconds: + type: integer + description: How long to cache credential lists (default 300 seconds) + default: 300 + example: 300 + additionalProperties: false + UpdateCredentialProviderRequest: + type: object + description: Request to update a credential provider + properties: + name: + type: string + description: Human-readable name for this provider instance + example: my-1password + enabled: + type: boolean + description: Whether the provider is enabled for credential lookups + example: true + priority: + type: integer + description: Priority order for credential lookups (lower numbers are checked first) + example: 0 + token: + type: string + description: New service account token (to rotate credentials) + example: ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... + cache_ttl_seconds: + type: integer + description: How long to cache credential lists + example: 300 + additionalProperties: false + CredentialProviderItem: + type: object + description: A credential item from an external provider (e.g., a 1Password login item) + required: + - id + - title + - vault_id + - vault_name + - path + properties: + id: + type: string + description: Unique identifier for the item within the provider + example: abc123xyz + title: + type: string + description: Display name of the credential item + example: Netflix Login + vault_id: + type: string + description: ID of the vault containing this item + example: vault_abc123 + vault_name: + type: string + description: Name of the vault containing this item + example: Engineering + path: + type: string + description: Path to reference this item (VaultName/ItemTitle format) + example: Engineering/Netflix Login + urls: + type: array + items: + type: string + description: URLs associated with this credential + example: + - https://netflix.com + - https://www.netflix.com + additionalProperties: false + CredentialReference: + type: object + description: | + Reference to credentials for the auth connection. Use one of: + - { name } for Kernel credentials + - { provider, path } for external provider item + - { provider, auto: true } for external provider domain lookup + properties: + name: + type: string + description: Kernel credential name + example: my-netflix-creds + provider: + type: string + description: External provider name (e.g., "my-1p") + example: my-1p + path: + type: string + description: Provider-specific path (e.g., "VaultName/ItemName" for 1Password) + example: Personal/Netflix + auto: + type: boolean + description: If true, lookup by domain from the specified provider + example: true + additionalProperties: false + CredentialProviderTestResult: + type: object + description: Result of testing a credential provider connection + required: + - success + - vaults + properties: + success: + type: boolean + description: Whether the connection test was successful + example: true + vaults: + type: array + description: List of vaults accessible by the service account + items: + type: object + required: + - id + - name + properties: + id: + type: string + description: Vault ID + example: abc123xyz + name: + type: string + description: Vault name + example: Shared Logins + error: + type: string + description: Error message if the test failed + example: Invalid token + additionalProperties: false + OkResponse: + type: object + description: Generic OK response. + required: + - ok + properties: + ok: + type: boolean + description: Indicates success. + default: true + additionalProperties: false + Proxy: + type: object + description: Configuration for routing traffic through a proxy. + required: + - type + properties: + id: + type: string + name: + type: string + description: Readable name of the proxy. + type: + type: string + description: | + Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`. + enum: + - datacenter + - isp + - residential + - mobile + - custom + protocol: + type: string + description: Protocol to use for the proxy connection. + enum: + - http + - https + default: https + bypass_hosts: + type: array + description: Hostnames that should bypass the parent proxy and connect directly. + items: + type: string + status: + type: string + description: Current health status of the proxy. + enum: + - available + - unavailable + last_checked: + type: string + format: date-time + description: Timestamp of the last health check performed on this proxy. + ip_address: + type: string + description: IP address that the proxy uses when making requests. + example: 192.168.1.1 + config: + description: Configuration specific to the selected proxy `type`. + oneOf: + - $ref: '#/components/schemas/DatacenterProxyConfig' + - $ref: '#/components/schemas/IspProxyConfig' + - $ref: '#/components/schemas/ResidentialProxyConfig' + - $ref: '#/components/schemas/MobileProxyConfig' + - $ref: '#/components/schemas/CustomProxyConfig' + discriminator: + propertyName: type + mapping: + datacenter: '#/components/schemas/DatacenterProxyConfig' + isp: '#/components/schemas/IspProxyConfig' + residential: '#/components/schemas/ResidentialProxyConfig' + mobile: '#/components/schemas/MobileProxyConfig' + custom: '#/components/schemas/CustomProxyConfig' + ProxyCheckRequest: + type: object + description: Optional parameters for the proxy health check. + properties: + url: + type: string + example: https://example.com + description: An optional URL to test reachability against. If provided, the proxy check will test connectivity to this URL instead of the default test URLs. Only HTTP and HTTPS schemes are allowed, and the URL must resolve to a public IP address. For ISP and datacenter proxies, the exit IP is stable, so a successful check reliably indicates that subsequent browser sessions will reach the target site with the same IP. For residential and mobile proxies, the exit node changes between requests, so a successful check validates proxy configuration but does not guarantee that a subsequent browser session will use the same exit IP or reach the same site — it is useful for verifying credentials and connectivity, not for predicting site-specific behavior. When provided, the check result does not update the proxy's health status, since a failure may indicate a problem with the target site rather than the proxy itself. + ProxyUpdateRequest: + type: object + required: + - name + properties: + name: + type: string + description: New proxy name. Proxy names are trimmed and length-checked only; duplicates are allowed because proxies are updated by ID, not by name. + minLength: 1 + maxLength: 255 + example: my-renamed-proxy + ProxyCreateRequest: + type: object + description: Configuration for routing traffic through a proxy. + required: + - type + properties: + name: + type: string + description: Readable name of the proxy. + type: + type: string + description: | + Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`. + enum: + - datacenter + - isp + - residential + - mobile + - custom + protocol: + type: string + description: Protocol to use for the proxy connection. + enum: + - http + - https + default: https + bypass_hosts: + type: array + description: Hostnames that should bypass the parent proxy and connect directly. + items: + type: string + config: + description: Configuration specific to the selected proxy `type`. + oneOf: + - $ref: '#/components/schemas/DatacenterProxyConfig' + - $ref: '#/components/schemas/IspProxyConfig' + - $ref: '#/components/schemas/ResidentialProxyConfig' + - $ref: '#/components/schemas/MobileProxyConfig' + - $ref: '#/components/schemas/CreateCustomProxyConfig' + discriminator: + propertyName: type + mapping: + datacenter: '#/components/schemas/DatacenterProxyConfig' + isp: '#/components/schemas/IspProxyConfig' + residential: '#/components/schemas/ResidentialProxyConfig' + mobile: '#/components/schemas/MobileProxyConfig' + custom: '#/components/schemas/CustomProxyConfig' + DatacenterProxyConfig: + type: object + title: Datacenter + description: Configuration for a datacenter proxy. + properties: + country: + type: string + description: ISO 3166 country code. Defaults to US if not provided. + example: US + IspProxyConfig: + type: object + title: ISP + description: Configuration for an ISP proxy. + properties: + country: + type: string + description: ISO 3166 country code. Defaults to US if not provided. + example: US + ResidentialProxyConfig: + type: object + title: Residential + description: Configuration for residential proxies. + properties: + country: + type: string + description: ISO 3166 country code. + example: US + city: + type: string + description: City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided. + example: sanfrancisco + state: + type: string + description: Two-letter state code. + example: CA + zip: + type: string + description: US ZIP code. + example: "94107" + asn: + type: string + description: Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html + example: AS15169 + os: + type: string + description: Operating system of the residential device. + deprecated: true + x-deprecated-reason: os selection not supported by proxy provider + enum: + - windows + - macos + - android + MobileProxyConfig: + type: object + title: Mobile + description: Configuration for mobile proxies. + properties: + country: + type: string + description: ISO 3166 country code + example: US + city: + type: string + description: Provider city alias. Mobile carrier routing can make observed geo vary. + example: brooklyn + state: + type: string + description: US-only state code. Mobile carrier routing can make observed geo vary. + example: NY + CustomProxyConfig: + type: object + title: Custom + description: Configuration for a custom proxy (e.g., private proxy server). + required: + - host + - port + properties: + host: + type: string + description: Proxy host address or IP. + example: 127.0.0.1 + port: + type: integer + description: Proxy port. + example: 8080 + username: + type: string + description: Username for proxy authentication. + example: user123 + has_password: + type: boolean + description: Whether the proxy has a password. + example: true + has_ca_bundle: + type: boolean + description: Whether the proxy has a custom CA bundle configured. + example: true + CreateCustomProxyConfig: + type: object + title: Custom + description: Configuration for a custom proxy (e.g., private proxy server). + required: + - host + - port + properties: + host: + type: string + description: Proxy host address or IP. + example: 127.0.0.1 + port: + type: integer + description: Proxy port. + example: 8080 + username: + type: string + description: Username for proxy authentication. + example: user123 + password: + type: string + maxLength: 4096 + description: Password for proxy authentication. + example: secret + ca_bundle: + type: string + maxLength: 65536 + description: PEM-encoded CA certificate bundle the proxy re-signs upstream TLS with. Provide when the proxy terminates TLS (MITM) so the browser trusts its certificates. May contain multiple concatenated certificates. + example: | + -----BEGIN CERTIFICATE----- + MIIB... + -----END CERTIFICATE----- + ClickMouseRequest: + type: object + required: + - x + - y + properties: + button: + type: string + description: Mouse button to interact with + enum: + - left + - right + - middle + - back + - forward + click_type: + type: string + description: Type of click action + enum: + - down + - up + - click + x: + type: integer + description: X coordinate of the click position + y: + type: integer + description: Y coordinate of the click position + hold_keys: + type: array + description: Modifier keys to hold during the click + items: + type: string + num_clicks: + type: integer + description: Number of times to repeat the click + default: 1 + additionalProperties: false + MoveMouseRequest: + type: object + required: + - x + - y + properties: + x: + type: integer + description: X coordinate to move the cursor to + y: + type: integer + description: Y coordinate to move the cursor to + hold_keys: + type: array + description: Modifier keys to hold during the move + items: + type: string + smooth: + type: boolean + description: Use human-like Bezier curve path instead of instant mouse movement. + default: true + duration_ms: + type: integer + description: Target total duration in milliseconds for the mouse movement when smooth=true. Omit for automatic timing based on distance. + minimum: 50 + maximum: 5000 + additionalProperties: false + MousePositionResponse: + type: object + required: + - x + - y + properties: + x: + type: integer + description: X coordinate of the cursor + y: + type: integer + description: Y coordinate of the cursor + additionalProperties: false + ClipboardContent: + type: object + required: + - text + properties: + text: + type: string + description: Current clipboard text content + additionalProperties: false + WriteClipboardRequest: + type: object + required: + - text + properties: + text: + type: string + description: Text to write to the system clipboard + additionalProperties: false + ScreenshotRegion: + type: object + required: + - x + - y + - width + - height + properties: + x: + type: integer + description: X coordinate of the region's top-left corner + y: + type: integer + description: Y coordinate of the region's top-left corner + width: + type: integer + description: Width of the region in pixels + height: + type: integer + description: Height of the region in pixels + additionalProperties: false + ScreenshotRequest: + type: object + properties: + region: + $ref: '#/components/schemas/ScreenshotRegion' + additionalProperties: false + TypeTextRequest: + type: object + required: + - text + properties: + text: + type: string + description: Text to type on the browser instance + delay: + type: integer + description: Delay in milliseconds between keystrokes + minimum: 0 + default: 0 + additionalProperties: false + PressKeyRequest: + type: object + required: + - keys + properties: + keys: + type: array + description: | + List of key symbols to press. Each item should be a key symbol supported by xdotool + (see X11 keysym definitions). Examples include "Return", "Shift", "Ctrl", "Alt", "F5". + Items in this list could also be combinations, e.g. "Ctrl+t" or "Ctrl+Shift+Tab". + items: + type: string + duration: + type: integer + description: Duration to hold the keys down in milliseconds. If omitted or 0, keys are tapped. + minimum: 0 + default: 0 + hold_keys: + type: array + description: Optional modifier keys to hold during the key press sequence. + items: + type: string + additionalProperties: false + ScrollRequest: + type: object + required: + - x + - y + properties: + x: + type: integer + description: X coordinate at which to perform the scroll + y: + type: integer + description: Y coordinate at which to perform the scroll + delta_x: + type: integer + description: Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, negative scrolls left. + default: 0 + delta_y: + type: integer + description: Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative scrolls up. + default: 0 + hold_keys: + type: array + description: Modifier keys to hold during the scroll + items: + type: string + additionalProperties: false + DragMouseRequest: + type: object + required: + - path + properties: + path: + type: array + description: Ordered list of [x, y] coordinate pairs to move through while dragging. Must contain at least 2 points. + minItems: 2 + items: + type: array + minItems: 2 + maxItems: 2 + items: + type: integer + button: + type: string + description: Mouse button to drag with + enum: + - left + - middle + - right + delay: + type: integer + description: Delay in milliseconds between button down and starting to move along the path. + minimum: 0 + default: 0 + steps_per_segment: + type: integer + description: Number of relative move steps per segment in the path. Minimum 1. + minimum: 1 + default: 10 + step_delay_ms: + type: integer + description: Delay in milliseconds between relative steps while dragging (not the initial delay). + minimum: 0 + default: 50 + hold_keys: + type: array + description: Modifier keys to hold during the drag + items: + type: string + smooth: + type: boolean + description: Use human-like Bezier curves between path waypoints instead of linear interpolation. When true, steps_per_segment and step_delay_ms are ignored. + default: true + duration_ms: + type: integer + description: Target total duration in milliseconds for the entire drag movement when smooth=true. Omit for automatic timing based on total path length. + minimum: 50 + maximum: 10000 + additionalProperties: false + SetCursorRequest: + type: object + required: + - hidden + properties: + hidden: + type: boolean + description: Whether the cursor should be hidden or visible + additionalProperties: false + SleepAction: + type: object + description: Pause execution for a specified duration. + required: + - duration_ms + properties: + duration_ms: + type: integer + description: Duration to sleep in milliseconds. + minimum: 0 + maximum: 30000 + additionalProperties: false + ComputerAction: + type: object + description: | + A single computer action to execute as part of a batch. The `type` field selects which + action to perform, and the corresponding field contains the action parameters. + Exactly one action field matching the type must be provided. + required: + - type + properties: + type: + type: string + description: The type of action to perform. + enum: + - click_mouse + - move_mouse + - type_text + - press_key + - scroll + - drag_mouse + - set_cursor + - sleep + click_mouse: + $ref: '#/components/schemas/ClickMouseRequest' + move_mouse: + $ref: '#/components/schemas/MoveMouseRequest' + type_text: + $ref: '#/components/schemas/TypeTextRequest' + press_key: + $ref: '#/components/schemas/PressKeyRequest' + scroll: + $ref: '#/components/schemas/ScrollRequest' + drag_mouse: + $ref: '#/components/schemas/DragMouseRequest' + set_cursor: + $ref: '#/components/schemas/SetCursorRequest' + sleep: + $ref: '#/components/schemas/SleepAction' + additionalProperties: false + BatchComputerActionRequest: + type: object + description: A batch of computer actions to execute sequentially. + required: + - actions + properties: + actions: + type: array + description: Ordered list of actions to execute. Execution stops on the first error. + minItems: 1 + maxItems: 100 + items: + $ref: '#/components/schemas/ComputerAction' + additionalProperties: false + ApiKeyCreator: + type: object + required: + - id + - email + - name + properties: + id: + type: string + description: Kernel user ID of the creator. + example: user-abc123 + email: + type: string + format: email + description: Email address of the creator. + example: user@example.com + name: + type: string + nullable: true + description: Display name of the creator, if available. + example: Jane Doe + ApiKey: + type: object + required: + - id + - name + - created_at + - created_by + - expires_at + - deleted_at + - project_id + - project_name + - masked_key + properties: + id: + type: string + description: Unique API key identifier + example: ckv9w8q2f000001l5r3j7k9m4 + name: + type: string + description: Label for the API key. API keys are not addressable by name; use the ID or key identifier for stable references. + example: production + created_at: + type: string + format: date-time + description: When the API key was created + created_by: + $ref: '#/components/schemas/ApiKeyCreator' + expires_at: + type: string + format: date-time + description: When the API key expires + nullable: true + deleted_at: + type: string + format: date-time + description: When the API key was deleted (soft-deleted). Null for keys that have not been deleted. + nullable: true + project_id: + type: string + description: Project identifier for project-scoped API keys. Null means org-wide. + example: proj_abc123 + nullable: true + project_name: + type: string + description: Project name for project-scoped API keys. Null means the key is org-wide or the project name is unavailable. + example: Production + nullable: true + masked_key: + type: string + description: Masked version of the API key + example: sk_1234...abcd + CreatedApiKey: + description: API key returned immediately after creation. Includes the plaintext key once. + allOf: + - $ref: '#/components/schemas/ApiKey' + - type: object + required: + - key + properties: + key: + type: string + description: Plaintext API key. Only returned once when the key is created. + example: sk_1234abcd + CreateApiKeyRequest: + type: object + required: + - name + properties: + name: + type: string + description: Label for the API key (1-255 characters). API keys are not addressable by name. + minLength: 1 + maxLength: 255 + example: staging + days_to_expire: + type: integer + description: Number of days until expiry, up to 3650. Use null for never. + minimum: 1 + maximum: 3650 + example: 30 + nullable: true + project_id: + type: string + description: Unique project identifier + example: proj_abc123 + nullable: true + UpdateApiKeyRequest: + type: object + required: + - name + properties: + name: + type: string + description: New API key name + minLength: 1 + maxLength: 255 + example: new-api-name + RotateApiKeyRequest: + type: object + properties: + days_to_expire: + type: integer + description: Lifetime in days for the new key, up to 3650. Omit to reuse the rotated key's original lifetime, or never-expires if it had none. + minimum: 1 + maximum: 3650 + example: 30 + nullable: true + expire_in_days: + type: integer + description: Grace period in days before the rotated key expires. Use 0 to expire it immediately. Omit for the default grace period of 7 days. + minimum: 0 + maximum: 3650 + example: 7 + nullable: true + AuditLogExportDestination: + type: object + description: |- + An organization-scoped audit log export destination. + + Delivery is at-least-once for rows visible when their window is committed: a delivery that is retried rewrites the same object, and the same `event_id` can appear in more than one object, so consumers must deduplicate on `event_id`. Each event-time window is held for ten minutes before it commits; a row that becomes visible after its window is committed may not be delivered. + + Objects are written as `/destination_id=/org_id=/date=/hour=/-.jsonl.gz`, where `date` and `hour` are the UTC calendar hour that fully contains every row in the object, so the layout is safe to register as a Hive-partitioned table. The object name is derived from the rows it holds, so a retried delivery rewrites its own object. + required: + - id + - type + - region + - bucket + - prefix + - role_arn + - external_id + - kernel_role_arn + - format + - status + - consecutive_failures + - created_at + - updated_at + properties: + id: + type: string + maxLength: 128 + readOnly: true + x-go-type-skip-optional-pointer: true + type: + type: string + enum: + - s3 + region: + type: string + minLength: 1 + maxLength: 128 + bucket: + type: string + minLength: 3 + maxLength: 63 + prefix: + type: string + maxLength: 512 + role_arn: + type: string + minLength: 1 + maxLength: 2048 + external_id: + type: string + maxLength: 128 + readOnly: true + x-go-type-skip-optional-pointer: true + kernel_role_arn: + type: string + maxLength: 2048 + description: |- + The Kernel role that assumes `role_arn` in your account to deliver logs. Allow this role as the principal in your role's trust policy, and require `external_id` as the `sts:ExternalId` condition. + + Recreating a destination issues a new `external_id`, which the trust policy has to be updated to match. + readOnly: true + x-go-type-skip-optional-pointer: true + kms_key_id: + type: string + maxLength: 2048 + format: + type: string + enum: + - jsonl.gz + status: + type: string + enum: + - active + - paused + description: Pausing prevents new delivery attempts. An S3 upload already in progress may complete after the pause response; its rows can appear again after the destination is resumed. + last_exported_cursor: + type: string + description: |- + Opaque, versioned checkpoint for forward-only continuous export. This value is not compatible with audit-log list page tokens. + + Delivery starts at the moment the destination is activated, so events recorded before that are not delivered. Pausing stops delivery and resuming starts again from the time of the resume: events recorded while a destination was paused are never exported, and pausing is not a way to defer delivery. + readOnly: true + last_success_at: + type: string + format: date-time + readOnly: true + last_error: + type: string + description: Sanitized description of the most recent delivery failure. + readOnly: true + last_error_at: + type: string + format: date-time + readOnly: true + consecutive_failures: + type: integer + minimum: 0 + readOnly: true + x-go-type-skip-optional-pointer: true + x-omitempty: false + next_attempt_at: + type: string + format: date-time + readOnly: true + created_at: + type: string + format: date-time + readOnly: true + x-go-type-skip-optional-pointer: true + updated_at: + type: string + format: date-time + readOnly: true + x-go-type-skip-optional-pointer: true + additionalProperties: false + CreateAuditLogExportDestinationRequest: + type: object + required: + - type + - region + - bucket + - prefix + - role_arn + - format + properties: + type: + type: string + enum: + - s3 + region: + type: string + minLength: 1 + maxLength: 128 + bucket: + type: string + minLength: 3 + maxLength: 63 + prefix: + type: string + maxLength: 512 + role_arn: + type: string + minLength: 1 + maxLength: 2048 + kms_key_id: + type: string + maxLength: 2048 + format: + type: string + enum: + - jsonl.gz + additionalProperties: false + UpdateAuditLogExportDestinationRequest: + type: object + properties: + region: + type: string + minLength: 1 + maxLength: 128 + bucket: + type: string + minLength: 3 + maxLength: 63 + prefix: + type: string + maxLength: 512 + role_arn: + type: string + minLength: 1 + maxLength: 2048 + kms_key_id: + type: string + maxLength: 2048 + description: KMS key ID, alias, or ARN. Set to an empty string to remove the configured KMS key; omit or send null to leave unchanged. + status: + type: string + enum: + - active + - paused + additionalProperties: false + AuditLogExportDestinationTestResult: + type: object + required: + - success + - stage + properties: + success: + type: boolean + stage: + type: string + enum: + - assume_role + - put_object + - complete + error: + type: object + required: + - code + - message + properties: + code: + type: string + enum: + - assume_role_failed + - put_object_failed + message: + type: string + additionalProperties: false + additionalProperties: false + AuditLogEntry: + type: object + required: + - timestamp + - auth_strategy + - user_id + - email + - status + - method + - path + - route + - domain + - duration_ms + - client_ip + - user_agent + properties: + timestamp: + type: string + format: date-time + description: UTC time when the request was received. + auth_strategy: + type: string + description: Authentication strategy used for the request. + user_id: + type: string + description: ID of the authenticated user, if any. + email: + type: string + description: Email of the authenticated user at request time, if any. + status: + type: integer + description: HTTP response status code. + method: + type: string + description: HTTP method. + path: + type: string + description: Request path. + route: + type: string + description: Matched API route pattern, if available. + domain: + type: string + description: Request host. + duration_ms: + type: integer + description: Request duration in milliseconds. + client_ip: + type: string + description: Client IP address. + user_agent: + type: string + description: User agent header. + Project: + type: object + required: + - id + - name + - status + - created_at + - updated_at + properties: + id: + type: string + description: Unique project identifier + example: proj_abc123 + name: + type: string + description: Project name + example: production + status: + type: string + enum: + - active + - archived + description: Project status + example: active + created_at: + type: string + format: date-time + description: When the project was created + updated_at: + type: string + format: date-time + description: When the project was last updated + CreateProjectRequest: + type: object + required: + - name + properties: + name: + type: string + description: Project name (1-255 Unicode code points) + minLength: 1 + maxLength: 255 + example: staging + UpdateProjectRequest: + type: object + properties: + name: + type: string + description: New project name (1-255 Unicode code points) + minLength: 1 + maxLength: 255 + status: + type: string + enum: + - active + - archived + description: New project status + ProjectLimits: + type: object + properties: + max_concurrent_sessions: + type: integer + nullable: true + description: Maximum concurrent browsers for this project, covering both on-demand sessions (`browsers.create()`) and browser pool reservations. Null means no project-level cap. + example: 10 + max_concurrent_invocations: + type: integer + nullable: true + description: Maximum concurrent app invocations for this project. Null means no project-level cap. + example: 20 + max_pooled_sessions: + type: integer + nullable: true + deprecated: true + description: 'Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Always null.' + example: 50 + UpdateProjectLimitsRequest: + type: object + properties: + max_concurrent_sessions: + type: integer + nullable: true + description: Maximum concurrent browsers for this project, covering both on-demand sessions and browser pool reservations. Set to 0 to remove the cap; omit to leave unchanged. + max_concurrent_invocations: + type: integer + nullable: true + description: Maximum concurrent app invocations for this project. Set to 0 to remove the cap; omit to leave unchanged. + max_pooled_sessions: + type: integer + nullable: true + deprecated: true + description: 'Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Requests that set this field are rejected with a 400.' + OrgLimits: + type: object + properties: + max_concurrent_sessions: + type: integer + description: The organization's effective concurrency limit — the maximum browsers running at once, covering both on-demand sessions and browser pool reservations — from its plan or an override. Read-only and shared across all projects in the org; a per-project default cannot exceed it. + example: 500 + default_project_max_concurrent_sessions: + type: integer + nullable: true + description: Default maximum concurrent browsers applied to every project that has no explicit per-project override. Null means no org-level default, so such projects are uncapped (only the org-wide limit applies). Applies to existing and newly created projects. + example: 10 + UpdateOrgLimitsRequest: + type: object + properties: + default_project_max_concurrent_sessions: + type: integer + nullable: true + description: Default maximum concurrent browsers for projects without an explicit override. Set to 0 to remove the default; omit to leave unchanged. Cannot exceed the organization's concurrency limit. + responses: + Unauthorized: + description: Unauthorized – missing or invalid authorization token + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + BadRequest: + description: Bad Request – invalid input + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + NotFound: + description: Resource not found + 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' + Conflict: + description: Conflict – resource already exists + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + Forbidden: + description: Forbidden – insufficient permissions or plan + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + UnprocessableEntity: + description: Unprocessable Entity – request was valid but the operation failed + 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' + Gone: + description: Resource expired or no longer available + content: + application/json: + schema: + $ref: '#/components/schemas/Error' +security: + - bearerAuth: [] +tags: + - name: Browsers + description: Create and manage browser sessions. + - 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 Filesystem + description: Read, write, and manage files on the browser instance. + - name: Browser Processes + description: Execute and manage processes on the browser instance. + - name: Browser Replays + description: Record and manage browser session video replays. + - name: Browser Logs + description: Stream logs from the browser instance. + - name: Browser Telemetry + description: Stream live telemetry events from a browser session. + - name: Profiles + description: Create, list, retrieve, and delete browser profiles. + - name: Proxies + description: Create and manage proxy configurations for routing browser traffic. + - name: Extensions + description: Create, list, retrieve, and delete browser extensions. + - 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: Organization + description: Read and manage organization-level limits. + - name: Projects + description: | + Create and manage projects for resource isolation within an organization. + When projects are disabled for the organization, project operations return + `404` with code `projects_disabled`. + - name: API Keys + description: Create and manage API keys for organization and project-scoped access. + - name: Audit Logs + description: Read audit log records for the authenticated organization. +paths: + /browsers: + post: + operationId: postBrowsers + tags: + - Browsers + summary: Create a browser session + description: Create a new browser session from within an action. + security: + - bearerAuth: [] + 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' + "409": + $ref: '#/components/responses/Conflict' + "429": + $ref: '#/components/responses/TooManyRequests' + "500": + $ref: '#/components/responses/InternalError' + "529": + $ref: '#/components/responses/CapacityExhausted' + 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 + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + browser, err := client.Browsers.New(context.TODO(), kernel.BrowserNewParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", browser.SessionID) + } + get: + operationId: getBrowsers + tags: + - Browsers + summary: List browser sessions + description: List all browser sessions with pagination support. Use status parameter to filter by session state. + security: + - bearerAuth: [] + parameters: + - name: status + in: query + required: false + description: Filter sessions by status. "active" returns only active sessions (default), "deleted" returns only soft-deleted sessions, "all" returns both. + schema: + type: string + enum: + - active + - deleted + - all + default: active + - name: include_deleted + in: query + required: false + deprecated: true + description: 'Deprecated: Use status=all instead. When true, includes soft-deleted browser sessions in the results alongside active sessions.' + schema: + type: boolean + default: false + - name: limit + in: query + required: false + description: Maximum number of results to return. Defaults to 20, maximum 100. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Number of results to skip. Defaults to 0. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Search browsers by name, session ID, profile name or ID, proxy ID, or pool name. + schema: + type: string + - name: tags + in: query + required: false + style: deepObject + explode: true + description: | + Filter sessions by tag key-value pairs using deepObject style, e.g. ?tags[team]=backend&tags[env]=staging. Multiple pairs are ANDed: a session must match every supplied pair exactly. + schema: + type: object + additionalProperties: + type: string + responses: + "200": + description: List of browsers + headers: + X-Limit: + description: The limit used for pagination + schema: + type: integer + X-Offset: + description: The offset used for pagination + schema: + type: integer + X-Has-More: + description: Whether more results are available + schema: + type: boolean + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Browser' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const browserListResponse of client.browsers.list()) { + console.log(browserListResponse.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 + ) + page = client.browsers.list() + page = page.items[0] + print(page.session_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Browsers.List(context.TODO(), kernel.BrowserListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /browsers/{id_or_name}: + get: + operationId: getBrowsersByIdOrName + tags: + - Browsers + summary: Get browser session details + description: Get information about a browser session. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser session ID or name + example: htzv5orfit78e1m2biiifpbv + - name: include_deleted + in: query + required: false + description: When true, includes soft-deleted browser sessions in the lookup. + schema: + type: boolean + default: false + responses: + "200": + description: Browser session retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Browser' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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.retrieve('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.retrieve( + id_or_name="htzv5orfit78e1m2biiifpbv", + ) + print(browser.session_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + browser, err := client.Browsers.Get( + context.TODO(), + "htzv5orfit78e1m2biiifpbv", + kernel.BrowserGetParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", browser.SessionID) + } + patch: + operationId: patchBrowsersByIdOrName + tags: + - Browsers + summary: Update browser session + description: Update a browser session. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser session ID or name + 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' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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_or_name="htzv5orfit78e1m2biiifpbv", + ) + print(browser.session_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + browser, err := client.Browsers.Update( + context.TODO(), + "htzv5orfit78e1m2biiifpbv", + kernel.BrowserUpdateParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", browser.SessionID) + } + delete: + operationId: deleteBrowsersByIdOrName + tags: + - Browsers + summary: Delete a browser session by ID or name. + description: Delete a browser session by ID or name + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser session ID or name + example: htzv5orfit78e1m2biiifpbv + responses: + "204": + description: Browser session deleted successfully + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.deleteByID('htzv5orfit78e1m2biiifpbv'); + - 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 + ) + client.browsers.delete_by_id( + "htzv5orfit78e1m2biiifpbv", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.DeleteByID(context.TODO(), "htzv5orfit78e1m2biiifpbv") + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/extensions: + post: + operationId: uploadExtensionsToBrowser + tags: + - Browsers + summary: Ad-hoc upload one or more unpacked extensions to a running browser instance. + description: Loads one or more unpacked extensions and restarts Chromium on the browser instance. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + extensions: + type: array + description: List of extensions to upload and activate + items: + type: object + properties: + zip_file: + type: string + format: binary + description: Zip archive containing an unpacked Chromium extension (must include manifest.json) + name: + type: string + description: Folder name to place the extension under /home/kernel/extensions/ + minLength: 1 + maxLength: 255 + pattern: ^[a-zA-Z0-9._-]{1,255}$ + required: + - zip_file + - name + required: + - extensions + responses: + "201": + description: Extensions uploaded, Chromium restarted, and DevTools is ready + "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' + 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 + }); + + await client.browsers.loadExtensions('id', { + extensions: [{ name: 'name', zip_file: fs.createReadStream('path/to/file') }], + }); + - 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 + ) + client.browsers.load_extensions( + id="id", + extensions=[{ + "name": "name", + "zip_file": b"Example data", + }], + ) + - lang: Go + source: | + package main + + import ( + "bytes" + "context" + "io" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.LoadExtensions( + context.TODO(), + "id", + kernel.BrowserLoadExtensionsParams{ + Extensions: []kernel.BrowserLoadExtensionsParamsExtension{{ + Name: "name", + ZipFile: io.Reader(bytes.NewBuffer([]byte("Example data"))), + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/curl: + post: + summary: Make an HTTP request through the browser's network stack + description: | + Sends an HTTP request through Chrome's HTTP request stack, inheriting + the browser's TLS fingerprint, cookies, proxy configuration, and headers. + Returns a structured JSON response with status, headers, body, and timing. + operationId: browserCurl + tags: + - Browsers + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserCurlRequest' + responses: + "200": + description: Response from target URL + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserCurlResult' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + "502": + description: Upstream transport failure + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserCurlTransportError' + 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 response = await client.browsers.curl('id', { url: 'url' }); + + console.log(response.body); + - 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 + ) + response = client.browsers.curl( + id="id", + url="url", + ) + print(response.body) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Curl( + context.TODO(), + "id", + kernel.BrowserCurlParams{ + URL: "url", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Body) + } + /browsers/{id}/computer/click_mouse: + post: + summary: Simulate a mouse click action on the browser instance + operationId: clickMouse + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ClickMouseRequest' + responses: + "200": + description: Mouse action performed + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.clickMouse('id', { x: 0, y: 0 }); + - 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 + ) + client.browsers.computer.click_mouse( + id="id", + x=0, + y=0, + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.ClickMouse( + context.TODO(), + "id", + kernel.BrowserComputerClickMouseParams{ + X: 0, + Y: 0, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/move_mouse: + post: + summary: Move the mouse cursor to the specified coordinates on the browser instance + operationId: moveMouse + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/MoveMouseRequest' + responses: + "200": + description: Mouse cursor moved + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.moveMouse('id', { x: 0, y: 0 }); + - 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 + ) + client.browsers.computer.move_mouse( + id="id", + x=0, + y=0, + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.MoveMouse( + context.TODO(), + "id", + kernel.BrowserComputerMoveMouseParams{ + X: 0, + Y: 0, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/screenshot: + post: + summary: Capture a screenshot of the browser instance + operationId: takeScreenshot + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/ScreenshotRequest' + responses: + "200": + description: Screenshot image + content: + image/png: + schema: + type: string + format: binary + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.computer.captureScreenshot('id'); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.browsers.computer.capture_screenshot( + id="id", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Computer.CaptureScreenshot( + context.TODO(), + "id", + kernel.BrowserComputerCaptureScreenshotParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /browsers/{id}/computer/type: + post: + summary: Type text on the browser instance + operationId: typeText + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TypeTextRequest' + responses: + "200": + description: Text typed successfully + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.typeText('id', { text: 'text' }); + - 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 + ) + client.browsers.computer.type_text( + id="id", + text="text", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.TypeText( + context.TODO(), + "id", + kernel.BrowserComputerTypeTextParams{ + Text: "text", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/press_key: + post: + summary: Press one or more keys on the host computer + operationId: pressKey + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PressKeyRequest' + responses: + "200": + description: Keys pressed successfully + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.pressKey('id', { keys: ['string'] }); + - 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 + ) + client.browsers.computer.press_key( + id="id", + keys=["string"], + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.PressKey( + context.TODO(), + "id", + kernel.BrowserComputerPressKeyParams{ + Keys: []string{"string"}, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/scroll: + post: + summary: Scroll the mouse wheel at a position on the host computer + operationId: scroll + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ScrollRequest' + responses: + "200": + description: Scroll performed + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.scroll('id', { x: 0, y: 0 }); + - 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 + ) + client.browsers.computer.scroll( + id="id", + x=0, + y=0, + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.Scroll( + context.TODO(), + "id", + kernel.BrowserComputerScrollParams{ + X: 0, + Y: 0, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/drag_mouse: + post: + summary: Drag the mouse along a path + operationId: dragMouse + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DragMouseRequest' + responses: + "200": + description: Drag performed + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.dragMouse('id', { + path: [ + [0, 0], + [0, 0], + ], + }); + - 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 + ) + client.browsers.computer.drag_mouse( + id="id", + path=[[0, 0], [0, 0]], + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.DragMouse( + context.TODO(), + "id", + kernel.BrowserComputerDragMouseParams{ + Path: [][]int64{{0, 0}, {0, 0}}, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/cursor: + post: + summary: Set cursor visibility + operationId: setCursor + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SetCursorRequest' + responses: + "200": + description: Cursor visibility set + content: + application/json: + schema: + $ref: '#/components/schemas/OkResponse' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.computer.setCursorVisibility('id', { hidden: true }); + + console.log(response.ok); + - 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 + ) + response = client.browsers.computer.set_cursor_visibility( + id="id", + hidden=True, + ) + print(response.ok) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Computer.SetCursorVisibility( + context.TODO(), + "id", + kernel.BrowserComputerSetCursorVisibilityParams{ + Hidden: true, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Ok) + } + /browsers/{id}/computer/batch: + post: + summary: Execute a batch of computer actions sequentially + description: | + Send an array of computer actions to execute in order on the browser instance. + Execution stops on the first error. This reduces network latency compared to + sending individual action requests. + operationId: batchComputerAction + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BatchComputerActionRequest' + responses: + "200": + description: All actions executed successfully + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.batch('id', { actions: [{ type: 'click_mouse' }] }); + - 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 + ) + client.browsers.computer.batch( + id="id", + actions=[{ + "type": "click_mouse" + }], + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.Batch( + context.TODO(), + "id", + kernel.BrowserComputerBatchParams{ + Actions: []kernel.BrowserComputerBatchParamsAction{{ + Type: "click_mouse", + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/computer/get_mouse_position: + post: + summary: Get the current mouse cursor position on the browser instance + operationId: getMousePosition + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + responses: + "200": + description: Current mouse position + content: + application/json: + schema: + $ref: '#/components/schemas/MousePositionResponse' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.computer.getMousePosition('id'); + + console.log(response.x); + - 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 + ) + response = client.browsers.computer.get_mouse_position( + "id", + ) + print(response.x) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Computer.GetMousePosition(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.X) + } + /browsers/{id}/computer/clipboard/read: + post: + summary: Read text from the clipboard on the browser instance + operationId: readClipboard + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + responses: + "200": + description: Clipboard content read successfully + content: + application/json: + schema: + $ref: '#/components/schemas/ClipboardContent' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.computer.readClipboard('id'); + + console.log(response.text); + - 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 + ) + response = client.browsers.computer.read_clipboard( + "id", + ) + print(response.text) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Computer.ReadClipboard(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Text) + } + /browsers/{id}/computer/clipboard/write: + post: + summary: Write text to the clipboard on the browser instance + operationId: writeClipboard + tags: + - Browser Computer Controls + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WriteClipboardRequest' + responses: + "200": + description: Text written to clipboard successfully + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.computer.writeClipboard('id', { text: 'text' }); + - 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 + ) + client.browsers.computer.write_clipboard( + id="id", + text="text", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Computer.WriteClipboard( + context.TODO(), + "id", + kernel.BrowserComputerWriteClipboardParams{ + Text: "text", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/playwright/execute: + post: + summary: Execute Playwright/TypeScript code against the browser + description: | + Execute arbitrary Playwright code in a fresh execution context against the browser. + The code runs in the same VM as the browser, minimizing latency and maximizing throughput. + It has access to 'page', 'context', and 'browser' variables. + It can `return` a value, and this value is returned in the response. + operationId: executePlaywrightCode + tags: + - Browser Playwright + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExecutePlaywrightRequest' + responses: + "200": + description: Code executed successfully + content: + application/json: + schema: + $ref: '#/components/schemas/ExecutePlaywrightResult' + "400": + $ref: '#/components/responses/BadRequest' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.playwright.execute('id', { code: 'code' }); + + console.log(response.success); + - 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 + ) + response = client.browsers.playwright.execute( + id="id", + code="code", + ) + print(response.success) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Playwright.Execute( + context.TODO(), + "id", + kernel.BrowserPlaywrightExecuteParams{ + Code: "code", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Success) + } + /browsers/{id}/fs/read_file: + get: + summary: Read file contents + operationId: readFile + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: path + in: query + required: true + schema: + type: string + pattern: ^/.* + description: Absolute file path to read. + responses: + "200": + description: File read successfully + content: + application/octet-stream: + schema: + type: string + format: binary + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.fs.readFile('id', { path: '/J!' }); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.browsers.fs.read_file( + id="id", + path="/J!", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Fs.ReadFile( + context.TODO(), + "id", + kernel.BrowserFReadFileParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /browsers/{id}/fs/write_file: + put: + summary: Write or create a file + operationId: writeFile + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: path + in: query + required: true + schema: + type: string + pattern: ^/.* + description: Destination absolute file path. + - name: mode + in: query + required: false + schema: + type: string + pattern: ^[0-7]{3,4}$ + description: Optional file mode (octal string, e.g. 644). Defaults to 644. + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + "201": + description: File written successfully + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.writeFile('id', fs.createReadStream('path/to/file'), { path: '/J!' }); + - 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 + ) + client.browsers.fs.write_file( + id="id", + contents=b"Example data", + path="/J!", + ) + - lang: Go + source: | + package main + + import ( + "bytes" + "context" + "io" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.WriteFile( + context.TODO(), + "id", + io.Reader(bytes.NewBuffer([]byte("Example data"))), + kernel.BrowserFWriteFileParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/list_files: + get: + summary: List files in a directory + operationId: listFiles + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: path + in: query + required: true + schema: + type: string + pattern: ^/.* + description: Absolute directory path. + responses: + "200": + description: Directory listing + content: + application/json: + schema: + $ref: '#/components/schemas/ListFiles' + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.fs.listFiles('id', { path: '/J!' }); + + console.log(response); + - 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 + ) + response = client.browsers.fs.list_files( + id="id", + path="/J!", + ) + print(response) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Fs.ListFiles( + context.TODO(), + "id", + kernel.BrowserFListFilesParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /browsers/{id}/fs/create_directory: + put: + summary: Create a new directory + operationId: createDirectory + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDirectoryRequest' + responses: + "201": + description: Directory created successfully + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.createDirectory('id', { path: '/J!' }); + - 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 + ) + client.browsers.fs.create_directory( + id="id", + path="/J!", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.NewDirectory( + context.TODO(), + "id", + kernel.BrowserFNewDirectoryParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/delete_file: + put: + summary: Delete a file + operationId: deleteFile + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeletePathRequest' + responses: + "200": + description: File deleted + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.deleteFile('id', { path: '/J!' }); + - 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 + ) + client.browsers.fs.delete_file( + id="id", + path="/J!", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.DeleteFile( + context.TODO(), + "id", + kernel.BrowserFDeleteFileParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/delete_directory: + put: + summary: Delete a directory + operationId: deleteDirectory + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeletePathRequest' + responses: + "200": + description: Directory deleted + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.deleteDirectory('id', { path: '/J!' }); + - 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 + ) + client.browsers.fs.delete_directory( + id="id", + path="/J!", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.DeleteDirectory( + context.TODO(), + "id", + kernel.BrowserFDeleteDirectoryParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/set_file_permissions: + put: + summary: Set file or directory permissions/ownership + operationId: setFilePermissions + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SetFilePermissionsRequest' + responses: + "200": + description: Permissions updated + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.setFilePermissions('id', { mode: '0611', path: '/J!' }); + - 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 + ) + client.browsers.fs.set_file_permissions( + id="id", + mode="0611", + path="/J!", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.SetFilePermissions( + context.TODO(), + "id", + kernel.BrowserFSetFilePermissionsParams{ + Mode: "0611", + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/file_info: + get: + summary: Get information about a file or directory + operationId: fileInfo + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: path + in: query + required: true + schema: + type: string + pattern: ^/.* + description: Absolute path of the file or directory. + responses: + "200": + description: File information + content: + application/json: + schema: + $ref: '#/components/schemas/FileInfo' + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.fs.fileInfo('id', { path: '/J!' }); + + console.log(response.is_dir); + - 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 + ) + response = client.browsers.fs.file_info( + id="id", + path="/J!", + ) + print(response.is_dir) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Fs.FileInfo( + context.TODO(), + "id", + kernel.BrowserFFileInfoParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.IsDir) + } + /browsers/{id}/fs/move: + put: + summary: Move or rename a file or directory + operationId: movePath + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/MovePathRequest' + responses: + "200": + description: Move successful + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.move('id', { dest_path: '/J!', src_path: '/J!' }); + - 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 + ) + client.browsers.fs.move( + id="id", + dest_path="/J!", + src_path="/J!", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.Move( + context.TODO(), + "id", + kernel.BrowserFMoveParams{ + DestPath: "/J!", + SrcPath: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/watch: + post: + summary: Watch a directory for changes + operationId: startFsWatch + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StartFsWatchRequest' + responses: + "201": + description: Watch started successfully + content: + application/json: + schema: + type: object + properties: + watch_id: + type: string + description: Unique identifier for the directory watch + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.fs.watch.start('id', { path: 'path' }); + + console.log(response.watch_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 + ) + response = client.browsers.fs.watch.start( + id="id", + path="path", + ) + print(response.watch_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Fs.Watch.Start( + context.TODO(), + "id", + kernel.BrowserFWatchStartParams{ + Path: "path", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.WatchID) + } + /browsers/{id}/fs/watch/{watch_id}/events: + get: + summary: Stream filesystem events for a watch + operationId: streamFsEvents + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: watch_id + in: path + required: true + schema: + type: string + responses: + "200": + description: SSE stream of filesystem events + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (application/json) + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/FileSystemEvent' + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.fs.watch.events('watch_id', { id: 'id' }); + + console.log(response.path); + - 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 + ) + for watch in client.browsers.fs.watch.events( + watch_id="watch_id", + id="id", + ): + print(watch) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Browsers.Fs.Watch.EventsStreaming( + context.TODO(), + "watch_id", + kernel.BrowserFWatchEventsParams{ + ID: "id", + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/watch/{watch_id}: + delete: + summary: Stop watching a directory + operationId: stopFsWatch + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: watch_id + in: path + required: true + schema: + type: string + responses: + "204": + description: Watch stopped successfully + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.watch.stop('watch_id', { id: '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 + ) + client.browsers.fs.watch.stop( + watch_id="watch_id", + id="id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.Watch.Stop( + context.TODO(), + "watch_id", + kernel.BrowserFWatchStopParams{ + ID: "id", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/download_dir_zip: + get: + summary: Download a directory as a ZIP archive + description: Returns a ZIP file containing the contents of the specified directory. + operationId: downloadDirZip + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: path + in: query + required: true + schema: + type: string + pattern: ^/.* + description: Absolute directory path to archive and download. + responses: + "200": + description: ZIP archive of the requested directory + content: + application/zip: + schema: + type: string + format: binary + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.fs.downloadDirZip('id', { path: '/J!' }); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.browsers.fs.download_dir_zip( + id="id", + path="/J!", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Fs.DownloadDirZip( + context.TODO(), + "id", + kernel.BrowserFDownloadDirZipParams{ + Path: "/J!", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /browsers/{id}/fs/upload: + post: + summary: Upload one or more files + description: Allows uploading single or multiple files to the remote filesystem. + operationId: uploadFiles + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: object + properties: + file: + type: string + format: binary + dest_path: + type: string + description: Absolute destination path to write the file. + pattern: ^/.* + required: + - file + - dest_path + required: + - files + responses: + "201": + description: Files uploaded successfully + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.fs.upload('id', { + files: [{ dest_path: '/J!', file: fs.createReadStream('path/to/file') }], + }); + - 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 + ) + client.browsers.fs.upload( + id="id", + files=[{ + "dest_path": "/J!", + "file": b"Example data", + }], + ) + - lang: Go + source: | + package main + + import ( + "bytes" + "context" + "io" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.Upload( + context.TODO(), + "id", + kernel.BrowserFUploadParams{ + Files: []kernel.BrowserFUploadParamsFile{{ + DestPath: "/J!", + File: io.Reader(bytes.NewBuffer([]byte("Example data"))), + }}, + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/fs/upload_zip: + post: + summary: Upload a zip archive and extract it + description: Upload a zip file and extract its contents to the specified destination path. + operationId: uploadZip + tags: + - Browser Filesystem + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + zip_file: + type: string + format: binary + dest_path: + type: string + description: Absolute destination directory to extract the archive to. + pattern: ^/.* + required: + - zip_file + - dest_path + responses: + "201": + description: Zip uploaded and extracted successfully + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + x-codeSamples: + - lang: JavaScript + source: |- + import fs from 'fs'; + import Kernel from '@onkernel/sdk'; + + const client = new Kernel({ + apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted + }); + + await client.browsers.fs.uploadZip('id', { + dest_path: '/J!', + zip_file: fs.createReadStream('path/to/file'), + }); + - 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 + ) + client.browsers.fs.upload_zip( + id="id", + dest_path="/J!", + zip_file=b"Example data", + ) + - lang: Go + source: | + package main + + import ( + "bytes" + "context" + "io" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Fs.UploadZip( + context.TODO(), + "id", + kernel.BrowserFUploadZipParams{ + DestPath: "/J!", + ZipFile: io.Reader(bytes.NewBuffer([]byte("Example data"))), + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/process/exec: + post: + summary: Execute a command synchronously + operationId: processExec + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessExecRequest' + responses: + "200": + description: Execution result + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessExecResult' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.exec('id', { command: 'command' }); + + console.log(response.duration_ms); + - 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 + ) + response = client.browsers.process.exec( + id="id", + command="command", + ) + print(response.duration_ms) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Process.Exec( + context.TODO(), + "id", + kernel.BrowserProcessExecParams{ + Command: "command", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.DurationMs) + } + /browsers/{id}/process/spawn: + post: + summary: Execute a command asynchronously + operationId: processSpawn + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessSpawnRequest' + responses: + "200": + description: Spawned + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessSpawnResult' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.spawn('id', { command: 'command' }); + + console.log(response.pid); + - 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 + ) + response = client.browsers.process.spawn( + id="id", + command="command", + ) + print(response.pid) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Process.Spawn( + context.TODO(), + "id", + kernel.BrowserProcessSpawnParams{ + Command: "command", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Pid) + } + /browsers/{id}/process/{process_id}/status: + get: + summary: Get process status + operationId: processStatus + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: process_id + in: path + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Status + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessStatus' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.status('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { + id: 'id', + }); + + console.log(response.cpu_pct); + - 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 + ) + response = client.browsers.process.status( + process_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + id="id", + ) + print(response.cpu_pct) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Process.Status( + context.TODO(), + "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + kernel.BrowserProcessStatusParams{ + ID: "id", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.CPUPct) + } + /browsers/{id}/process/{process_id}/stdout/stream: + get: + summary: Stream process stdout via SSE + operationId: processStdoutStream + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: process_id + in: path + required: true + schema: + type: string + format: uuid + responses: + "200": + description: SSE stream of process output and lifecycle events + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (application/json) + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/ProcessStreamEvent' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.stdoutStream( + '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', + { id: 'id' }, + ); + + console.log(response.data_b64); + - 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 + ) + for process in client.browsers.process.stdout_stream( + process_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + id="id", + ): + print(process) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Browsers.Process.StdoutStreamStreaming( + context.TODO(), + "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + kernel.BrowserProcessStdoutStreamParams{ + ID: "id", + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/process/{process_id}/stdin: + post: + summary: Write to process stdin + operationId: processStdin + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: process_id + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessStdinRequest' + responses: + "200": + description: Bytes written + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessStdinResult' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.stdin('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { + id: 'id', + data_b64: 'data_b64', + }); + + console.log(response.written_bytes); + - 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 + ) + response = client.browsers.process.stdin( + process_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + id="id", + data_b64="data_b64", + ) + print(response.written_bytes) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Process.Stdin( + context.TODO(), + "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + kernel.BrowserProcessStdinParams{ + ID: "id", + DataB64: "data_b64", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.WrittenBytes) + } + /browsers/{id}/process/{process_id}/kill: + post: + summary: Send signal to process + operationId: processKill + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: process_id + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessKillRequest' + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/OkResponse' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.kill('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { + id: 'id', + signal: 'TERM', + }); + + console.log(response.ok); + - 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 + ) + response = client.browsers.process.kill( + process_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + id="id", + signal="TERM", + ) + print(response.ok) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Process.Kill( + context.TODO(), + "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + kernel.BrowserProcessKillParams{ + ID: "id", + Signal: kernel.BrowserProcessKillParamsSignalTerm, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Ok) + } + /browsers/{id}/process/{process_id}/resize: + post: + summary: Resize a PTY-backed process terminal + operationId: processResize + tags: + - Browser Processes + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: process_id + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProcessResizeRequest' + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/OkResponse' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.process.resize('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { + id: 'id', + cols: 1, + rows: 1, + }); + + console.log(response.ok); + - 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 + ) + response = client.browsers.process.resize( + process_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + id="id", + cols=1, + rows=1, + ) + print(response.ok) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Process.Resize( + context.TODO(), + "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", + kernel.BrowserProcessResizeParams{ + ID: "id", + Cols: 1, + Rows: 1, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Ok) + } + /browsers/{id}/replays: + post: + operationId: startBrowserReplayRecording + tags: + - Browser Replays + summary: Start a browser session replay recording + description: Start recording the browser session and return a replay ID. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: Browser session ID + schema: + type: string + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + framerate: + type: integer + description: Recording framerate in fps. Values above 20 require GPU to be enabled on the browser session. + minimum: 1 + maximum: 60 + max_duration_in_seconds: + type: integer + description: Maximum recording duration in seconds. + minimum: 1 + record_audio: + type: boolean + description: Record audio in addition to video. When false (the default), the recording is video-only. + default: false + responses: + "201": + description: Recording started successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserReplay' + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.replays.start('id'); + + console.log(response.replay_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 + ) + response = client.browsers.replays.start( + id="id", + ) + print(response.replay_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Replays.Start( + context.TODO(), + "id", + kernel.BrowserReplayStartParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.ReplayID) + } + get: + operationId: listBrowsersReplays + tags: + - Browser Replays + summary: List browser session replays + description: List all replays for the specified browser session. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: Browser session ID + schema: + type: string + responses: + "200": + description: List of replays retrieved successfully. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/BrowserReplay' + "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' + 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 replays = await client.browsers.replays.list('id'); + + console.log(replays); + - 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 + ) + replays = client.browsers.replays.list( + "id", + ) + print(replays) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + replays, err := client.Browsers.Replays.List(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", replays) + } + /browsers/{id}/replays/{replay_id}: + get: + operationId: getBrowsersReplaysById + tags: + - Browser Replays + summary: Download a replay recording + description: Download or stream the specified replay recording. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: Browser session ID + schema: + type: string + - name: replay_id + in: path + required: true + description: Replay recording identifier + schema: + type: string + responses: + "200": + description: Replay recording retrieved successfully. + content: + video/mp4: + schema: + type: string + format: binary + "202": + description: Replay recording is still in progress, please try again later + headers: + Retry-After: + description: Suggested wait time in seconds before retrying + schema: + type: integer + minimum: 1 + "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' + 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 response = await client.browsers.replays.download('replay_id', { id: 'id' }); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.browsers.replays.download( + replay_id="replay_id", + id="id", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Browsers.Replays.Download( + context.TODO(), + "replay_id", + kernel.BrowserReplayDownloadParams{ + ID: "id", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /browsers/{id}/replays/{replay_id}/stop: + post: + operationId: stopBrowserReplayRecording + tags: + - Browser Replays + summary: Stop a browser session replay recording + description: Stop the specified replay recording and persist the video. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: Browser session ID + schema: + type: string + - name: replay_id + in: path + required: true + description: Replay recording identifier + schema: + type: string + responses: + "200": + description: Recording stopped successfully. + "400": + $ref: '#/components/responses/BadRequest' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browsers.replays.stop('replay_id', { id: '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 + ) + client.browsers.replays.stop( + replay_id="replay_id", + id="id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Browsers.Replays.Stop( + context.TODO(), + "replay_id", + kernel.BrowserReplayStopParams{ + ID: "id", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/logs/stream: + get: + summary: Stream log files on the browser instance via SSE + operationId: logsStream + tags: + - Browser Logs + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - in: query + name: source + required: true + schema: + type: string + enum: + - path + - supervisor + - in: query + name: follow + required: false + schema: + type: boolean + default: true + - in: query + description: only required if source is path + name: path + required: false + schema: + type: string + - in: query + name: supervisor_process + description: only required if source is supervisor + required: false + schema: + type: string + responses: + "200": + description: SSE stream of logs + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (application/json) + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/LogEvent' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 logEvent = await client.browsers.logs.stream('id', { source: 'path' }); + + console.log(logEvent.event); + - 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 + ) + for log in client.browsers.logs.stream( + id="id", + source="path", + ): + print(log) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Browsers.Logs.StreamStreaming( + context.TODO(), + "id", + kernel.BrowserLogStreamParams{ + Source: kernel.BrowserLogStreamParamsSourcePath, + }, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/telemetry/stream: + get: + summary: Stream telemetry events via SSE + description: | + Streams browser telemetry events as a server-sent events (SSE) stream. The stream closes when the browser session terminates. Each event frame includes an id: field containing a monotonically increasing sequence number; pass it as Last-Event-ID on reconnect to resume without gaps. The event: field is never set; all frames carry JSON in the data: field. A keepalive comment frame is sent every 15 seconds when no events arrive. Returns 404 if the browser session does not exist. If telemetry was not enabled on the session, the stream opens but no events are delivered. Fresh connections only see new events; pass replay=all to start from the oldest retained event instead. + operationId: streamBrowserTelemetry + tags: + - Browser Telemetry + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: Last-Event-ID + in: header + schema: + type: string + description: Last event sequence number for SSE reconnection (sent by SSE clients on reconnect). Takes precedence over replay when both are present, so reconnect resumes instead of re-replaying. + - name: replay + in: query + schema: + type: string + description: Pass `all` to start from the oldest retained event instead of only new events; any other value is treated as from-now. The buffer is bounded, so the first event id may be greater than 1 if older events were evicted. + responses: + "200": + description: SSE stream of telemetry events + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (always application/json). + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/BrowserTelemetryEventEnvelope' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browsers.telemetry.stream('id'); + + console.log(response.event); + - 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 + ) + for telemetry in client.browsers.telemetry.stream( + id="id", + ): + print(telemetry) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Browsers.Telemetry.StreamStreaming( + context.TODO(), + "id", + kernel.BrowserTelemetryStreamParams{}, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /browsers/{id}/telemetry/events: + get: + summary: Read telemetry events for a browser session + description: | + Reads a page of telemetry events for the browser session. To page through results, pass the X-Next-Offset value from the previous response as offset and repeat while X-Has-More is true. Returns an empty list when telemetry data is unavailable. + operationId: readBrowserTelemetryEvents + tags: + - Browser Telemetry + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Browser session ID + - name: offset + in: query + required: false + description: | + Opaque pagination cursor: pass the X-Next-Offset value from the previous response to fetch the next page. When set, paging continues from this cursor and since is ignored, while until still bounds the page. It is not an event's seq field, so do not derive it from the response body. + schema: + type: integer + minimum: 0 + - name: since + in: query + required: false + description: | + Start of the window: an RFC-3339 timestamp, or a duration like 5m meaning that long ago. Defaults to 5m. Ignored when offset is set. + schema: + type: string + - name: until + in: query + required: false + description: | + End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m meaning that long ago. + schema: + type: string + - name: limit + in: query + required: false + description: Maximum number of events per page. Defaults to 20. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: category + in: query + required: false + description: Restrict results to these event categories. Repeat the parameter for multiple values. + schema: + type: array + items: + type: string + enum: + - console + - network + - page + - interaction + - control + - connection + - system + - screenshot + - captcha + - monitor + - name: order + in: query + required: false + description: | + Read direction. asc (default) reads oldest first, starting from since or the offset cursor. desc reads newest first: each request returns one page of up to limit records ending at the offset cursor (or until, or the newest archived event); combining desc with since is rejected with a 400. In either direction the category filter applies within the page, so a filtered page may be empty while X-Has-More is true. + schema: + type: string + default: asc + responses: + "200": + description: A page of telemetry events. + headers: + X-Has-More: + description: Whether more results are available + schema: + type: boolean + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/BrowserTelemetryEventEnvelope' + "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' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const telemetryEventsResponse of client.browsers.telemetry.events('id')) { + console.log(telemetryEventsResponse.event); + } + - 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 + ) + page = client.browsers.telemetry.events( + id="id", + ) + page = page.items[0] + print(page.event) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Browsers.Telemetry.Events( + context.TODO(), + "id", + kernel.BrowserTelemetryEventsParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /profiles: + post: + operationId: postProfiles + tags: + - Profiles + summary: Create a new profile + description: Create a browser profile that can be used to load state into future browser sessions. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProfileRequest' + responses: + "201": + description: Profile created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Profile' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 profile = await client.profiles.create(); + + console.log(profile.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 + ) + profile = client.profiles.create() + print(profile.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + profile, err := client.Profiles.New(context.TODO(), kernel.ProfileNewParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", profile.ID) + } + get: + operationId: getProfiles + tags: + - Profiles + summary: List profiles + description: List profiles with optional filtering and pagination. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + description: Limit the number of profiles to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of profiles to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Case-insensitive substring match against profile name or ID. + schema: + type: string + - name: name + in: query + required: false + description: Exact-match filter on profile name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project profile over a legacy unscoped profile with the same name. + schema: + type: string + responses: + "200": + description: List of profiles + headers: + X-Limit: + description: Limit the number of profiles to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of profiles to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more profiles to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Profile' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const profile of client.profiles.list()) { + console.log(profile.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 + ) + page = client.profiles.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Profiles.List(context.TODO(), kernel.ProfileListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /profiles/{id_or_name}: + get: + operationId: getProfileByIdOrName + tags: + - Profiles + summary: Get profile by ID or name + description: Retrieve details for a single profile by its ID or name. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Profile ID or name + responses: + "200": + description: Profile details + content: + application/json: + schema: + $ref: '#/components/schemas/Profile' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 profile = await client.profiles.retrieve('id_or_name'); + + console.log(profile.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 + ) + profile = client.profiles.retrieve( + "id_or_name", + ) + print(profile.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + profile, err := client.Profiles.Get(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", profile.ID) + } + patch: + operationId: patchProfileByIdOrName + tags: + - Profiles + summary: Rename profile by ID or name + description: Update a profile's name. Names must be unique within the logical project; during the default-project migration, unscoped profiles and profiles in the org default project are treated as the same project. Duplicate-name conflicts are checked before update but are best-effort because there is no backing unique index. Renaming a profile while a browser session references it by name may prevent that session's changes from saving; prefer renaming when the profile is not in use. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Profile ID or profile name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProfileUpdateRequest' + responses: + "200": + description: Profile updated + content: + application/json: + schema: + $ref: '#/components/schemas/Profile' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 profile = await client.profiles.update('id_or_name', { name: 'my-renamed-profile' }); + + console.log(profile.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 + ) + profile = client.profiles.update( + id_or_name="id_or_name", + name="my-renamed-profile", + ) + print(profile.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + profile, err := client.Profiles.Update( + context.TODO(), + "id_or_name", + kernel.ProfileUpdateParams{ + Name: "my-renamed-profile", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", profile.ID) + } + delete: + operationId: deleteProfileByIdOrName + tags: + - Profiles + summary: Delete profile by ID or name + description: Delete a profile by its ID or by its name. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Profile ID or profile name + responses: + "204": + description: Profile deleted successfully + "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' + 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 + }); + + await client.profiles.delete('id_or_name'); + - 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 + ) + client.profiles.delete( + "id_or_name", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Profiles.Delete(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + } + /profiles/{id_or_name}/download: + get: + operationId: downloadProfileByIdOrName + tags: + - Profiles + summary: Download profile archive + description: | + Downloads the profile in its stored format by default. Current profiles are returned as + zstd-compressed tar archives, while legacy profiles remain JSON. Set `format=tar` to + decompress current profiles during download; legacy profiles remain JSON. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Profile ID or name + - name: format + in: query + required: false + schema: + type: string + enum: + - tar.zst + - tar + default: tar.zst + description: Response format for current profile archives. Legacy profiles are always returned as JSON. + responses: + "200": + description: Profile data in the requested format, or JSON for a legacy profile. + headers: + Content-Disposition: + description: Attachment filename matching the returned profile format. + schema: + type: string + content: + application/octet-stream: + schema: + type: string + format: binary + application/zstd: + schema: + type: string + format: binary + application/x-tar: + schema: + type: string + format: binary + "202": + description: Profile exists but has not yet captured any state. Use it in a browser session first to capture state. + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.profiles.download('id_or_name'); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.profiles.download( + id_or_name="id_or_name", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Profiles.Download( + context.TODO(), + "id_or_name", + kernel.ProfileDownloadParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /proxies: + post: + operationId: postProxies + tags: + - Proxies + summary: Create a proxy + description: Create a new proxy configuration in the resolved project. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProxyCreateRequest' + responses: + "201": + description: Proxy created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Proxy' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + 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 proxy = await client.proxies.create({ type: 'datacenter' }); + + console.log(proxy.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 + ) + proxy = client.proxies.create( + type="datacenter", + ) + print(proxy.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + proxy, err := client.Proxies.New(context.TODO(), kernel.ProxyNewParams{ + Type: kernel.ProxyNewParamsTypeDatacenter, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", proxy.ID) + } + get: + operationId: getProxies + tags: + - Proxies + summary: List proxies + description: List proxies in the resolved project. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + description: Limit the number of proxies to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of proxies to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Case-insensitive substring match against proxy name, host, or IP address. IDs match by exact value. + schema: + type: string + - name: name + in: query + required: false + description: Exact-match filter on proxy name using the database collation. In production, matching is case- and accent-insensitive. Names are not required to be unique, so multiple proxies may match. + schema: + type: string + responses: + "200": + description: List of proxies + headers: + X-Limit: + description: Limit the number of proxies to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of proxies to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more proxies to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Proxy' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const proxyListResponse of client.proxies.list()) { + console.log(proxyListResponse.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 + ) + page = client.proxies.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Proxies.List(context.TODO(), kernel.ProxyListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /proxies/{id}: + get: + operationId: getProxiesById + tags: + - Proxies + summary: Get proxy by ID + description: Retrieve a proxy in the resolved project by ID. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: Proxy retrieved + content: + application/json: + schema: + $ref: '#/components/schemas/Proxy' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 proxy = await client.proxies.retrieve('id'); + + console.log(proxy.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 + ) + proxy = client.proxies.retrieve( + "id", + ) + print(proxy.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + proxy, err := client.Proxies.Get(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", proxy.ID) + } + patch: + operationId: patchProxiesById + tags: + - Proxies + summary: Rename proxy by ID + description: Update a proxy's name. Proxy names are not unique and are not ID-or-name addressable on this endpoint; duplicate names are allowed. Name-based session-create lookups can remain ambiguous until callers resolve proxies by ID or the API adds a stronger uniqueness contract. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ProxyUpdateRequest' + responses: + "200": + description: Proxy updated + content: + application/json: + schema: + $ref: '#/components/schemas/Proxy' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 proxy = await client.proxies.update('id', { name: 'my-renamed-proxy' }); + + console.log(proxy.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 + ) + proxy = client.proxies.update( + id="id", + name="my-renamed-proxy", + ) + print(proxy.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + proxy, err := client.Proxies.Update( + context.TODO(), + "id", + kernel.ProxyUpdateParams{ + Name: "my-renamed-proxy", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", proxy.ID) + } + delete: + operationId: deleteProxiesById + tags: + - Proxies + summary: Delete proxy by ID + description: Soft delete a proxy. Sessions referencing it are not modified. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "204": + description: Proxy deleted + "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' + 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 + }); + + await client.proxies.delete('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 + ) + client.proxies.delete( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Proxies.Delete(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /proxies/{id}/check: + post: + operationId: postProxiesByIdCheck + tags: + - Proxies + summary: Check proxy health + description: Run a health check on the proxy to verify it's working. Optionally specify a URL to test reachability against a specific target. For ISP and datacenter proxies, this reliably tests whether the target site is reachable from the proxy's stable exit IP. For residential and mobile proxies, the exit node varies between requests, so this validates proxy configuration and connectivity rather than guaranteeing site-specific reachability. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/ProxyCheckRequest' + responses: + "200": + description: Health check completed + content: + application/json: + schema: + $ref: '#/components/schemas/Proxy' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "422": + $ref: '#/components/responses/UnprocessableEntity' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.proxies.check('id'); + + console.log(response.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 + ) + response = client.proxies.check( + id="id", + ) + print(response.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Proxies.Check( + context.TODO(), + "id", + kernel.ProxyCheckParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.ID) + } + /extensions: + post: + operationId: postExtensions + tags: + - Extensions + summary: Upload a browser extension + description: Upload a zip file containing an unpacked browser extension. Optionally provide a unique name for later reference. + security: + - bearerAuth: [] + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + description: ZIP file containing the browser extension. + example: '@path/to/extension.zip' + name: + type: string + description: Optional unique name within the project to reference this extension. + pattern: ^[A-Za-z0-9._-]{1,255}$ + required: + - file + responses: + "201": + description: Extension uploaded successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Extension' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + x-codeSamples: + - lang: JavaScript + source: |- + import fs from 'fs'; + import Kernel from '@onkernel/sdk'; + + const client = new Kernel({ + apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted + }); + + const response = await client.extensions.upload({ file: fs.createReadStream('path/to/file') }); + + console.log(response.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 + ) + response = client.extensions.upload( + file=b"Example data", + ) + print(response.id) + - lang: Go + source: | + package main + + import ( + "bytes" + "context" + "fmt" + "io" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Extensions.Upload(context.TODO(), kernel.ExtensionUploadParams{ + File: io.Reader(bytes.NewBuffer([]byte("Example data"))), + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.ID) + } + get: + operationId: getExtensions + tags: + - Extensions + summary: List browser extensions + description: List extensions in the resolved project. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + description: Limit the number of extensions to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of extensions to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Case-insensitive substring match against extension name. IDs match by exact value. + schema: + type: string + - name: name + in: query + required: false + description: Exact-match filter on extension name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project extension over a legacy unscoped extension with the same name. + schema: + type: string + responses: + "200": + description: List of extensions + headers: + X-Limit: + description: Limit the number of extensions to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of extensions to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more extensions to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Extension' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const extensionListResponse of client.extensions.list()) { + console.log(extensionListResponse.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 + ) + page = client.extensions.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Extensions.List(context.TODO(), kernel.ExtensionListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /extensions/{id_or_name}: + get: + operationId: getExtensionByIdOrName + tags: + - Extensions + summary: Download extension archive + description: Download the extension as a ZIP archive by ID or name. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Extension ID or name + responses: + "200": + description: Extension ZIP archive + content: + application/octet-stream: + schema: + type: string + format: binary + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.extensions.download('id_or_name'); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.extensions.download( + "id_or_name", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Extensions.Download(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + delete: + operationId: deleteExtensionByIdOrName + tags: + - Extensions + summary: Delete extension by ID or name + description: Delete an extension by its ID or by its name. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Extension ID or extension name + responses: + "204": + description: Extension deleted successfully + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.extensions.delete('id_or_name'); + - 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 + ) + client.extensions.delete( + "id_or_name", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Extensions.Delete(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + } + /extensions/{id_or_name}/metadata: + get: + operationId: getExtensionByIdOrNameMetadata + tags: + - Extensions + summary: Get extension metadata + description: Get an extension's metadata (name, size, timestamps) by ID or name, without downloading the archive. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Extension ID or name + responses: + "200": + description: Extension metadata + content: + application/json: + schema: + $ref: '#/components/schemas/Extension' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 extension = await client.extensions.get('id_or_name'); + + console.log(extension.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 + ) + extension = client.extensions.get( + "id_or_name", + ) + print(extension.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + extension, err := client.Extensions.Get(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", extension.ID) + } + /extensions/from_chrome_store: + get: + operationId: getExtensionsFromChromeStore + tags: + - Extensions + summary: Download unpacked extension from Chrome Web Store + description: Returns a ZIP archive containing the unpacked extension fetched from the Chrome Web Store. + security: + - bearerAuth: [] + parameters: + - name: url + in: query + required: true + schema: + type: string + description: Chrome Web Store URL for the extension. + - name: os + in: query + required: false + schema: + type: string + enum: + - win + - mac + - linux + default: linux + description: Target operating system for the extension package. Defaults to linux. + responses: + "200": + description: Extension ZIP archive + content: + application/octet-stream: + schema: + type: string + format: binary + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.extensions.downloadFromChromeStore({ url: 'url' }); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - 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 + ) + response = client.extensions.download_from_chrome_store( + url="url", + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Extensions.DownloadFromChromeStore(context.TODO(), kernel.ExtensionDownloadFromChromeStoreParams{ + URL: "url", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + } + /browser_pools: + post: + operationId: postBrowserPools + tags: + - Browser Pools + summary: Create a browser pool + description: | + Create a new browser pool with the specified configuration and size. + Pooled browsers load their profile read-only: any save_changes on the profile is ignored + (not rejected), so pooled browsers never persist changes back to the profile. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPoolCreateRequest' + 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' + 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 + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + browserPool, err := client.BrowserPools.New(context.TODO(), kernel.BrowserPoolNewParams{ + Size: 10, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", browserPool.ID) + } + get: + operationId: getBrowserPools + tags: + - Browser Pools + summary: List browser pools + description: List browser pools in the resolved project. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + description: Limit the number of browser pools to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of browser pools to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Case-insensitive substring match against browser pool name. IDs match by exact value. + schema: + type: string + - name: name + in: query + required: false + description: Exact-match filter on browser pool name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project browser pool over a legacy unscoped browser pool with the same name. + schema: + type: string + responses: + "200": + description: List of browser pools + headers: + X-Limit: + description: Limit the number of browser pools to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of browser pools to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more browser pools to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/BrowserPool' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const browserPool of client.browserPools.list()) { + 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 + ) + page = client.browser_pools.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.BrowserPools.List(context.TODO(), kernel.BrowserPoolListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /browser_pools/{id_or_name}: + get: + operationId: getBrowserPoolsByIdOrName + tags: + - Browser Pools + summary: Get browser pool details + description: Retrieve details for a single browser pool by its ID or name. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser pool ID or name + responses: + "200": + description: Browser pool details + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPool' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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.retrieve('id_or_name'); + + 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.retrieve( + "id_or_name", + ) + print(browser_pool.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + browserPool, err := client.BrowserPools.Get(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", browserPool.ID) + } + patch: + operationId: updateBrowserPoolsByIdOrName + tags: + - Browser Pools + summary: Update a browser pool + description: | + Updates the configuration used to create browsers in the pool. + As with creation, save_changes on the pool profile is ignored (not rejected); pooled + browsers never persist changes back to the profile. + To clear the profile reference, send `profile: { "id": "" }`. Clearing the profile + also disables `refresh_on_profile_update`. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser pool ID or name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPoolUpdateRequest' + responses: + "200": + description: Browser pool details + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPool' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "429": + $ref: '#/components/responses/TooManyRequests' + "500": + $ref: '#/components/responses/InternalError' + 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.update('id_or_name'); + + 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.update( + id_or_name="id_or_name", + ) + print(browser_pool.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + browserPool, err := client.BrowserPools.Update( + context.TODO(), + "id_or_name", + kernel.BrowserPoolUpdateParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", browserPool.ID) + } + delete: + operationId: deleteBrowserPoolsByIdOrName + tags: + - Browser Pools + summary: Delete a browser pool + description: Delete a browser pool and all browsers in it. By default, deletion is blocked if browsers are currently leased. Use force=true to terminate leased browsers. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser pool ID or name + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPoolDeleteRequest' + responses: + "204": + description: Browser pool deleted successfully + "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' + 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 + }); + + await client.browserPools.delete('id_or_name'); + - 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 + ) + client.browser_pools.delete( + id_or_name="id_or_name", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.BrowserPools.Delete( + context.TODO(), + "id_or_name", + kernel.BrowserPoolDeleteParams{}, + ) + if err != nil { + panic(err.Error()) + } + } + /browser_pools/{id_or_name}/acquire: + post: + operationId: acquireFromBrowserPoolByIdOrName + tags: + - Browser Pools + summary: Acquire a browser from the pool + description: | + Long-polling endpoint to acquire a browser from the pool. Returns immediately when a browser + is available, or returns 204 No Content when the poll times out. The client should retry + the request to continue waiting for a browser. The acquired browser will use the pool's + timeout_seconds for its idle timeout. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser pool ID or name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPoolAcquireRequest' + responses: + "200": + description: Browser acquired successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Browser' + "204": + description: Poll timed out, no browser available. Retry the request to continue waiting. + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.browserPools.acquire('id_or_name'); + + console.log(response.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 + ) + response = client.browser_pools.acquire( + id_or_name="id_or_name", + ) + print(response.session_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.BrowserPools.Acquire( + context.TODO(), + "id_or_name", + kernel.BrowserPoolAcquireParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.SessionID) + } + /browser_pools/{id_or_name}/release: + post: + operationId: releaseToBrowserPoolByIdOrName + tags: + - Browser Pools + summary: Release a browser back to the pool + description: Release a browser back to the pool, optionally recreating the browser instance. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser pool ID or name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/BrowserPoolReleaseRequest' + responses: + "204": + description: Browser released successfully + "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' + 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 + }); + + await client.browserPools.release('id_or_name', { session_id: 'ts8iy3sg25ibheguyni2lg9t' }); + - 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 + ) + client.browser_pools.release( + id_or_name="id_or_name", + session_id="ts8iy3sg25ibheguyni2lg9t", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.BrowserPools.Release( + context.TODO(), + "id_or_name", + kernel.BrowserPoolReleaseParams{ + SessionID: "ts8iy3sg25ibheguyni2lg9t", + }, + ) + if err != nil { + panic(err.Error()) + } + } + /browser_pools/{id_or_name}/flush: + post: + operationId: flushBrowserPoolByIdOrName + tags: + - Browser Pools + summary: Flush all idle browsers in the pool + description: Destroys all idle browsers in the pool; leased browsers are not affected. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Browser pool ID or name + responses: + "204": + description: Pool flushed successfully + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.browserPools.flush('id_or_name'); + - 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 + ) + client.browser_pools.flush( + "id_or_name", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.BrowserPools.Flush(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + } + /auth/connections: + post: + operationId: postAuthConnections + tags: + - Managed Auth + summary: Create auth connection + description: Creates an auth connection for a profile and domain combination. If the provided profile_name does not exist, it is created automatically. Returns 409 Conflict if an auth connection already exists for the given profile and domain. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuthCreateRequest' + responses: + "201": + description: Auth connection created + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuth' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "409": + description: Auth connection already exists for this profile and domain + content: + application/json: + schema: + type: object + required: + - code + - message + - existing_id + properties: + code: + type: string + example: already_exists + message: + type: string + example: Auth connection already exists for this profile and domain + existing_id: + type: string + description: ID of the existing auth connection + "500": + $ref: '#/components/responses/InternalError' + 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 managedAuth = await client.auth.connections.create({ + domain: 'netflix.com', + profile_name: 'user-123', + }); + + console.log(managedAuth.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 + ) + managed_auth = client.auth.connections.create( + domain="netflix.com", + profile_name="user-123", + ) + print(managed_auth.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + managedAuth, err := client.Auth.Connections.New(context.TODO(), kernel.AuthConnectionNewParams{ + ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ + Domain: "netflix.com", + ProfileName: "user-123", + }, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", managedAuth.ID) + } + get: + operationId: getAuthConnections + tags: + - Managed Auth + summary: List auth connections + description: List auth connections with optional filters for profile_name and domain. + security: + - bearerAuth: [] + parameters: + - name: profile_name + in: query + required: false + schema: + type: string + description: Filter by profile name + - name: domain + in: query + required: false + schema: + type: string + description: Filter by domain + - name: limit + in: query + required: false + schema: + type: integer + default: 20 + maximum: 100 + description: Maximum number of results to return + - name: offset + in: query + required: false + schema: + type: integer + default: 0 + description: Number of results to skip + - name: query + in: query + required: false + description: Search auth connections by ID, domain, or profile name. + schema: + type: string + responses: + "200": + description: List of auth connections + headers: + X-Has-More: + schema: + type: boolean + description: Whether there are more results + X-Next-Offset: + schema: + type: integer + description: The offset where the next page starts. 0 when there are no more results. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ManagedAuth' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const managedAuth of client.auth.connections.list()) { + console.log(managedAuth.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 + ) + page = client.auth.connections.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Auth.Connections.List(context.TODO(), kernel.AuthConnectionListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /auth/connections/{id}: + get: + operationId: getAuthConnectionsById + tags: + - Managed Auth + summary: Get auth connection + description: Retrieve an auth connection by its ID. Includes current flow state if a login is in progress. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + responses: + "200": + description: Auth connection details + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuth' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 managedAuth = await client.auth.connections.retrieve('id'); + + console.log(managedAuth.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 + ) + managed_auth = client.auth.connections.retrieve( + "id", + ) + print(managed_auth.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + managedAuth, err := client.Auth.Connections.Get(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", managedAuth.ID) + } + patch: + operationId: patchAuthConnectionsById + tags: + - Managed Auth + summary: Update auth connection + description: Update an auth connection's configuration. Only the fields provided will be updated. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuthUpdateRequest' + responses: + "200": + description: Auth connection updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuth' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 managedAuth = await client.auth.connections.update('id'); + + console.log(managedAuth.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 + ) + managed_auth = client.auth.connections.update( + id="id", + ) + print(managed_auth.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + managedAuth, err := client.Auth.Connections.Update( + context.TODO(), + "id", + kernel.AuthConnectionUpdateParams{ + ManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", managedAuth.ID) + } + delete: + operationId: deleteAuthConnectionsById + tags: + - Managed Auth + summary: Delete auth connection + description: | + Deletes an auth connection and terminates its workflow. This will: + - Delete the auth connection record + - Terminate the Temporal workflow + - Cancel any in-progress login flows + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + responses: + "204": + description: Auth connection deleted successfully + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.auth.connections.delete('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 + ) + client.auth.connections.delete( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Auth.Connections.Delete(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /auth/connections/{id}/login: + post: + operationId: postAuthConnectionsLogin + tags: + - Managed Auth + summary: Start login flow + description: Starts a login flow for the auth connection. Returns immediately with a hosted URL for the user to complete authentication, or triggers automatic re-auth if credentials are stored. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/LoginRequest' + responses: + "200": + description: Login flow started + content: + application/json: + schema: + $ref: '#/components/schemas/LoginResponse' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + description: Login flow already in progress + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + "500": + $ref: '#/components/responses/InternalError' + 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 loginResponse = await client.auth.connections.login('id'); + + console.log(loginResponse.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 + ) + login_response = client.auth.connections.login( + id="id", + ) + print(login_response.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + loginResponse, err := client.Auth.Connections.Login( + context.TODO(), + "id", + kernel.AuthConnectionLoginParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", loginResponse.ID) + } + /auth/connections/{id}/submit: + post: + operationId: postAuthConnectionsSubmit + tags: + - Managed Auth + summary: Submit field values + description: Submits field values for the login form. Poll the auth connection to track progress and get results. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitFieldsRequest' + responses: + "202": + description: Submission accepted for processing + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitFieldsResponse' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "422": + $ref: '#/components/responses/BadRequest' + "500": + $ref: '#/components/responses/InternalError' + 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 submitFieldsResponse = await client.auth.connections.submit('id'); + + console.log(submitFieldsResponse.accepted); + - 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 + ) + submit_fields_response = client.auth.connections.submit( + id="id", + ) + print(submit_fields_response.accepted) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + submitFieldsResponse, err := client.Auth.Connections.Submit( + context.TODO(), + "id", + kernel.AuthConnectionSubmitParams{ + SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", submitFieldsResponse.Accepted) + } + /auth/connections/{id}/events: + get: + operationId: getAuthConnectionsEventsById + tags: + - Managed Auth + summary: Stream login flow events via SSE + description: | + Establishes a Server-Sent Events (SSE) stream that delivers real-time + login flow state updates. The stream terminates automatically once + the flow reaches a terminal state (SUCCESS, FAILED, EXPIRED, CANCELED). + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: The auth connection ID to follow. + schema: + type: string + responses: + "200": + description: SSE stream of auth connection state updates. + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (always application/json). + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/ManagedAuthEvent' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.auth.connections.follow('id'); + + console.log(response); + - 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 + ) + for connection in client.auth.connections.follow( + "id", + ): + print(connection) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Auth.Connections.FollowStreaming(context.TODO(), "id") + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /auth/connections/{id}/timeline: + get: + operationId: getAuthConnectionsTimelineById + tags: + - Managed Auth + summary: Get auth connection event timeline + description: | + Returns a chronological timeline of events for an auth connection — + login attempts, automatic re-auth attempts, and health checks. Events + are returned newest-first. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + - name: type + in: query + required: false + schema: + type: string + enum: + - login + - reauth + - health_check + description: Filter the timeline to a single event type. + - name: limit + in: query + required: false + schema: + type: integer + default: 20 + maximum: 100 + description: Maximum number of events to return + - name: offset + in: query + required: false + schema: + type: integer + default: 0 + description: Number of events to skip + responses: + "200": + description: Event timeline for the auth connection + headers: + X-Has-More: + schema: + type: boolean + description: Whether there are more results + X-Next-Offset: + schema: + type: integer + description: The offset where the next page starts. 0 when there are no more results. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ManagedAuthTimelineEvent' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const managedAuthTimelineEvent of client.auth.connections.timeline('id')) { + console.log(managedAuthTimelineEvent.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 + ) + page = client.auth.connections.timeline( + id="id", + ) + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Auth.Connections.Timeline( + context.TODO(), + "id", + kernel.AuthConnectionTimelineParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /auth/connections/{id}/exchange: + post: + x-cli-skip: true + x-stainless-skip: true + x-hidden: true + operationId: postAuthConnectionsExchange + tags: + - Managed Auth + summary: Exchange handoff code for JWT + description: Validates the handoff code and returns a JWT token for subsequent requests. Used by the hosted login UI. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuthExchangeRequest' + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Auth connection ID + responses: + "200": + description: Exchange successful, JWT returned + content: + application/json: + schema: + $ref: '#/components/schemas/ManagedAuthExchangeResponse' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "410": + $ref: '#/components/responses/Gone' + "500": + $ref: '#/components/responses/InternalError' + /credentials: + post: + x-hidden: true + operationId: postCredentials + tags: + - Credentials + summary: Create a credential + description: Create a new credential for storing login information. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCredentialRequest' + responses: + "201": + description: Credential created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Credential' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 credential = await client.credentials.create({ + domain: 'netflix.com', + name: 'my-netflix-login', + values: { username: 'user@example.com', password: 'mysecretpassword' }, + }); + + console.log(credential.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 + ) + credential = client.credentials.create( + domain="netflix.com", + name="my-netflix-login", + values={ + "username": "user@example.com", + "password": "mysecretpassword", + }, + ) + print(credential.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credential, err := client.Credentials.New(context.TODO(), kernel.CredentialNewParams{ + CreateCredentialRequest: kernel.CreateCredentialRequestParam{ + Domain: "netflix.com", + Name: "my-netflix-login", + Values: map[string]string{ + "username": "user@example.com", + "password": "mysecretpassword", + }, + }, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credential.ID) + } + get: + x-hidden: true + operationId: getCredentials + tags: + - Credentials + summary: List credentials + description: List credentials in the resolved project. Credential values are not returned. + security: + - bearerAuth: [] + parameters: + - name: domain + in: query + required: false + schema: + type: string + description: Filter by domain + - name: limit + in: query + required: false + schema: + type: integer + default: 20 + maximum: 100 + description: Maximum number of results to return + - name: offset + in: query + required: false + schema: + type: integer + default: 0 + description: Number of results to skip + - name: query + in: query + required: false + description: Case-insensitive substring match against credential name or domain. IDs match by exact value. + schema: + type: string + responses: + "200": + description: List of credentials + headers: + X-Has-More: + schema: + type: boolean + description: Whether there are more results + X-Next-Offset: + schema: + type: integer + description: The offset where the next page starts. 0 when there are no more results. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Credential' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const credential of client.credentials.list()) { + console.log(credential.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 + ) + page = client.credentials.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Credentials.List(context.TODO(), kernel.CredentialListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /credentials/{id_or_name}: + get: + x-hidden: true + operationId: getCredentialByIdOrName + tags: + - Credentials + summary: Get credential by ID or name + description: Retrieve a credential by its ID or name. Credential values are not returned. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Credential ID or name + responses: + "200": + description: Credential details + content: + application/json: + schema: + $ref: '#/components/schemas/Credential' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 credential = await client.credentials.retrieve('id_or_name'); + + console.log(credential.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 + ) + credential = client.credentials.retrieve( + "id_or_name", + ) + print(credential.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credential, err := client.Credentials.Get(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credential.ID) + } + patch: + x-hidden: true + operationId: patchCredentialByIdOrName + tags: + - Credentials + summary: Update credential + description: Update a credential's name or values. When values are provided, they are merged with existing values (new keys are added, existing keys are overwritten). + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Credential ID or name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateCredentialRequest' + responses: + "200": + description: Credential updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Credential' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 credential = await client.credentials.update('id_or_name'); + + console.log(credential.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 + ) + credential = client.credentials.update( + id_or_name="id_or_name", + ) + print(credential.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credential, err := client.Credentials.Update( + context.TODO(), + "id_or_name", + kernel.CredentialUpdateParams{ + UpdateCredentialRequest: kernel.UpdateCredentialRequestParam{}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credential.ID) + } + delete: + x-hidden: true + operationId: deleteCredentialByIdOrName + tags: + - Credentials + summary: Delete credential + description: Delete a credential by its ID or name. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Credential ID or name + responses: + "204": + description: Credential deleted successfully + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.credentials.delete('id_or_name'); + - 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 + ) + client.credentials.delete( + "id_or_name", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Credentials.Delete(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + } + /credentials/{id_or_name}/totp-code: + get: + x-hidden: true + operationId: getCredentialTotpCodeByIdOrName + tags: + - Credentials + summary: Generate TOTP code + description: Returns the current 6-digit TOTP code for a credential with a configured totp_secret. Use this to complete 2FA setup on sites or when you need a fresh code. + security: + - bearerAuth: [] + parameters: + - name: id_or_name + in: path + required: true + schema: + type: string + description: Credential ID or name + responses: + "200": + description: TOTP code generated successfully + content: + application/json: + schema: + type: object + required: + - code + - expires_at + properties: + code: + type: string + description: Current 6-digit TOTP code + example: "847291" + expires_at: + type: string + format: date-time + description: When this code expires (ISO 8601 timestamp) + example: "2025-01-15T10:30:30Z" + "401": + $ref: '#/components/responses/Unauthorized' + "404": + description: Credential not found or has no TOTP secret configured + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.credentials.totpCode('id_or_name'); + + console.log(response.code); + - 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 + ) + response = client.credentials.totp_code( + "id_or_name", + ) + print(response.code) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Credentials.TotpCode(context.TODO(), "id_or_name") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Code) + } + /org/credential_providers: + post: + x-hidden: true + operationId: postCredentialProviders + tags: + - Credential Providers + summary: Create a credential provider + description: Configure an external credential provider (e.g., 1Password) for automatic credential lookup. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCredentialProviderRequest' + responses: + "201": + description: Credential provider created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/CredentialProvider' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 credentialProvider = await client.credentialProviders.create({ + token: 'ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', + name: 'my-1password', + provider_type: 'onepassword', + }); + + console.log(credentialProvider.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 + ) + credential_provider = client.credential_providers.create( + token="ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", + name="my-1password", + provider_type="onepassword", + ) + print(credential_provider.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credentialProvider, err := client.CredentialProviders.New(context.TODO(), kernel.CredentialProviderNewParams{ + CreateCredentialProviderRequest: kernel.CreateCredentialProviderRequestParam{ + Token: "ops_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", + Name: "my-1password", + ProviderType: kernel.CreateCredentialProviderRequestProviderTypeOnepassword, + }, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credentialProvider.ID) + } + get: + x-hidden: true + operationId: getCredentialProviders + tags: + - Credential Providers + summary: List credential providers + description: List external credential providers configured for the organization. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + description: Limit the number of credential providers to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of credential providers to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Case-insensitive substring match against credential provider name. IDs match by exact value. + schema: + type: string + responses: + "200": + description: List of credential providers + headers: + X-Limit: + description: Limit the number of credential providers to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of credential providers to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more credential providers to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/CredentialProvider' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const credentialProvider of client.credentialProviders.list()) { + console.log(credentialProvider.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 + ) + page = client.credential_providers.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.CredentialProviders.List(context.TODO(), kernel.CredentialProviderListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /org/credential_providers/{id}: + get: + x-hidden: true + operationId: getCredentialProvidersById + tags: + - Credential Providers + summary: Get credential provider by ID + description: Retrieve a credential provider by its ID. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Credential provider ID + responses: + "200": + description: Credential provider details + content: + application/json: + schema: + $ref: '#/components/schemas/CredentialProvider' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 credentialProvider = await client.credentialProviders.retrieve('id'); + + console.log(credentialProvider.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 + ) + credential_provider = client.credential_providers.retrieve( + "id", + ) + print(credential_provider.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credentialProvider, err := client.CredentialProviders.Get(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credentialProvider.ID) + } + patch: + x-hidden: true + operationId: patchCredentialProvidersById + tags: + - Credential Providers + summary: Update credential provider + description: Update a credential provider's configuration. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Credential provider ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateCredentialProviderRequest' + responses: + "200": + description: Credential provider updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/CredentialProvider' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 credentialProvider = await client.credentialProviders.update('id'); + + console.log(credentialProvider.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 + ) + credential_provider = client.credential_providers.update( + id="id", + ) + print(credential_provider.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credentialProvider, err := client.CredentialProviders.Update( + context.TODO(), + "id", + kernel.CredentialProviderUpdateParams{ + UpdateCredentialProviderRequest: kernel.UpdateCredentialProviderRequestParam{}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credentialProvider.ID) + } + delete: + x-hidden: true + operationId: deleteCredentialProvidersById + tags: + - Credential Providers + summary: Delete credential provider + description: Delete a credential provider by its ID. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Credential provider ID + responses: + "204": + description: Credential provider deleted successfully + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.credentialProviders.delete('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 + ) + client.credential_providers.delete( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.CredentialProviders.Delete(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /org/credential_providers/{id}/test: + post: + x-hidden: true + operationId: testCredentialProviderById + tags: + - Credential Providers + summary: Test credential provider connection + description: Validate the credential provider's token and list accessible vaults. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Credential provider ID + responses: + "200": + description: Connection test successful + content: + application/json: + schema: + $ref: '#/components/schemas/CredentialProviderTestResult' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 credentialProviderTestResult = await client.credentialProviders.test('id'); + + console.log(credentialProviderTestResult.success); + - 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 + ) + credential_provider_test_result = client.credential_providers.test( + "id", + ) + print(credential_provider_test_result.success) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + credentialProviderTestResult, err := client.CredentialProviders.Test(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", credentialProviderTestResult.Success) + } + /org/credential_providers/{id}/items: + get: + x-hidden: true + operationId: getCredentialProviderItems + tags: + - Credential Providers + summary: List items from a credential provider + description: Returns available credential items (e.g., 1Password login items) from the provider. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Credential provider ID + responses: + "200": + description: List of credential items + content: + application/json: + schema: + type: object + properties: + items: + type: array + items: + $ref: '#/components/schemas/CredentialProviderItem' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.credentialProviders.listItems('id'); + + console.log(response.items); + - 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 + ) + response = client.credential_providers.list_items( + "id", + ) + print(response.items) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.CredentialProviders.ListItems(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Items) + } + /apps: + get: + operationId: getApps + tags: + - Apps + summary: List apps + description: List applications. Optionally filter by app name and/or version label. + security: + - bearerAuth: [] + parameters: + - name: app_name + in: query + required: false + description: Filter results by application name. + schema: + type: string + - name: version + in: query + required: false + description: Filter results by version label. + schema: + type: string + - name: limit + in: query + required: false + description: Limit the number of apps to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of apps to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Search apps by name. + schema: + type: string + responses: + "200": + description: List of apps. + headers: + X-Limit: + description: Limit the number of apps to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of apps to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more apps to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AppVersionSummary' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const appListResponse of client.apps.list()) { + console.log(appListResponse.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 + ) + page = client.apps.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Apps.List(context.TODO(), kernel.AppListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /deployments: + post: + operationId: postDeployments + tags: + - Deployments + summary: Create a deployment + description: Create a new deployment. + security: + - bearerAuth: [] + requestBody: + description: App deployment data + required: true + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/DeploymentRequest' + examples: + upload_zip: + summary: Upload a ZIP file + value: + version: 1.0.0 + file: + entrypoint_rel_path: src/app.py + region: aws.us-east-1a + force: false + env_vars: + FOO: bar + github_public: + summary: Deploy from GitHub source + value: + version: 1.0.0 + source: + type: github + url: https://github.com/org/repo + ref: main + path: apps/api + entrypoint: src/index.ts + region: aws.us-east-1a + force: false + env_vars: + FOO: bar + github_private: + summary: Deploy from private GitHub repo + value: + version: latest + source: + type: github + url: https://github.com/org/private-repo + ref: main + path: apps/service + entrypoint: index.ts + auth: + method: github_token + token: ghs_*** + encoding: + source: + contentType: application/json + responses: + "201": + description: Deployment created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + x-codeSamples: + - lang: JavaScript + source: |- + import fs from 'fs'; + import Kernel from '@onkernel/sdk'; + + const client = new Kernel({ + apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted + }); + + const deployment = await client.deployments.create({ + entrypoint_rel_path: 'src/app.py', + env_vars: { FOO: 'bar' }, + file: fs.createReadStream('path/to/file'), + region: 'aws.us-east-1a', + version: '1.0.0', + }); + + console.log(deployment.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 + ) + deployment = client.deployments.create( + entrypoint_rel_path="src/app.py", + env_vars={ + "FOO": "bar" + }, + file=b"", + force=False, + region="aws.us-east-1a", + version="1.0.0", + ) + print(deployment.id) + - lang: Go + source: | + package main + + import ( + "bytes" + "context" + "fmt" + "io" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + deployment, err := client.Deployments.New(context.TODO(), kernel.DeploymentNewParams{ + EntrypointRelPath: kernel.String("src/app.py"), + EnvVars: map[string]string{ + "FOO": "bar", + }, + File: io.Reader(bytes.NewBuffer([]byte(""))), + Region: kernel.DeploymentNewParamsRegionAwsUsEast1a, + Version: kernel.String("1.0.0"), + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", deployment.ID) + } + get: + operationId: getDeployments + tags: + - Deployments + summary: List deployments + description: List deployments. Optionally filter by application name and version. + security: + - bearerAuth: [] + parameters: + - name: app_name + in: query + required: false + description: Filter results by application name. + schema: + type: string + - name: app_version + in: query + required: false + description: Filter results by application version. Requires app_name to be set. + schema: + type: string + - name: limit + in: query + required: false + description: Limit the number of deployments to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of deployments to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Search deployments by ID or app name. + schema: + type: string + responses: + "200": + description: List of deployments. + headers: + X-Limit: + description: Limit the number of deployments to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of deployments to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more deployments to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Deployment' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const deploymentListResponse of client.deployments.list()) { + console.log(deploymentListResponse.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 + ) + page = client.deployments.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Deployments.List(context.TODO(), kernel.DeploymentListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /deployments/{id}: + get: + operationId: getDeploymentsById + tags: + - Deployments + summary: Get deployment details + description: Get information about a deployment's status. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: Deployment ID + schema: + type: string + responses: + "200": + description: Deployment retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 deployment = await client.deployments.retrieve('id'); + + console.log(deployment.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 + ) + deployment = client.deployments.retrieve( + "id", + ) + print(deployment.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + deployment, err := client.Deployments.Get(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", deployment.ID) + } + delete: + operationId: deleteDeploymentsById + tags: + - Deployments + summary: Delete a deployment + description: Stops a running deployment and marks it for deletion. If the deployment is already in a terminal state (stopped or failed), returns immediately. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: Deployment ID + schema: + type: string + responses: + "204": + description: Deployment deleted successfully + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.deployments.delete('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 + ) + client.deployments.delete( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Deployments.Delete(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /deployments/{id}/events: + get: + x-hidden: false + operationId: getDeploymentsEventsById + tags: + - Deployments + summary: Stream deployment events via SSE + description: | + Establishes a Server-Sent Events (SSE) stream that delivers real-time logs and + status updates for a deployment. The stream terminates automatically + once the deployment reaches a terminal state. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: The deployment ID to follow. + schema: + type: string + - name: since + in: query + required: false + description: Show logs since the given time (RFC timestamps or durations like 5m). + schema: + type: string + example: "2025-06-20T12:00:00Z" + responses: + "200": + description: SSE stream of deployment state updates and logs. + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (always application/json). + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/DeploymentEvent' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.deployments.follow('id'); + + console.log(response); + - 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 + ) + for deployment in client.deployments.follow( + id="id", + ): + print(deployment) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Deployments.FollowStreaming( + context.TODO(), + "id", + kernel.DeploymentFollowParams{}, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /invocations: + post: + operationId: postInvocations + tags: + - Invocations + summary: Invoke an action + description: Invoke an action. + security: + - bearerAuth: [] + requestBody: + description: Invocation parameters + required: true + content: + application/json: + schema: + type: object + properties: + app_name: + type: string + description: Name of the application + example: my-app + version: + type: string + description: Version of the application + example: 1.0.0 + default: latest + payload: + type: string + description: Input data for the action, sent as a JSON string. + example: '{"data":"example input"}' + action_name: + type: string + description: Name of the action to invoke + example: analyze + async: + type: boolean + description: If true, invoke asynchronously. When set, the API responds 202 Accepted with status "queued". + example: true + default: false + async_timeout_seconds: + type: integer + description: Timeout in seconds for async invocations (min 10, max 3600). Only applies when async is true. + example: 600 + default: 900 + minimum: 10 + maximum: 3600 + required: + - app_name + - version + - action_name + responses: + "200": + description: Invocation created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/InvokeResponse' + "202": + description: Invocation queued successfully (asynchronous invocation) + content: + application/json: + schema: + $ref: '#/components/schemas/InvokeResponse' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "429": + $ref: '#/components/responses/TooManyRequests' + "500": + $ref: '#/components/responses/InternalError' + "529": + $ref: '#/components/responses/CapacityExhausted' + 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 invocation = await client.invocations.create({ + action_name: 'analyze', + app_name: 'my-app', + version: '1.0.0', + }); + + console.log(invocation.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 + ) + invocation = client.invocations.create( + action_name="analyze", + app_name="my-app", + version="1.0.0", + ) + print(invocation.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + invocation, err := client.Invocations.New(context.TODO(), kernel.InvocationNewParams{ + ActionName: "analyze", + AppName: "my-app", + Version: "1.0.0", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", invocation.ID) + } + get: + operationId: getInvocations + tags: + - Invocations + summary: List invocations + description: List invocations. Optionally filter by application name, action name, status, deployment ID, or start time. + security: + - bearerAuth: [] + parameters: + - name: app_name + in: query + required: false + description: Filter results by application name. + schema: + type: string + - name: version + in: query + required: false + description: Filter results by application version. + schema: + type: string + - name: action_name + in: query + required: false + description: Filter results by action name. + schema: + type: string + - name: deployment_id + in: query + required: false + description: Filter results by deployment ID. + schema: + type: string + - name: status + in: query + required: false + description: Filter results by invocation status. + schema: + type: string + enum: + - queued + - running + - succeeded + - failed + - name: since + in: query + required: false + description: Show invocations that have started since the given time (RFC timestamps or durations like 5m). + schema: + type: string + example: "2025-06-20T12:00:00Z" + - name: limit + in: query + required: false + description: Limit the number of invocations to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of invocations to return. + schema: + type: integer + minimum: 0 + default: 0 + - name: query + in: query + required: false + description: Search invocations by ID, app name, or action name. + schema: + type: string + responses: + "200": + description: A list of invocations. + headers: + X-Limit: + description: The limit of invocations returned. + schema: + type: integer + X-Offset: + description: The offset of invocations returned. + schema: + type: integer + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more invocations to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Invocation' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const invocationListResponse of client.invocations.list()) { + console.log(invocationListResponse.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 + ) + page = client.invocations.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Invocations.List(context.TODO(), kernel.InvocationListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /invocations/{id}: + get: + operationId: getInvocationsById + tags: + - Invocations + summary: Get invocation details + description: Get details about an invocation's status and output. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: The invocation ID + example: rr33xuugxj9h0bkf1rdt2bet + responses: + "200": + description: App invocation retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Invocation' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 invocation = await client.invocations.retrieve('rr33xuugxj9h0bkf1rdt2bet'); + + console.log(invocation.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 + ) + invocation = client.invocations.retrieve( + "rr33xuugxj9h0bkf1rdt2bet", + ) + print(invocation.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + invocation, err := client.Invocations.Get(context.TODO(), "rr33xuugxj9h0bkf1rdt2bet") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", invocation.ID) + } + patch: + operationId: patchInvocationsById + tags: + - Invocations + summary: Update invocation + description: Update an invocation's status or output. This can be used to cancel an invocation by setting the status to "failed". + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Invocation ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InvocationUpdateRequest' + responses: + "200": + description: Invocation updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Invocation' + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 invocation = await client.invocations.update('id', { status: 'succeeded' }); + + console.log(invocation.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 + ) + invocation = client.invocations.update( + id="id", + status="succeeded", + ) + print(invocation.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + invocation, err := client.Invocations.Update( + context.TODO(), + "id", + kernel.InvocationUpdateParams{ + Status: kernel.InvocationUpdateParamsStatusSucceeded, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", invocation.ID) + } + /invocations/{id}/browsers: + get: + operationId: getInvocationsBrowsersById + tags: + - Invocations + summary: List browsers for an invocation + description: Returns all active browser sessions created within the specified invocation. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Invocation ID + responses: + "200": + description: List of browsers for this invocation + content: + application/json: + schema: + type: object + required: + - browsers + properties: + browsers: + type: array + items: + $ref: '#/components/schemas/Browser' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.invocations.listBrowsers('id'); + + console.log(response.browsers); + - 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 + ) + response = client.invocations.list_browsers( + "id", + ) + print(response.browsers) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.Invocations.ListBrowsers(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.Browsers) + } + delete: + operationId: deleteInvocationsBrowsersById + tags: + - Invocations + summary: Delete browser sessions for an invocation + description: Delete all browser sessions created within the specified invocation. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Invocation ID + responses: + "204": + description: Browser sessions deleted successfully + "400": + $ref: '#/components/responses/BadRequest' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.invocations.deleteBrowsers('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 + ) + client.invocations.delete_browsers( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Invocations.DeleteBrowsers(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /invocations/{id}/events: + get: + x-hidden: false + operationId: getInvocationsEventsById + tags: + - Invocations + summary: Stream invocation events via SSE + description: | + Establishes a Server-Sent Events (SSE) stream that delivers real-time logs and + status updates for an invocation. The stream terminates automatically + once the invocation reaches a terminal state. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + description: The invocation ID to follow. + schema: + type: string + - name: since + in: query + required: false + description: Show logs since the given time (RFC timestamps or durations like 5m). + schema: + type: string + example: "2025-06-20T12:00:00Z" + responses: + "200": + description: SSE stream of invocation state updates and logs. + headers: + X-SSE-Content-Type: + description: Media type of SSE data events (always application/json). + schema: + type: string + const: application/json + content: + text/event-stream: + schema: + $ref: '#/components/schemas/InvocationEvent' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.invocations.follow('id'); + + console.log(response); + - 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 + ) + for invocation in client.invocations.follow( + id="id", + ): + print(invocation) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + stream := client.Invocations.FollowStreaming( + context.TODO(), + "id", + kernel.InvocationFollowParams{}, + ) + for stream.Next() { + fmt.Printf("%+v\n", stream.Current()) + } + err := stream.Err() + if err != nil { + panic(err.Error()) + } + } + /projects: + post: + operationId: postProjects + tags: + - Projects + summary: Create a project + description: | + Deprecated: use `POST /org/projects` instead. This route will be removed on 2026-11-24. + + Create a new project within the authenticated organization. + deprecated: true + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateProjectRequest' + responses: + "201": + description: Project created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + get: + operationId: getProjects + tags: + - Projects + summary: List projects + description: | + Deprecated: use `GET /org/projects` instead. This route will be removed on 2026-11-24. + + List projects for the authenticated organization. + deprecated: true + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 20 + maximum: 100 + description: Maximum number of results to return + - name: offset + in: query + required: false + schema: + type: integer + default: 0 + description: Number of results to skip + - name: query + in: query + required: false + schema: + type: string + description: Case-insensitive substring match against project name + - name: name + in: query + required: false + schema: + type: string + description: Exact-match filter on project name using the database collation. In production, matching is case- and accent-insensitive. + responses: + "200": + description: List of projects + headers: + X-Has-More: + schema: + type: boolean + description: Whether there are more results + X-Next-Offset: + schema: + type: integer + description: The offset where the next page starts. 0 when there are no more results. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Project' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + /projects/{id}: + get: + operationId: getProjectsId + tags: + - Projects + summary: Get a project + description: | + Deprecated: use `GET /org/projects/{id}` instead. This route will be removed on 2026-11-24. + + Get a project by ID. + deprecated: true + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + responses: + "200": + description: Project details + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + patch: + operationId: patchProjectsId + tags: + - Projects + summary: Update a project + description: | + Deprecated: use `PATCH /org/projects/{id}` instead. This route will be removed on 2026-11-24. + + Update a project's name or status. + deprecated: true + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateProjectRequest' + responses: + "200": + description: Project updated + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + delete: + operationId: deleteProjectsId + tags: + - Projects + summary: Delete a project + description: | + Deprecated: use `DELETE /org/projects/{id}` instead. This route will be removed on 2026-11-24. + + Soft-delete a project. The project must be empty (no active resources). + deprecated: true + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + responses: + "204": + description: Project deleted + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + /projects/{id}/limits: + get: + operationId: getProjectLimits + tags: + - Projects + summary: Get project limits + description: | + Deprecated: use `GET /org/projects/{id}/limits` instead. This route will be removed on 2026-11-24. + + Get the resource limit overrides for a project. Null values mean no project-level cap (org limit applies). + deprecated: true + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + responses: + "200": + description: Project limits + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectLimits' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + patch: + operationId: patchProjectLimits + tags: + - Projects + summary: Update project limits + description: | + Deprecated: use `PATCH /org/projects/{id}/limits` instead. This route will be removed on 2026-11-24. + + Update resource limit overrides for a project. Only fields present in the request are modified. Set a field to 0 to remove that limit cap; omit a field to leave it unchanged. + deprecated: true + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateProjectLimitsRequest' + responses: + "200": + description: Project limits updated + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectLimits' + "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' + /org/projects: + post: + operationId: postOrgProjects + tags: + - Projects + summary: Create a project + description: Create a new project within the authenticated organization. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateProjectRequest' + responses: + "201": + description: Project created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 project = await client.projects.create({ name: 'staging' }); + + console.log(project.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 + ) + project = client.projects.create( + name="staging", + ) + print(project.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + project, err := client.Projects.New(context.TODO(), kernel.ProjectNewParams{ + CreateProjectRequest: kernel.CreateProjectRequestParam{ + Name: "staging", + }, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", project.ID) + } + get: + operationId: getOrgProjects + tags: + - Projects + summary: List projects + description: List projects for the authenticated organization. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 20 + maximum: 100 + description: Maximum number of results to return + - name: offset + in: query + required: false + schema: + type: integer + default: 0 + description: Number of results to skip + - name: query + in: query + required: false + schema: + type: string + description: Case-insensitive substring match against project name + - name: name + in: query + required: false + schema: + type: string + description: Exact-match filter on project name using the database collation. In production, matching is case- and accent-insensitive. + responses: + "200": + description: List of projects + headers: + X-Has-More: + schema: + type: boolean + description: Whether there are more results + X-Next-Offset: + schema: + type: integer + description: The offset where the next page starts. 0 when there are no more results. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Project' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const project of client.projects.list()) { + console.log(project.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 + ) + page = client.projects.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.Projects.List(context.TODO(), kernel.ProjectListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /org/projects/{id}: + get: + operationId: getOrgProjectsId + tags: + - Projects + summary: Get a project by ID or name + description: Get a project by its ID or by its name. Names are unique within an organization. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID or name + responses: + "200": + description: Project details + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 project = await client.projects.retrieve('id'); + + console.log(project.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 + ) + project = client.projects.retrieve( + "id", + ) + print(project.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + project, err := client.Projects.Get(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", project.ID) + } + patch: + operationId: patchOrgProjectsId + tags: + - Projects + summary: Update a project + description: Update a project's name or status. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateProjectRequest' + responses: + "200": + description: Project updated + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + 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 project = await client.projects.update('id'); + + console.log(project.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 + ) + project = client.projects.update( + id="id", + ) + print(project.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + project, err := client.Projects.Update( + context.TODO(), + "id", + kernel.ProjectUpdateParams{ + UpdateProjectRequest: kernel.UpdateProjectRequestParam{}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", project.ID) + } + delete: + operationId: deleteOrgProjectsId + tags: + - Projects + summary: Delete a project + description: Soft-delete a project. The project must be empty (no active resources). + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + responses: + "204": + description: Project deleted + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + description: | + Project deletion conflict. Returns `project_not_empty` when active + resources remain; remove them and retry. Returns `last_active_project` + when deletion would remove the organization's final active project. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.projects.delete('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 + ) + client.projects.delete( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.Projects.Delete(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /org/limits: + get: + operationId: getOrgLimits + tags: + - Organization + summary: Get organization limits + description: Get the organization's concurrency limit — the maximum browsers running at once across on-demand sessions and browser pool reservations — and the default per-project concurrency cap applied to projects without an explicit override. + security: + - bearerAuth: [] + responses: + "200": + description: Organization limits + content: + application/json: + schema: + $ref: '#/components/schemas/OrgLimits' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 orgLimits = await client.organization.limits.retrieve(); + + console.log(orgLimits.default_project_max_concurrent_sessions); + - 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 + ) + org_limits = client.organization.limits.retrieve() + print(org_limits.default_project_max_concurrent_sessions) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + orgLimits, err := client.Organization.Limits.Get(context.TODO()) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", orgLimits.DefaultProjectMaxConcurrentSessions) + } + patch: + operationId: patchOrgLimits + tags: + - Organization + summary: Update organization limits + description: Set the default per-project concurrency cap applied to projects without an explicit override. Set the value to 0 to remove the default; omit to leave it unchanged. The default cannot exceed the organization's concurrency limit. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrgLimitsRequest' + responses: + "200": + description: Organization limits updated + content: + application/json: + schema: + $ref: '#/components/schemas/OrgLimits' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + 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 orgLimits = await client.organization.limits.update(); + + console.log(orgLimits.default_project_max_concurrent_sessions); + - 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 + ) + org_limits = client.organization.limits.update() + print(org_limits.default_project_max_concurrent_sessions) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + orgLimits, err := client.Organization.Limits.Update(context.TODO(), kernel.OrganizationLimitUpdateParams{ + UpdateOrgLimitsRequest: kernel.UpdateOrgLimitsRequestParam{}, + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", orgLimits.DefaultProjectMaxConcurrentSessions) + } + /org/projects/{id}/limits: + get: + operationId: getOrgProjectLimits + tags: + - Projects + summary: Get project limits + description: Get the resource limit overrides for a project. Null values mean no project-level cap (org limit applies). + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + responses: + "200": + description: Project limits + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectLimits' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 projectLimits = await client.projects.limits.retrieve('id'); + + console.log(projectLimits.max_concurrent_invocations); + - 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 + ) + project_limits = client.projects.limits.retrieve( + "id", + ) + print(project_limits.max_concurrent_invocations) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + projectLimits, err := client.Projects.Limits.Get(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", projectLimits.MaxConcurrentInvocations) + } + patch: + operationId: patchOrgProjectLimits + tags: + - Projects + summary: Update project limits + description: Update resource limit overrides for a project. Only fields present in the request are modified. Set a field to 0 to remove that limit cap; omit a field to leave it unchanged. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: Project ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateProjectLimitsRequest' + responses: + "200": + description: Project limits updated + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectLimits' + "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' + 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 projectLimits = await client.projects.limits.update('id'); + + console.log(projectLimits.max_concurrent_invocations); + - 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 + ) + project_limits = client.projects.limits.update( + id="id", + ) + print(project_limits.max_concurrent_invocations) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + projectLimits, err := client.Projects.Limits.Update( + context.TODO(), + "id", + kernel.ProjectLimitUpdateParams{ + UpdateProjectLimitsRequest: kernel.UpdateProjectLimitsRequestParam{}, + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", projectLimits.MaxConcurrentInvocations) + } + /org/api_keys: + post: + operationId: postApiKeys + tags: + - API Keys + summary: Create an API key + description: Create a new API key within the authenticated organization. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateApiKeyRequest' + responses: + "201": + description: API key created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/CreatedApiKey' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 createdAPIKey = await client.apiKeys.create({ name: 'staging' }); + + console.log(createdAPIKey); + - 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 + ) + created_api_key = client.api_keys.create( + name="staging", + ) + print(created_api_key) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + createdAPIKey, err := client.APIKeys.New(context.TODO(), kernel.APIKeyNewParams{ + Name: "staging", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", createdAPIKey) + } + get: + operationId: listApiKeys + tags: + - API Keys + summary: List API keys + description: List API keys for the authenticated organization. API keys are masked. + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 20 + maximum: 100 + description: Maximum number of results to return + - name: offset + in: query + required: false + schema: + type: integer + default: 0 + description: Number of results to skip + - name: query + in: query + required: false + schema: + type: string + description: Case-insensitive substring match against API key name, creator, and project. API key identifiers and masked keys match by exact value or prefix. + - name: name + in: query + required: false + schema: + type: string + description: Exact-match filter on API key name using the database collation. In production, matching is case- and accent-insensitive. Names are not required to be unique, so multiple keys may match. When status=all or include_deleted=true is set, soft-deleted keys with the same name may also match. + - name: sort_by + in: query + required: false + schema: + type: string + enum: + - created_at + - name + - expires_at + default: created_at + description: Field to sort API keys by. + - name: sort_direction + in: query + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + description: Sort direction for API keys. + - name: status + in: query + required: false + description: Filter API keys by status. "active" returns keys that are not deleted (default; expired-but-not-deleted keys are still included), "deleted" returns only soft-deleted keys, "all" returns both. + schema: + type: string + enum: + - active + - deleted + - all + default: active + - name: include_deleted + in: query + required: false + deprecated: true + description: 'Deprecated: use status=all instead. When true, include deleted (soft-deleted) API keys in the results for audit purposes.' + schema: + type: boolean + default: false + responses: + "200": + description: List of API keys + headers: + X-Has-More: + schema: + type: boolean + description: Whether there are more results + X-Next-Offset: + schema: + type: integer + description: The offset where the next page starts. 0 when there are no more results. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ApiKey' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const apiKey of client.apiKeys.list()) { + console.log(apiKey.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 + ) + page = client.api_keys.list() + page = page.items[0] + print(page.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.APIKeys.List(context.TODO(), kernel.APIKeyListParams{}) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /org/api_keys/{id}: + get: + operationId: getApiKeysById + tags: + - API Keys + summary: Get an API key + description: Retrieve an API key by ID for the authenticated organization. API keys are masked. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: API key ID + - name: include_deleted + in: query + required: false + schema: + type: boolean + default: false + description: When true, return the API key even if it has been deleted (soft-deleted), for audit purposes. Defaults to false, which returns 404 for a deleted key. + responses: + "200": + description: API key details + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKey' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 apiKey = await client.apiKeys.retrieve('id'); + + console.log(apiKey.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 + ) + api_key = client.api_keys.retrieve( + id="id", + ) + print(api_key.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + apiKey, err := client.APIKeys.Get( + context.TODO(), + "id", + kernel.APIKeyGetParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", apiKey.ID) + } + patch: + operationId: patchApiKeysById + tags: + - API Keys + summary: Update an API key + description: Update an API key's name. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: API key ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateApiKeyRequest' + responses: + "200": + description: API key updated + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKey' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 apiKey = await client.apiKeys.update('id', { name: 'new-api-name' }); + + console.log(apiKey.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 + ) + api_key = client.api_keys.update( + id="id", + name="new-api-name", + ) + print(api_key.id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + apiKey, err := client.APIKeys.Update( + context.TODO(), + "id", + kernel.APIKeyUpdateParams{ + Name: "new-api-name", + }, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", apiKey.ID) + } + delete: + operationId: deleteApiKeysById + tags: + - API Keys + summary: Delete an API key + description: Delete an API key. A key cannot delete itself; use a different key to delete this one. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: API key ID + responses: + "204": + description: API key deleted. + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + await client.apiKeys.delete('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 + ) + client.api_keys.delete( + "id", + ) + - lang: Go + source: | + package main + + import ( + "context" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + err := client.APIKeys.Delete(context.TODO(), "id") + if err != nil { + panic(err.Error()) + } + } + /org/api_keys/{id}/rotate: + post: + operationId: rotateApiKey + tags: + - API Keys + summary: Rotate an API key + description: Rotate an API key. Issues a new key that copies the name and project of the rotated key, and schedules the rotated key to expire after a grace period so in-flight callers can swap over. The new plaintext key is returned once. + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + description: API key ID + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/RotateApiKeyRequest' + responses: + "201": + description: New API key created from the rotation + content: + application/json: + schema: + $ref: '#/components/schemas/CreatedApiKey' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + 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 createdAPIKey = await client.apiKeys.rotate('id'); + + console.log(createdAPIKey); + - 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 + ) + created_api_key = client.api_keys.rotate( + id="id", + ) + print(created_api_key) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + createdAPIKey, err := client.APIKeys.Rotate( + context.TODO(), + "id", + kernel.APIKeyRotateParams{}, + ) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", createdAPIKey) + } + /audit-logs/export/destinations: + post: + x-hidden: true + x-cli-skip: true + x-stainless-skip: true + operationId: postAuditLogExportDestinations + tags: + - Audit Logs + summary: Create an audit log export destination + description: Creates a paused destination. Activate it with a status update once the destination test passes. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAuditLogExportDestinationRequest' + responses: + "201": + description: Audit log export destination created + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportDestination' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + get: + x-hidden: true + x-cli-skip: true + x-stainless-skip: true + operationId: getAuditLogExportDestinations + tags: + - Audit Logs + summary: List audit log export destinations + security: + - bearerAuth: [] + parameters: + - name: limit + in: query + required: false + description: Limit the number of destinations to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: offset + in: query + required: false + description: Offset the number of destinations to return. + schema: + type: integer + minimum: 0 + default: 0 + responses: + "200": + description: Audit log export destinations for the organization + headers: + X-Limit: + description: Limit the number of destinations to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + X-Offset: + description: The offset of destinations to return. + schema: + type: integer + minimum: 0 + default: 0 + X-Next-Offset: + description: The offset where the next page starts. 0 when there are no more results. + schema: + type: integer + nullable: true + X-Has-More: + description: Whether there are more destinations to fetch. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AuditLogExportDestination' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "500": + $ref: '#/components/responses/InternalError' + /audit-logs/export/destinations/{id}: + parameters: + - name: id + in: path + required: true + schema: + type: string + maxLength: 128 + get: + x-hidden: true + x-cli-skip: true + x-stainless-skip: true + operationId: getAuditLogExportDestinationsById + tags: + - Audit Logs + summary: Retrieve an audit log export destination + security: + - bearerAuth: [] + responses: + "200": + description: Audit log export destination + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportDestination' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + patch: + x-hidden: true + x-cli-skip: true + x-stainless-skip: true + operationId: patchAuditLogExportDestinationsById + tags: + - Audit Logs + summary: Update an audit log export destination + description: Applies a partial update. Returns 409 when the destination was changed concurrently, because the merged configuration this request validated is no longer the one that would be stored; retry against fresh state. Pausing prevents new delivery attempts, but an S3 upload already in progress may complete after the response. + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAuditLogExportDestinationRequest' + responses: + "200": + description: Audit log export destination updated + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportDestination' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "409": + $ref: '#/components/responses/Conflict' + "500": + $ref: '#/components/responses/InternalError' + delete: + x-hidden: true + x-cli-skip: true + x-stainless-skip: true + operationId: deleteAuditLogExportDestinationsById + tags: + - Audit Logs + summary: Delete an audit log export destination + description: Soft-deletes the destination and prevents new delivery attempts. An S3 upload already in progress may complete after the response. + security: + - bearerAuth: [] + responses: + "204": + description: Audit log export destination deleted + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + /audit-logs/export/destinations/{id}/test: + post: + x-hidden: true + x-cli-skip: true + x-stainless-skip: true + operationId: testAuditLogExportDestinationById + tags: + - Audit Logs + summary: Test an audit log export destination + security: + - bearerAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + maxLength: 128 + responses: + "200": + description: Audit log export destination test result + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportDestinationTestResult' + "401": + $ref: '#/components/responses/Unauthorized' + "403": + $ref: '#/components/responses/Forbidden' + "404": + $ref: '#/components/responses/NotFound' + "500": + $ref: '#/components/responses/InternalError' + /audit-logs: + get: + operationId: getAuditLogs + tags: + - Audit Logs + summary: List audit logs + description: API for searching audit logs. Limited to at most 30 day search, returns up to 100 records per page. Not recommended for bulk export. + security: + - bearerAuth: [] + parameters: + - name: start + in: query + required: true + description: Lower bound (inclusive) for the audit record timestamp. + schema: + type: string + format: date-time + example: "2026-01-01T00:00:00Z" + - name: end + in: query + required: true + description: Upper bound (exclusive) for the audit record timestamp. + schema: + type: string + format: date-time + example: "2026-01-02T00:00:00Z" + - name: auth_strategy + in: query + required: false + description: Filter by authentication strategy. + schema: + type: string + - name: service + in: query + required: false + description: Filter by service name. + schema: + type: string + - name: method + in: query + required: false + description: Filter by HTTP method. + schema: + type: string + - name: exclude_method + in: query + required: false + description: Filter out results by HTTP method. + style: form + explode: false + schema: + type: array + maxItems: 10 + items: + type: string + - name: search + in: query + required: false + description: Free-text search over path, user ID, email, client IP, and status. + schema: + type: string + - name: search_user_id + in: query + required: false + description: Additional user IDs to OR into free-text search. + style: form + explode: false + schema: + type: array + maxItems: 100 + items: + type: string + - name: limit + in: query + required: false + description: Maximum number of results to return. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 100 + - name: page_token + in: query + required: false + description: Opaque page token from X-Next-Page-Token for the next page of older records. + schema: + type: string + responses: + "200": + description: A list of audit log records. + headers: + X-Limit: + description: The limit applied to the returned records. + schema: + type: integer + minimum: 1 + maximum: 100 + X-Next-Page-Token: + description: Page token for the next page of older records, omitted when no more results. + schema: + type: string + X-Has-More: + description: Whether there are more records available beyond this page. + schema: + type: boolean + default: false + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AuditLogEntry' + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 + }); + + // Automatically fetches more pages as needed. + for await (const auditLogEntry of client.auditLogs.list({ + end: '2026-01-02T00:00:00Z', + start: '2026-01-01T00:00:00Z', + })) { + console.log(auditLogEntry.user_id); + } + - lang: Python + source: |- + import os + from datetime import datetime + from kernel import Kernel + + client = Kernel( + api_key=os.environ.get("KERNEL_API_KEY"), # This is the default and can be omitted + ) + page = client.audit_logs.list( + end=datetime.fromisoformat("2026-01-02T00:00:00"), + start=datetime.fromisoformat("2026-01-01T00:00:00"), + ) + page = page.items[0] + print(page.user_id) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + "time" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + page, err := client.AuditLogs.List(context.TODO(), kernel.AuditLogListParams{ + End: time.Now(), + Start: time.Now(), + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", page) + } + /audit-logs/export/chunk: + get: + operationId: getAuditLogsExportChunk + tags: + - Audit Logs + summary: Download an audit-log export chunk + description: Download an organization's audit log records for a time range as a file, for archival, compliance, or offline analysis. For interactive browsing, use GET /audit-logs. + security: + - bearerAuth: [] + parameters: + - name: start + in: query + required: true + description: Lower bound (inclusive) for the audit record timestamp. + schema: + type: string + format: date-time + example: "2026-01-01T00:00:00Z" + - name: end + in: query + required: true + description: Upper bound (exclusive) for the audit record timestamp. + schema: + type: string + format: date-time + example: "2026-01-02T00:00:00Z" + - name: auth_strategy + in: query + required: false + description: Filter by authentication strategy. + schema: + type: string + - name: service + in: query + required: false + description: Filter by service name. + schema: + type: string + - name: method + in: query + required: false + description: Filter by HTTP method. + schema: + type: string + - name: exclude_method + in: query + required: false + description: Filter out results by HTTP method. + style: form + explode: false + schema: + type: array + maxItems: 10 + items: + type: string + - name: search + in: query + required: false + description: Free-text search over path, user ID, email, client IP, and status. + schema: + type: string + - name: search_user_id + in: query + required: false + description: Additional user IDs to OR into free-text search. + style: form + explode: false + schema: + type: array + maxItems: 100 + items: + type: string + - name: cursor + in: query + required: false + description: Opaque cursor from X-Next-Cursor for the next chunk of older records. + schema: + type: string + - name: limit + in: query + required: false + description: Maximum number of records to return in this chunk. + schema: + type: integer + minimum: 1 + maximum: 50000 + default: 50000 + - name: format + in: query + required: false + description: Encoding for the returned chunk. + schema: + type: string + enum: + - jsonl + - jsonl.gz + default: jsonl.gz + responses: + "200": + description: One chunk of audit log records. + headers: + X-Has-More: + description: Whether more records remain beyond this chunk. + schema: + type: boolean + default: false + X-Next-Cursor: + description: Cursor for the next chunk of older records, empty when no more results. + schema: + type: string + X-Row-Count: + description: Number of records in this chunk. + schema: + type: integer + minimum: 0 + maximum: 50000 + X-Content-Sha256: + description: Hex SHA-256 of the response body. + schema: + type: string + pattern: ^[a-f0-9]{64}$ + content: + application/octet-stream: + schema: + type: string + format: binary + "400": + $ref: '#/components/responses/BadRequest' + "401": + $ref: '#/components/responses/Unauthorized' + "500": + $ref: '#/components/responses/InternalError' + 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 response = await client.auditLogs.exportChunk({ + end: '2026-01-02T00:00:00Z', + start: '2026-01-01T00:00:00Z', + }); + + console.log(response); + + const content = await response.blob(); + console.log(content); + - lang: Python + source: |- + import os + from datetime import datetime + from kernel import Kernel + + client = Kernel( + api_key=os.environ.get("KERNEL_API_KEY"), # This is the default and can be omitted + ) + response = client.audit_logs.export_chunk( + end=datetime.fromisoformat("2026-01-02T00:00:00"), + start=datetime.fromisoformat("2026-01-01T00:00:00"), + ) + print(response) + content = response.read() + print(content) + - lang: Go + source: | + package main + + import ( + "context" + "fmt" + "time" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + ) + + func main() { + client := kernel.NewClient( + option.WithAPIKey("My API Key"), + ) + response, err := client.AuditLogs.ExportChunk(context.TODO(), kernel.AuditLogExportChunkParams{ + End: time.Now(), + Start: time.Now(), + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response) + }