openapi: 3.1.0 info: title: Kernel API Keys Browsers API description: Developer tools and cloud infrastructure for AI agents to use web browsers version: 0.1.0 servers: - url: https://api.onkernel.com description: API Server security: - bearerAuth: [] tags: - name: Browsers description: Create and manage browser sessions. 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' '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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst browser = await client.browsers.create();\n\nconsole.log(browser.session_id);" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nbrowser = client.browsers.create()\nprint(browser.session_id)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.New(context.TODO(), kernel.BrowserNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n" 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 session ID, profile ID, proxy ID, or pool name. schema: 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 to use for the next page (only present when has_more is true) schema: type: integer content: application/json: schema: type: array items: $ref: '#/components/schemas/Browser' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' x-codeSamples: - lang: JavaScript source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const browserListResponse of client.browsers.list()) {\n console.log(browserListResponse.session_id);\n}" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\npage = client.browsers.list()\npage = page.items[0]\nprint(page.session_id)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Browsers.List(context.TODO(), kernel.BrowserListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" /browsers/{id}: get: operationId: getBrowsersById tags: - Browsers summary: Get browser session details description: Get information about a browser session. security: - bearerAuth: [] parameters: - name: id in: path required: true schema: type: string description: Browser session ID 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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst browser = await client.browsers.retrieve('htzv5orfit78e1m2biiifpbv');\n\nconsole.log(browser.session_id);" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nbrowser = client.browsers.retrieve(\n id=\"htzv5orfit78e1m2biiifpbv\",\n)\nprint(browser.session_id)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.Get(\n\t\tcontext.TODO(),\n\t\t\"htzv5orfit78e1m2biiifpbv\",\n\t\tkernel.BrowserGetParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n" delete: operationId: deleteBrowsersById tags: - Browsers summary: Delete a browser session by ID. description: Delete a browser session by ID security: - bearerAuth: [] parameters: - name: id in: path required: true schema: type: string description: Browser session ID 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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.browsers.deleteByID('htzv5orfit78e1m2biiifpbv');" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nclient.browsers.delete_by_id(\n \"htzv5orfit78e1m2biiifpbv\",\n)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Browsers.DeleteByID(context.TODO(), \"htzv5orfit78e1m2biiifpbv\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n" patch: operationId: patchBrowsersById tags: - Browsers summary: Update browser session description: Update a browser session. security: - bearerAuth: [] parameters: - name: id in: path required: true schema: type: string description: Browser session ID example: htzv5orfit78e1m2biiifpbv requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrowserUpdateRequest' responses: '200': description: Browser session updated successfully content: application/json: schema: $ref: '#/components/schemas/Browser' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' x-codeSamples: - lang: JavaScript source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst browser = await client.browsers.update('htzv5orfit78e1m2biiifpbv');\n\nconsole.log(browser.session_id);" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nbrowser = client.browsers.update(\n id=\"htzv5orfit78e1m2biiifpbv\",\n)\nprint(browser.session_id)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.Update(\n\t\tcontext.TODO(),\n\t\t\"htzv5orfit78e1m2biiifpbv\",\n\t\tkernel.BrowserUpdateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n" /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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.browsers.loadExtensions('id', {\n extensions: [{ name: 'name', zip_file: fs.createReadStream('path/to/file') }],\n});" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nclient.browsers.load_extensions(\n id=\"id\",\n extensions=[{\n \"name\": \"name\",\n \"zip_file\": b\"Example data\",\n }],\n)" - lang: Go source: "package main\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"io\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Browsers.LoadExtensions(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserLoadExtensionsParams{\n\t\t\tExtensions: []kernel.BrowserLoadExtensionsParamsExtension{{\n\t\t\t\tName: \"name\",\n\t\t\t\tZipFile: io.Reader(bytes.NewBuffer([]byte(\"Example data\"))),\n\t\t\t}},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n" /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: - 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/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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.browsers.computer.batch('id', { actions: [{ type: 'click_mouse' }] });" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nclient.browsers.computer.batch(\n id=\"id\",\n actions=[{\n \"type\": \"click_mouse\"\n }],\n)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Browsers.Computer.Batch(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserComputerBatchParams{\n\t\t\tActions: []kernel.BrowserComputerBatchParamsAction{{\n\t\t\t\tType: \"click_mouse\",\n\t\t\t}},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n" /browsers/{id}/computer/get_mouse_position: post: summary: Get the current mouse cursor position on the browser instance operationId: getMousePosition tags: - Browsers 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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.computer.getMousePosition('id');\n\nconsole.log(response.x);" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.computer.get_mouse_position(\n \"id\",\n)\nprint(response.x)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Computer.GetMousePosition(context.TODO(), \"id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.X)\n}\n" /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';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.curl('id', { url: 'url' });\n\nconsole.log(response.body);" - lang: Python source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.browsers.curl(\n id=\"id\",\n url=\"url\",\n)\nprint(response.body)" - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Curl(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserCurlParams{\n\t\t\tURL: \"url\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Body)\n}\n" components: 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 BrowserTelemetryCategoryConfig: type: object description: Per-category telemetry configuration. properties: enabled: type: boolean description: Whether this category is captured. Defaults to true if omitted. 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 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 BrowserUpdateRequest: type: object description: Request body for updating a browser session. properties: proxy_id: type: string nullable: true description: ID of the proxy to use. Omit to leave unchanged, set to empty string to remove proxy. disable_default_proxy: type: boolean description: If true, stealth browsers connect directly instead of using the default stealth proxy. profile: $ref: '#/components/schemas/BrowserProfile' description: Profile to load into the browser session. Only allowed if the session does not already have a profile loaded. viewport: $ref: '#/components/schemas/BrowserViewportUpdate' description: Viewport configuration to apply to the browser session. telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' nullable: true description: 'Telemetry configuration. Omit, set to null, or set to an empty object ({}) to leave the existing configuration unchanged (no-op). To enable capture for all categories using VM defaults, set browser to an empty object ({"browser": {}}). To stop capture, set every category''s enabled to false. ' 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' 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 SetCursorRequest: type: object required: - hidden properties: hidden: type: boolean description: Whether the cursor should be hidden or visible 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 BrowserTelemetryConfig: type: object description: Telemetry configuration for a browser session. properties: browser: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: Per-category enable/disable flags. If omitted, all categories are captured. 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 BrowserRequest: type: object description: 'Parameters for creating a browser session. ' properties: invocation_id: type: string description: action invocation ID example: rr33xuugxj9h0bkf1rdt2bet stealth: type: boolean description: If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. example: true headless: type: boolean description: If true, launches the browser using a headless image (no VNC/GUI). Defaults to false. example: false gpu: type: boolean description: If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan and headless=false. example: false timeout_seconds: type: integer description: The number of seconds of inactivity before the browser session is terminated. Activity includes CDP connections and live view connections. Defaults to 60 seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We check for inactivity every 5 seconds, so the actual timeout behavior you will see is +/- 5 seconds around the specified value. minimum: 10 maximum: 259200 profile: $ref: '#/components/schemas/BrowserProfile' extensions: type: array description: List of browser extensions to load into the session. Provide each by id or name. maxItems: 20 items: $ref: '#/components/schemas/BrowserExtension' proxy_id: type: string description: Optional proxy to associate to the browser session. Must reference a proxy belonging to the caller's org. viewport: $ref: '#/components/schemas/BrowserViewport' kiosk_mode: type: boolean description: If true, launches the browser in kiosk mode to hide address bar and tabs in live view. example: true start_url: type: string description: Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created. example: https://example.com chrome_policy: type: object additionalProperties: true description: 'Custom Chrome enterprise policy overrides applied to this browser session. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/ ' telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' nullable: true description: Telemetry configuration for the browser session. If provided, telemetry capture starts with the specified category filter when the session is created. If omitted, no telemetry capture is started. required: [] 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 BrowserTelemetryCategoriesConfig: type: object description: Per-category telemetry capture settings. properties: console: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Console output (log, warn, error) and uncaught exceptions. page: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. interaction: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: User interaction events including clicks, keydowns, and scroll-settled events. network: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: HTTP request and response metadata including URL, method, status code, and timing. Request post data is forwarded as-is from CDP. Text response bodies are truncated at 8 KB for structured types (JSON, XML, form data) and 4 KB for other text types. Binary responses (images, fonts, media) are excluded. 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 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 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 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 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 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 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 BrowserUsage: type: object description: Session usage metrics. properties: uptime_ms: type: integer description: Time in milliseconds the session was actively running. required: - uptime_ms Profile: type: object description: Browser profile metadata. properties: id: type: string description: Unique identifier for the profile name: type: string nullable: true description: Optional, easier-to-reference name for the profile created_at: type: string format: date-time description: Timestamp when the profile was created updated_at: type: string format: date-time description: Timestamp when the profile was last updated last_used_at: type: string format: date-time description: Timestamp when the profile was last used required: - id - created_at BrowserPoolRef: type: object description: Browser pool this session was acquired from, if any. properties: id: type: string description: Browser pool ID name: type: string description: Browser pool name, if set required: - id 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 Browser: type: object properties: created_at: type: string format: date-time description: When the browser session was created. cdp_ws_url: type: string description: Websocket URL for Chrome DevTools Protocol connections to the browser session example: wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi... webdriver_ws_url: type: string description: Websocket URL for WebDriver BiDi connections to the browser session example: wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi... browser_live_view_url: type: string description: Remote URL for live viewing the browser session. Only available for non-headless browsers. example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi... base_url: type: string description: Metro-API HTTP base URL for this browser session. example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel headless: type: boolean description: Whether the browser session is running in headless mode. example: false stealth: type: boolean description: Whether the browser session is running in stealth mode. example: false gpu: type: boolean description: Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). example: false session_id: type: string description: Unique identifier for the browser session example: htzv5orfit78e1m2biiifpbv timeout_seconds: type: integer description: The number of seconds of inactivity before the browser session is terminated. profile: $ref: '#/components/schemas/Profile' proxy_id: type: string description: ID of the proxy associated with this browser session, if any. pool: $ref: '#/components/schemas/BrowserPoolRef' viewport: $ref: '#/components/schemas/BrowserViewport' kiosk_mode: type: boolean description: Whether the browser session is running in kiosk mode. example: false start_url: type: string description: URL the session was asked to navigate to on creation, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. example: https://example.com chrome_policy: type: object additionalProperties: true description: 'Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. ' deleted_at: type: string format: date-time description: When the browser session was soft-deleted. Only present for deleted sessions. usage: $ref: '#/components/schemas/BrowserUsage' telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' nullable: true description: Active telemetry configuration for the session, if any. required: - created_at - cdp_ws_url - webdriver_ws_url - session_id - stealth - headless - timeout_seconds 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. ' BrowserViewport: type: object description: 'Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable). ' properties: width: type: integer description: Browser window width in pixels. minimum: 320 maximum: 7680 example: 1280 height: type: integer description: Browser window height in pixels. minimum: 240 maximum: 4320 example: 800 refresh_rate: type: integer description: Display refresh rate in Hz. If omitted, automatically determined from width and height. example: 60 required: - width - height 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 responses: NotFound: description: Resource not found 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' Forbidden: description: Forbidden – insufficient permissions or plan content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized – missing or invalid authorization token content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too Many Requests – rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: Bad Request – invalid input content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer