---
title: "Create Browser Session"
method: POST
path: "/browser-sessions"
---

# Create Browser Session

`POST /browser-sessions`

## Request body

- CreateBrowserSessionRequest — Create and boot a browser session owned by one SDK client.
  - `session_id` string, nullable
  - `mode` 'headless' | 'live'
  - `backend` 'firecracker' | 'qemu' | 'libkrun' | 'auto'
  - `profile_mode` 'ephemeral' | 'persistent'
  - `profile_id` string, nullable
  - `timeout_minutes` integer
  - `viewport` BrowserViewportRequest — Requested browser viewport in CSS pixels.
    - `width` integer
    - `height` integer
  - `record_video` boolean
  - `allow_downloads` boolean
  - `memory` integer
  - `disk_size` integer
  - `network` union
    - OpenNetworkPolicy — Allow all outbound network access.
      - `mode` 'open', required
    - OffNetworkPolicy — Block outbound network access.
      - `mode` 'off', required
    - RestrictedNetworkPolicy — Allow outbound access only to the supplied IPv4 ranges.
      - `mode` 'restricted', required
      - `allowed_cidrs` string[], required

## Response `201`

Successful Response

- BrowserSessionResponse — Ready browser session endpoints returned only to the owning SDK client.
  - `session_id` string, required
  - `sandbox_id` string, required
  - `status` 'created' | 'starting' | 'ready' | 'stopping' | 'error' | 'deleted', required — Browser session lifecycle states.
  - `cdp_url` string, required
  - `viewer_url` string, nullable
  - `display_url` string, nullable
  - `profile_id` string, nullable

## Other responses

- `400` — Bad Request
- `422` — Validation Error

## Changes

- **2026-09-14** `4d88cab246b2` — 1 warning
  - added the new `deleted` enum value to the `status` response property for the response status `201`
- **2026-09-14** `9d26ec55ddc6` — 1 info
  - added the optional property `display_url` to the response with the `201` status
- **2026-09-13** `1c971ff55cd2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/celestoai/apis/smolvm/changes/browser-sessions/post.md)

---

[API](https://skmtc.dev/celestoai/apis/smolvm.md) · [All operations](https://skmtc.dev/celestoai/apis/smolvm/llms.txt) · [OpenAPI document](https://skmtc.dev/celestoai/apis/smolvm/revisions/4d88cab246b2?raw)