> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-document-proxy-admission.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a browser session > Create a new browser session from within an action. ## OpenAPI ````yaml https://api.onkernel.com/spec.json post /browsers openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: Execute Playwright code against the browser instance. name: Browser Playwright - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: Stream live telemetry events from a browser session. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - 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: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Site Configs paths: /browsers: post: tags: - Browsers summary: Create a browser session description: Create a new browser session from within an action. operationId: postBrowsers requestBody: content: application/json: schema: $ref: '#/components/schemas/BrowserRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Browser' description: Successful response '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' security: - bearerAuth: [] components: schemas: BrowserRequest: description: | Parameters for creating a browser session. properties: chrome_policy: 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/ type: object extensions: description: >- List of browser extensions to load into the session. Provide each by id or name. items: $ref: '#/components/schemas/BrowserExtension' maxItems: 20 type: array gpu: description: >- If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan and headless=false. example: false type: boolean headless: description: >- If true, launches the browser using a headless image (no VNC/GUI). Defaults to false. example: false type: boolean invocation_id: description: action invocation ID example: rr33xuugxj9h0bkf1rdt2bet type: string kiosk_mode: description: >- If true, launches the browser in kiosk mode to hide address bar and tabs in live view. example: true type: boolean name: 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}. example: checkout-flow-1 maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string network: $ref: '#/components/schemas/BrowserNetworkConfig' description: > Network configuration for the browser session. Cannot be changed after creation. profile: $ref: '#/components/schemas/BrowserProfile' proxy: $ref: '#/components/schemas/BrowserProxyConfig' description: > Proxy configuration for the browser session. Cannot be combined with proxy_id. Omit to use the browser default: stealth browsers use Kernel's default stealth proxy, while non-stealth browsers use direct egress. Set mode to direct to force direct egress regardless of stealth. Set mode to default to explicitly use the browser default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. Select id or name to use that proxy regardless of stealth. Proxy selection does not change stealth or CAPTCHA solver behavior. proxy_id: deprecated: true description: >- Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session. Deprecated in favor of proxy. type: string x-deprecated-reason: Use proxy instead. region: $ref: '#/components/schemas/Region' description: > Geographic region for the browser session. It is fixed once the session is created. Region selection requires a Start-Up or Enterprise plan, defaults to us-east when omitted on create. start_url: 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 type: string stealth: description: > If true, launches the browser in stealth mode and enables the CAPTCHA solver. Defaults to false. When proxy is omitted, stealth browsers use Kernel's default stealth proxy and non-stealth browsers use direct egress. An explicit proxy configuration changes only egress; it does not enable or disable stealth or the CAPTCHA solver. example: true type: boolean 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. telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' 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. nullable: true timeout_seconds: 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. maximum: 259200 minimum: 10 type: integer viewport: $ref: '#/components/schemas/BrowserViewport' required: [] type: object Browser: properties: base_url: description: Metro-API HTTP base URL for this browser session. example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel type: string browser_live_view_url: 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... type: string cdp_ws_url: 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... type: string chrome_policy: 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. type: object created_at: description: When the browser session was created. format: date-time type: string deleted_at: description: >- When the browser session was soft-deleted. Only present for deleted sessions. format: date-time type: string gpu: description: >- Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). example: false type: boolean headless: description: Whether the browser session is running in headless mode. example: false type: boolean kiosk_mode: description: Whether the browser session is running in kiosk mode. example: false type: boolean name: description: >- Human-readable name of the browser session, if one was set at creation. example: checkout-flow-1 type: string network: $ref: '#/components/schemas/BrowserNetworkConfig' description: >- Network configuration the session was created with, if any. Omitted when the session has no network configuration. pool: $ref: '#/components/schemas/BrowserPoolRef' profile: $ref: '#/components/schemas/Profile' profile_save_changes: description: >- Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached. type: boolean proxy: $ref: '#/components/schemas/BrowserProxy' description: Resolved proxy configuration for this browser session. proxy_id: deprecated: true description: >- ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy. type: string x-deprecated-reason: Use proxy instead. region: $ref: '#/components/schemas/Region' description: > Geographic region of the browser session. Fixed once the session is created. session_id: description: Unique identifier for the browser session example: htzv5orfit78e1m2biiifpbv type: string start_url: 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 type: string stealth: description: Whether the browser session is running in stealth mode. example: false type: boolean tags: $ref: '#/components/schemas/Tags' description: >- User-defined key-value tags that were set on this browser session, if any. Echoed back when present. telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' description: Active telemetry configuration for the session, if any. nullable: true timeout_seconds: description: >- The number of seconds of inactivity before the browser session is terminated. type: integer usage: $ref: '#/components/schemas/BrowserUsage' viewport: $ref: '#/components/schemas/BrowserViewport' webdriver_ws_url: 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... type: string required: - created_at - cdp_ws_url - webdriver_ws_url - session_id - region - stealth - headless - timeout_seconds type: object BrowserExtension: description: > Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel. oneOf: - required: - id - required: - name properties: id: description: Extension ID to load for this browser session type: string name: description: >- Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string type: object BrowserNetworkConfig: description: | Network configuration for a browser session or browser pool. properties: private_hosts: description: > Destinations the browser reaches directly through the session's own network instead of through Kernel-managed egress — for private hosts reachable over a VPN or tunnel the session has joined (e.g. a Tailscale tailnet). By default, private IP ranges already route directly: RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), CGNAT/Tailscale (100.64.0.0/10), and IPv6 ULA (fc00::/7). An explicitly supplied list replaces those defaults with exactly the entries given, and an empty list ([]) disables them so all traffic uses Kernel-managed egress; omit private_hosts to keep the defaults. Entries are hostname patterns ("*.example.ts.net", "preview.internal") or IP/CIDR literals ("100.64.0.0/10", "10.1.30.63"). IP and CIDR entries only match URLs written with a literal IP address; they never match hostnames that resolve into the range, so private DNS names need a hostname entry even when they resolve inside the default ranges. CIDRs must be in canonical masked form (host bits zero), and only the private ranges listed above are accepted; public, loopback, link-local, and unspecified ranges are rejected. Exact IPv6 addresses must be bracketed ("[fd00::1]"); IPv6 CIDR ranges are unbracketed ("fd00::/8"). Wildcards are limited to one leading "*." over a suffix with at least two labels that is not a public suffix (so "*.co.uk" or "*.ts.net" are rejected, while "*.example.ts.net" is accepted). Hostname and IP entries may carry a port; CIDR ranges may not. Hostname entries are not resolved during validation, so callers must ensure they identify private destinations. Not related to a proxy's bypass_hosts, which selects between upstream-proxy and Kernel-managed direct egress and cannot reach into a VPN. example: - '*.example.ts.net' - 100.64.0.0/10 items: maxLength: 255 type: string maxItems: 32 type: array type: object BrowserProfile: 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. oneOf: - required: - id - required: - name properties: id: description: Profile ID to load for this browser session type: string name: description: >- Profile name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string save_changes: default: false description: >- If true, save changes made during the session back to the profile when the session ends. type: boolean type: object BrowserProxyConfig: additionalProperties: false description: > Browser proxy configuration. Provide exactly one of mode, id, or name; an empty object is invalid. Set mode to direct for no proxy regardless of stealth. Set mode to default to use the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. Select id or name to use that proxy regardless of stealth. The selected proxy must be in the same project as the browser. Names must match exactly one active proxy; use id for stable references. Proxy configuration changes only egress and does not change stealth or CAPTCHA solver behavior. A stealth browser using mode=direct still runs in stealth mode with the CAPTCHA solver enabled. When proxy is omitted on browser creation, stealth browsers use Kernel's default stealth proxy and non-stealth browsers use direct egress. When omitted on update, the current configuration is unchanged. oneOf: - required: - mode - required: - id - required: - name properties: id: description: Proxy ID. minLength: 1 type: string mode: $ref: '#/components/schemas/BrowserProxyMode' name: description: Proxy name. Must match exactly one active proxy in the project. minLength: 1 type: string type: object Region: description: | Geographic region for hosting browser sessions or pools. enum: - us-east - eu-west type: string Tags: additionalProperties: maxLength: 256 minLength: 0 pattern: ^[A-Za-z0-9 _.:/=+@-]*$ type: string description: User-defined key-value tags. example: env: staging team: backend maxProperties: 50 propertyNames: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9 _.:/=+@-]+$ type: string type: object BrowserTelemetryRequestConfig: description: Telemetry request configuration for a browser session. properties: 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. enabled: 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. type: boolean export: $ref: '#/components/schemas/BrowserTelemetryExportRequestConfig' description: >- Where to export this session's captured telemetry. Omit to capture without exporting. type: object BrowserViewport: 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: height: description: Browser window height in pixels. Any positive integer is accepted. example: 800 minimum: 1 type: integer refresh_rate: description: >- Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height. example: 60 minimum: 1 type: integer width: description: Browser window width in pixels. Any positive integer is accepted. example: 1280 minimum: 1 type: integer required: - width - height type: object BrowserPoolRef: description: Browser pool this session was acquired from, if any. properties: id: description: Browser pool ID type: string name: description: Browser pool name, if set type: string required: - id type: object Profile: description: Browser profile metadata. properties: created_at: description: Timestamp when the profile was created format: date-time type: string id: description: Unique identifier for the profile type: string last_used_at: description: Timestamp when the profile was last used format: date-time type: string name: description: Optional, easier-to-reference name for the profile nullable: true type: string updated_at: description: Timestamp when the profile was last updated format: date-time type: string required: - id - created_at type: object BrowserProxy: additionalProperties: false description: >- Resolved proxy configuration for a browser session. Selected proxies are returned by stable ID. oneOf: - required: - mode - required: - id - required: - name properties: id: description: Selected proxy ID. minLength: 1 type: string mode: $ref: '#/components/schemas/BrowserProxyMode' name: description: Selected proxy name. minLength: 1 type: string type: object BrowserTelemetryConfig: 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. type: object BrowserUsage: description: Session usage metrics. properties: uptime_ms: description: Time in milliseconds the session was actively running. type: integer required: - uptime_ms type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object BrowserProxyMode: description: > Proxy egress mode. direct forces no proxy regardless of stealth. default uses the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. default is primarily useful on browser update to restore the browser default after selected-proxy egress. enum: - direct - default type: string x-enum-varnames: - Direct - Default BrowserTelemetryCategoriesConfig: 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: captcha: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Captcha solve attempt outcomes. On by default. connection: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Client attach/detach lifecycle for the CDP proxy and live view. On by default. console: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Console output (log, warn, error) and uncaught exceptions. 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. 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. page: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. CDP category; off by default. screenshot: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Periodic base64-encoded viewport screenshots. High volume; off by default and must be opted into. system: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Browser VM health, such as out-of-memory kills and managed-service crashes. On by default. type: object BrowserTelemetryExportRequestConfig: 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. type: object BrowserTelemetryExportConfig: description: Active export state for a session's captured telemetry, by protocol. properties: otlp: $ref: '#/components/schemas/BrowserTelemetryOTLPExportConfig' description: Active OTLP export state. type: object ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object BrowserTelemetryCategoryConfig: description: Per-category telemetry configuration. properties: enabled: 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. type: boolean type: object BrowserTelemetryOTLPExportRequestConfig: description: OTLP export settings for a browser session. properties: 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. enabled: 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). type: boolean type: object BrowserTelemetryOTLPExportConfig: description: Active OTLP export state for a browser session. properties: destination: description: >- ID of the OTLP destination the session is bound to. Omitted when the session is not exporting. type: string enabled: description: Whether the session is exporting captured telemetry over OTLP. type: boolean type: object OTLPDestinationRef: 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. oneOf: - required: - id - required: - name properties: id: description: OTLP destination ID type: string name: description: OTLP destination name type: string type: object responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized – missing or invalid authorization token Forbidden: content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden – insufficient permissions or plan Conflict: content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict – resource already exists TooManyRequests: content: application/json: schema: $ref: '#/components/schemas/Error' description: Too Many Requests – rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error CapacityExhausted: content: application/json: schema: $ref: '#/components/schemas/Error' description: Capacity exhausted, unable to fulfill request at this time securitySchemes: bearerAuth: scheme: bearer type: http ````