> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-changelog-august-13.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update a browser pool > Updates the configuration used to create browsers in the pool. As with creation, save_changes on the pool profile is ignored (not rejected); pooled browsers never persist changes back to the profile. To clear the profile reference, send `profile: { "id": "" }`. Clearing the profile also disables `refresh_on_profile_update`. ## OpenAPI ````yaml https://api.onkernel.com/spec.json patch /browser_pools/{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. 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: /browser_pools/{id_or_name}: patch: tags: - Browser Pools summary: Update a browser pool description: > Updates the configuration used to create browsers in the pool. As with creation, save_changes on the pool profile is ignored (not rejected); pooled browsers never persist changes back to the profile. To clear the profile reference, send `profile: { "id": "" }`. Clearing the profile also disables `refresh_on_profile_update`. operationId: updateBrowserPoolsByIdOrName parameters: - description: Browser pool ID or name in: path name: id_or_name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BrowserPoolUpdateRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BrowserPool' description: Browser pool details '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: BrowserPoolUpdateRequest: description: > Parameters for updating a browser pool. Omitted fields leave existing values unchanged. properties: chrome_policy: additionalProperties: true description: > If provided, replaces the custom Chrome enterprise policy overrides applied to all browsers in this pool. Empty object clears any previously-set policy. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/ The serialized JSON payload is capped at 5 MiB. type: object discard_all_idle: default: false description: >- Whether to discard all idle browsers and rebuild them immediately with the new configuration. Defaults to false. Only browsers that are idle when the update runs are rebuilt. A browser that is in use during the update keeps its original configuration, and if it is later released with `reuse: true` it returns to the pool with that stale configuration until it is discarded (by this flag on a later update, or by flushing the pool). example: false type: boolean extensions: description: > If provided, replaces the extension list. Empty array clears all previously-selected extensions. Omit this field to leave extensions unchanged. items: $ref: '#/components/schemas/BrowserExtension' maxItems: 20 type: array fill_rate_per_minute: description: > If provided, replaces the percentage of the pool to fill per minute. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here. minimum: 0 type: integer headless: description: >- If provided, replaces whether browsers launch using a headless image. example: false type: boolean kiosk_mode: description: If provided, replaces whether browsers launch in kiosk mode. example: true type: boolean name: description: > If provided, replaces the pool name. Empty string is a no-op; the pool name cannot be cleared or reset to empty once assigned. example: my-pool pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string network: $ref: '#/components/schemas/BrowserNetworkConfig' description: > If provided, replaces the pool's network configuration. Omit to leave the existing configuration unchanged; an empty object ({}) removes it, while network: {private_hosts: []} sets an explicit empty list. Only applied to browsers created in the pool after the update; browsers already in the pool keep their configuration until discarded (see discard_all_idle). profile: allOf: - $ref: '#/components/schemas/BrowserPoolProfile' description: > If provided, replaces the previously-selected profile. To clear the profile reference, send `{ "id": "" }` or `{ "name": "" }`. An empty object (no id or name) is rejected as 400. proxy_id: description: >- Empty string clears the previously-selected proxy. Omit this field to leave the proxy unchanged. type: string refresh_on_profile_update: description: > If provided, replaces whether idle browsers are flushed when the profile the pool uses is updated. When the pool's profile reference is changed (including newly attached) and this field is omitted, it defaults to true. Re-sending the same profile reference leaves this setting unchanged. Clearing the profile also disables this setting. Requires a profile to be set on the pool. example: true type: boolean size: description: > If provided, replaces the number of browsers to maintain in the pool. The maximum size is determined by your organization's pooled sessions limit (the sum of all pool sizes cannot exceed your limit). example: 10 minimum: 1 type: integer start_url: description: > If provided, replaces the URL to navigate to when a new browser is warmed into the pool. Empty string clears the previously-set URL. Omit this field to leave it unchanged. example: https://example.com maxLength: 2048 type: string stealth: description: If provided, replaces whether browsers launch in stealth mode. example: true type: boolean telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' description: > If provided, updates the pool's telemetry configuration. Omit, set to null, or set to an empty object ({}) to leave the existing configuration unchanged. Set enabled to true to enable capture using the default set. Set enabled to false to clear the pool's telemetry. Provide browser category settings for per-category updates, merged onto the pool's current configuration. Only applied to browsers warmed after the update; browsers already in the pool keep their configuration until discarded. nullable: true timeout_seconds: description: >- If provided, replaces the default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). maximum: 259200 minimum: 10 type: integer viewport: allOf: - $ref: '#/components/schemas/BrowserViewport' description: > If provided, replaces the viewport with the new width/height/refresh_rate. Because width and height are required and must be positive, the viewport cannot be cleared; omit this field to leave it unchanged. type: object BrowserPool: description: A browser pool containing multiple identically configured browsers. properties: acquired_count: description: Number of browsers currently acquired from the pool example: 15 type: integer available_count: description: Number of browsers currently available in the pool example: 85 type: integer browser_pool_config: $ref: '#/components/schemas/BrowserPoolConfig' description: Configuration used to create all browsers in this pool created_at: description: Timestamp when the browser pool was created format: date-time type: string extension_ids: description: >- Resolved extension IDs attached to the pool, in configured load order. Empty when no extensions are attached. Authoritative for programmatic consumers; the extensions inside `browser_pool_config` reflect the configured selector (echoed as sent on create). items: type: string type: array id: description: Unique identifier for the browser pool example: iv25ujqf37x3j07dwoffegqr type: string name: description: Browser pool name, if set example: my-pool type: string profile_id: description: >- Resolved profile ID the pool is attached to. Omitted when no profile is attached. Authoritative for programmatic consumers; the profile inside `browser_pool_config` reflects the configured selector (echoed as sent on create). example: iv25ujqf37x3j07dwoffegqr type: string region: $ref: '#/components/schemas/Region' description: > Geographic region of the browser pool. Fixed once the pool is created. required: - id - available_count - acquired_count - created_at - region - browser_pool_config - extension_ids 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 BrowserPoolProfile: description: > Profile configuration for browsers in a pool. Provide either id or name. Profiles must be created beforehand. Unlike single browser sessions, pools load the profile read-only and never persist changes back to it, so save_changes is omitted here. Any save_changes value sent on a pool profile is silently ignored rather than rejected. oneOf: - required: - id - required: - name properties: id: description: Profile ID to load for browsers in this pool type: string name: description: >- Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ 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 BrowserPoolConfig: description: | Effective browser pool configuration returned by the API. properties: chrome_policy: additionalProperties: true description: > Custom Chrome enterprise policy overrides applied to all browsers in this pool. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/ The serialized JSON payload is capped at 5 MiB. 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 fill_rate_per_minute: description: >- Percentage of the pool to fill per minute. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here. minimum: 0 type: integer headless: description: If true, launches the browser using a headless image. example: false type: boolean 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 name for the browser pool. Must be unique within the project. example: my-pool pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string network: $ref: '#/components/schemas/BrowserNetworkConfig' description: >- Network configuration applied to browsers in this pool, if any. Omitted when the pool has no network configuration. profile: allOf: - $ref: '#/components/schemas/BrowserPoolProfile' description: Profile selection for browsers in the pool. proxy_id: description: >- Optional proxy associated to the browser session. References a proxy in the same project as the browser session. type: string refresh_on_profile_update: description: > When true, flush idle browsers when the profile the pool uses is updated, so pool browsers pick up the latest profile data. When a profile is provided during creation, this defaults to true. Requires a profile to be set on the pool. example: true type: boolean size: description: > Number of browsers maintained in the pool. The maximum size is determined by your organization's pooled sessions limit (the sum of all pool sizes cannot exceed your limit). example: 10 minimum: 1 type: integer start_url: description: > Optional URL to navigate to when a new browser is warmed into the pool. Best-effort: failures to navigate do not fail pool fill. Only applied to newly-warmed browsers; browsers reused via release/acquire keep whatever URL the previous lease left them on. Accepts any URL Chromium can resolve, including chrome:// pages. example: https://example.com maxLength: 2048 type: string stealth: description: >- If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. example: true type: boolean telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' description: >- Active telemetry configuration applied to browsers warmed into this pool, if any. nullable: true timeout_seconds: description: >- Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). maximum: 259200 minimum: 10 type: integer viewport: allOf: - $ref: '#/components/schemas/BrowserViewport' description: Browser viewport used for newly-warmed browsers in this pool. required: - size type: object Region: description: | Geographic region for hosting browser sessions or pools. enum: - us-east - eu-west type: string 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 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 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 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 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 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 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 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 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 securitySchemes: bearerAuth: scheme: bearer type: http ````