Skip to main content
POST
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/v1/sessions

Documentation Index

Fetch the complete documentation index at: https://docs.reader.dev/llms.txt

Use this file to discover all available pages before exploring further.

Create a stealthed browser session. Returns a WebSocket URL for Playwright/Puppeteer connection.

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key
Content-TypeYesapplication/json

​
Body

FieldTypeDefaultDescription
maxDurationMsnumber3600000Maximum session lifetime in ms (60s - 60min)
{
  "maxDurationMs": 600000
}

​
Response

​
201 Created

{
  "success": true,
  "data": {
    "sessionId": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "wsEndpoint": "wss://api.reader.dev/v1/sessions/ses_a1b2.../cdp?token=abc123...",
    "token": "abc123def456...",
    "status": "active",
    "createdAt": "2026-04-30T12:00:00.000Z",
    "expiresAt": "2026-04-30T13:00:00.000Z"
  }
}

​
Fields

FieldDescription
sessionIdUnique session identifier
wsEndpointCDP WebSocket URL - pass to chromium.connectOverCDP()
tokenAuth token embedded in wsEndpoint (for WebSocket proxy)
statusAlways "active" on creation
createdAtISO 8601 timestamp
expiresAtWhen the session will auto-close

​
Usage

​
Playwright

const session = await reader.sessions.create();
const browser = await chromium.connectOverCDP(session.wsEndpoint);

​
Puppeteer

const session = await reader.sessions.create();
const browser = await connect({ browserWSEndpoint: session.wsEndpoint });

​
Errors

CodeStatusDescription
insufficient_credits402Not enough credits (sessions cost 1 credit/min)
rate_limited429Too many requests
upstream_unavailable502Browser engine unavailable

​
Credits

Sessions charge 1 credit per minute, starting immediately on creation. Credits are deducted in real-time. If credits run out, the session is automatically stopped.