> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapengine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Session

> Create a persistent, remote-controlled browser session with optional stealth, extensions, and proxy settings.

## Overview

Creates a new browser session backed by a sandboxed VM. The session stays alive until it hits `timeout` of inactivity, you destroy it explicitly, or it expires at `expiresAt`.

Returns a `cdpUrl` you can attach to with any Chrome DevTools Protocol client (Playwright, Puppeteer, chromedp), plus a `liveViewUrl` for an interactive noVNC view.

## Body

<ParamField body="capabilities" type="string[]">
  Runtime capabilities to enable on the session. Supported values include `stealth` (anti-bot evasion) and `recording` (server-side MP4 capture).
</ParamField>

<ParamField body="extensions" type="string[]">
  Extension IDs to load into the browser. Upload extensions first via `POST /browser/extensions`.
</ParamField>

<ParamField body="proxyUrl" type="string">
  Raw proxy URL (e.g. `http://user:pass@host:port`). Mutually exclusive with `proxy`.
</ParamField>

<ParamField body="proxy" type="object">
  Managed proxy options. Mutually exclusive with `proxyUrl`.

  <Expandable title="proxy fields">
    <ParamField body="location" type="string">
      Country code for the exit IP (e.g. `us`, `gb`, `de`).
    </ParamField>

    <ParamField body="provider" type="string">
      Proxy provider. One of `oxylabs`, `evomi`.
    </ParamField>

    <ParamField body="sticky" type="boolean" default="true">
      Keep the same exit IP for the life of the session.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="timeout" type="integer" default="900000">
  Idle timeout in ms before the session auto-terminates. Default 15 minutes.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL (minimal) theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions" \
    -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```

  ```bash cURL (stealth + US proxy) theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions" \
    -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "capabilities": ["stealth"],
      "proxy": { "location": "us", "provider": "oxylabs", "sticky": true },
      "timeout": 1800000
    }'
  ```
</CodeGroup>

## Response

### Success Response (201)

<ResponseField name="id" type="string">
  Session ID (UUID). Use this as `{id}` in all other browser session endpoints.
</ResponseField>

<ResponseField name="status" type="string">
  Current state — typically `ready` when the session is immediately usable.
</ResponseField>

<ResponseField name="cdpUrl" type="string">
  Chrome DevTools Protocol WebSocket URL. Attach any CDP client here.
</ResponseField>

<ResponseField name="liveViewUrl" type="string">
  Shareable noVNC URL for interactive live view.
</ResponseField>

<ResponseField name="capabilities" type="string[]">
  Capabilities enabled on this session.
</ResponseField>

<ResponseField name="extensions" type="string[]">
  Extension IDs loaded into the browser.
</ResponseField>

<ResponseField name="proxyUrl" type="string">
  Raw proxy URL, when the session was created with `proxyUrl`.
</ResponseField>

<ResponseField name="proxy" type="object">
  Managed proxy info — `enabled`, `provider`, `location`, `sticky`.
</ResponseField>

<ResponseField name="createdAt" type="integer">
  Unix epoch milliseconds when the session was created.
</ResponseField>

<ResponseField name="expiresAt" type="integer">
  Unix epoch milliseconds when the session will auto-expire absent activity.
</ResponseField>

**Example Response:**

```json theme={null}
{
  "id": "baa3f390-fa6e-4a24-b84a-a575a5f3a9c7",
  "status": "ready",
  "cdpUrl": "wss://cdp.scrapengine.io/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7",
  "liveViewUrl": "https://live.scrapengine.io/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7",
  "capabilities": ["stealth"],
  "extensions": [],
  "proxy": { "enabled": true, "provider": "oxylabs", "location": "us", "sticky": true },
  "createdAt": 1714000000000,
  "expiresAt": 1714001800000
}
```

### Error Responses

| Status | Description                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Invalid body — e.g. more than 20 extensions requested, or a validation error on a field.                                       |
| `401`  | Unauthorized — invalid or missing API key.                                                                                     |
| `503`  | Maximum concurrent sessions reached for this account, the browser pool cannot allocate a sandbox, or VM initialization failed. |