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

# Create CDP Session

> Launch a dedicated Chromium instance and receive a CDP base URL with an embedded data token for authenticated browser control.

Create a new dedicated CDP session. The server starts a Chromium instance, applies your `browserSettings`, and returns a `cdpBaseUrl` you can pass directly to `playwright.connectOverCDP()` or use for manual CDP discovery.

<ParamField body="idleTimeoutMs" type="number">
  Milliseconds of inactivity before the session is terminated. Values above the server cap are silently clamped.
</ParamField>

<ParamField body="maxSessionMs" type="number">
  Maximum total lifetime of the session in milliseconds. Values above the server cap are silently clamped.
</ParamField>

<ParamField body="browserSettings" type="object">
  Browser configuration applied when the Chromium instance starts.

  <Expandable title="browserSettings fields">
    <ParamField body="viewport" type="object">
      Browser window dimensions: `{ "width": number, "height": number }`. CDP sessions apply these as the `--window-size` launch argument.
    </ParamField>

    <ParamField body="locale" type="string">
      Browser locale, e.g. `en-US`.
    </ParamField>

    <ParamField body="timezoneId" type="string">
      IANA timezone identifier, e.g. `Asia/Shanghai`.
    </ParamField>

    <ParamField body="geolocation" type="object">
      Geographic coordinates: `{ "latitude": number, "longitude": number }`.
    </ParamField>

    <ParamField body="proxy" type="object">
      Custom proxy configuration. Cannot be combined with `countryCode`.

      <Expandable title="proxy fields">
        <ParamField body="server" type="string">
          Full proxy URL such as `http://host:port` or `socks5://host:port`. Do not embed credentials here; provide them via `username` and `password` separately. Cannot be combined with `host`.
        </ParamField>

        <ParamField body="protocol" type="string">
          Proxy protocol for the split form: `http` or `socks5`.
        </ParamField>

        <ParamField body="host" type="string">
          Proxy host for the split form.
        </ParamField>

        <ParamField body="port" type="number">
          Proxy port (1 to 65535) for the split form.
        </ParamField>

        <ParamField body="username" type="string">
          Proxy username.
        </ParamField>

        <ParamField body="password" type="string">
          Proxy password.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="countryCode" type="string">
      Managed proxy region. Use `"GLOBAL"` to select a popular region automatically, or a specific region code for trusted proxies with dynamic fallback. Omitting this field picks a random trusted proxy.
    </ParamField>

    <ParamField body="userAgent" type="string">
      Override the default User-Agent string.
    </ParamField>

    <ParamField body="userAgentMode" type="string">
      Set to `"random"` to have the server choose from its User-Agent library. Requests without a User-Agent default to `"random"`.
    </ParamField>

    <ParamField body="userAgentOs" type="string">
      Operating system used when `userAgentMode` is `"random"`. Accepts `"windows"` (default) or `"macos"`.
    </ParamField>

    <ParamField body="fingerprint" type="object">
      CDP fingerprint overrides. When omitted, `canvas` and `webGlImage` default to `real`; all other signals are generated from a coherent randomized profile.

      <Expandable title="fingerprint fields">
        <ParamField body="webRtc" type="string">
          `"forward"` uses the proxy exit address; `"real"` or `"disabled"` also accepted.
        </ParamField>

        <ParamField body="webGl" type="string">
          WebGL vendor and renderer metadata: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="webGpu" type="string">
          `"random"` follows the WebGL GPU selection. Also accepts `"real"` or `"disabled"`. Cannot be `"random"` when `webGlImage` is `"real"`.
        </ParamField>

        <ParamField body="webGlImage" type="string">
          WebGL image noise: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="canvas" type="string">
          Canvas noise: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="audioContext" type="string">
          Audio fingerprint noise: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="clientRects" type="string">
          Layout measurement noise: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="speechVoices" type="string">
          OS-matched speech voice list: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="fonts" type="string">
          OS-matched font list: `"random"` or `"real"`.
        </ParamField>

        <ParamField body="hardware" type="string">
          CPU thread count and memory (generated as a pair): `"random"` or `"real"`.
        </ParamField>

        <ParamField body="doNotTrack" type="string">
          Do Not Track preference: `"random"`, `"enabled"`, or `"disabled"`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="cookies" type="array">
      Cookies injected into the browser context before the session starts.

      <Expandable title="cookie fields">
        <ParamField body="name" type="string" required>
          Cookie name.
        </ParamField>

        <ParamField body="value" type="string" required>
          Cookie value.
        </ParamField>

        <ParamField body="domain" type="string" required>
          Target domain, e.g. `.example.com`.
        </ParamField>

        <ParamField body="path" type="string">
          Cookie path. Defaults to `/`.
        </ParamField>

        <ParamField body="secure" type="boolean">
          When `true`, the cookie is only sent over HTTPS.
        </ParamField>

        <ParamField body="httpOnly" type="boolean">
          When `true`, the cookie is inaccessible to client-side JavaScript.
        </ParamField>

        <ParamField body="sameSite" type="string">
          SameSite attribute value.
        </ParamField>

        <ParamField body="session" type="boolean">
          Set to `true` for a session cookie.
        </ParamField>

        <ParamField body="expirationDate" type="number">
          Unix expiry timestamp in seconds. Also accepted as `expires` or `expiry`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="sessionId" type="string">
  Unique identifier for the active session. Use it for all subsequent list, delete, and CDP requests.
</ResponseField>

<ResponseField name="expiresAt" type="string">
  RFC 3339 timestamp when the session will expire.
</ResponseField>

<ResponseField name="cdpBaseUrl" type="string">
  Fully formed base URL for this session. Pass it directly to `playwright.connectOverCDP()`. It already contains the data token as a query parameter: do not replace or append your API key.
</ResponseField>

<Note>
  The `cdpBaseUrl` carries an embedded data token that authorizes CDP access. Never replace that token with your `x-api-key`. Store it securely and treat it with the same care as a credential.
</Note>

| Status | Meaning |
| - | - |
| `201` | Session created successfully. |
| `400` | Invalid managed region, custom proxy, or random User-Agent parameters. |
| `401` | Missing or invalid `x-api-key`. |
| `429` | The API key has reached its concurrent CDP session limit. |
| `502` | The browser backend rejected the payload, returned an oversized result, or failed to start the browser. |
| `503` | Total capacity exceeded, or the browser backend is unavailable. |
| `504` | Session startup or queue timeout. |
| `500` | Unclassified internal error. |

<RequestExample>
  ```bash cURL theme={null}
  curl -sS -X POST "https://api.adscrawl.net/cdp/sessions" \
    -H "content-type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "idleTimeoutMs": 600000,
      "maxSessionMs": 3600000,
      "browserSettings": {
        "viewport": { "width": 1440, "height": 900 },
        "countryCode": "GLOBAL",
        "userAgentMode": "random",
        "userAgentOs": "windows"
      }
    }'
  ```

  ```json Body JSON theme={null}
  {
    "idleTimeoutMs": 600000,
    "maxSessionMs": 3600000,
    "browserSettings": {
      "viewport": { "width": 1440, "height": 900 },
      "countryCode": "GLOBAL",
      "userAgentMode": "random",
      "userAgentOs": "windows"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "sessionId": "6c3f7d14-7fe4-4c8e-9f1b-0b6d6f2fa2ef",
    "expiresAt": "2026-04-21T10:30:00.000Z",
    "cdpBaseUrl": "https://api.adscrawl.net/cdp/sessions/6c3f7d14-7fe4-4c8e-9f1b-0b6d6f2fa2ef?token=<data-token>"
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "error": "CDP sessions per API key limit reached"
  }
  ```
</ResponseExample>