> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-mintlify-add-deploy-button-docs-27400.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.yaml post /browsers openapi: 3.1.0 info: title: Kernel API description: Developer tools and cloud infrastructure for AI agents to use web browsers version: 0.1.0 servers: - url: https://api.onkernel.com description: API Server security: - bearerAuth: [] tags: - name: Invocations description: Invoke actions and stream or query invocation status and events. - name: Browsers description: >- Create and manage browser sessions, filesystem, processes, logs, and replays. - name: Proxies description: Create and manage proxy configurations for routing browser traffic. - name: Deployments description: Create and manage app deployments and stream deployment events. - name: Apps description: List applications and versions. - name: Profiles description: Create, list, retrieve, and delete browser profiles. - name: Extensions description: Create, list, retrieve, and delete browser extensions. - name: Browser Pools description: Create and manage browser pools for acquiring and releasing browsers. - name: Agent Auth description: Agent authentication flow endpoints for hosted credential capture. 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': 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' security: - bearerAuth: [] components: schemas: BrowserRequest: type: object description: | Parameters for creating a browser session. properties: invocation_id: type: string description: action invocation ID example: rr33xuugxj9h0bkf1rdt2bet persistence: $ref: '#/components/schemas/BrowserPersistence' deprecated: true x-deprecated-reason: Use timeout_seconds (up to 72 hours) and Profiles instead 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 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 required: [] 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://api.onkernel.com/browser/cdp?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://api.onkernel.com/browser/remote?jwt=eyJ0eXAi... 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 session_id: type: string description: Unique identifier for the browser session example: htzv5orfit78e1m2biiifpbv persistence: $ref: '#/components/schemas/BrowserPersistence' 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. viewport: $ref: '#/components/schemas/BrowserViewport' kiosk_mode: type: boolean description: Whether the browser session is running in kiosk mode. example: false deleted_at: type: string format: date-time description: >- When the browser session was soft-deleted. Only present for deleted sessions. required: - created_at - cdp_ws_url - session_id - stealth - headless - timeout_seconds BrowserPersistence: type: object description: 'DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.' deprecated: true x-deprecated-reason: Use timeout_seconds (up to 72 hours) and Profiles instead properties: id: type: string description: 'DEPRECATED: Unique identifier for the persistent browser session.' example: my-awesome-browser-for-user-1234 required: - id 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 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 BrowserViewport: type: object description: > Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). Only specific viewport configurations are supported. The server will reject unsupported combinations. Supported resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will be automatically determined from the width and height if they match a supported configuration exactly. Note: Higher resolutions may affect the responsiveness of live view browser 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 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 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' 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 responses: BadRequest: description: Bad Request – invalid input content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized – missing or invalid authorization token content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden – insufficient permissions or plan 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' securitySchemes: bearerAuth: type: http scheme: bearer ````