> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-stagehand-v4-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update browser session > Update a browser session. ## OpenAPI ````yaml https://api.onkernel.com/spec.json patch /browsers/{id_or_name} 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, and manage the destinations sessions export them to. 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/{id_or_name}: patch: tags: - Browsers summary: Update browser session description: Update a browser session. operationId: patchBrowsersByIdOrName parameters: - description: Browser session ID or name example: htzv5orfit78e1m2biiifpbv in: path name: id_or_name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BrowserUpdateRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Browser' description: Browser session updated successfully '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' security: - bearerAuth: [] components: schemas: BrowserUpdateRequest: description: Request body for updating a browser session. properties: disable_default_proxy: deprecated: true description: >- If true, stealth browsers connect directly instead of using the default stealth proxy. Deprecated in favor of proxy.mode. type: boolean x-deprecated-reason: Use proxy.mode instead. name: 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. example: checkout-flow-1 maxLength: 255 minLength: 1 nullable: true pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string 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. proxy: $ref: '#/components/schemas/BrowserProxyConfig' description: > Proxy configuration to apply. Omit to leave the current configuration unchanged. Cannot be combined with proxy_id or disable_default_proxy. Set mode to direct to switch to direct egress regardless of stealth. Set mode to default to restore the browser default after using a selected proxy: Kernel's default stealth proxy for a stealth browser, or direct egress for a non-stealth browser. Updating proxy does not change stealth or CAPTCHA solver behavior. proxy_id: deprecated: true description: >- ID of the proxy to use. Omit to leave unchanged, set to empty string to remove proxy. Deprecated in favor of proxy. nullable: true type: string x-deprecated-reason: Use proxy instead. tags: $ref: '#/components/schemas/Tags' 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. nullable: true telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' 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. nullable: true viewport: $ref: '#/components/schemas/BrowserViewportUpdate' description: Viewport configuration to apply to the browser session. 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 memory: $ref: '#/components/schemas/BrowserMemory' description: Memory allocated to the browser session. 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 - memory - timeout_seconds 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 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 BrowserViewportUpdate: allOf: - $ref: '#/components/schemas/BrowserViewport' - properties: force: 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. type: boolean type: object description: >- Viewport configuration for updating a browser session. Extends BrowserViewport with update-only options. BrowserMemory: description: Memory allocated to the browser session. enum: - 1GiB - 2GiB - 6GiB - 8GiB - 16GiB example: 8GiB type: string 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 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 Region: description: | Geographic region for hosting browser sessions or pools. enum: - us-east - eu-west type: string 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 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 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 exist in the project the request resolves to. 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 NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource not found Conflict: content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict – resource already exists InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````