Skip to main content
POST
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/v1/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "proxy": {
    "type": "<string>",
    "country": "<string>",
    "region": "<string>",
    "city": "<string>",
    "sticky": true
  },
  "stealth": "<string>",
  "fingerprint": {
    "platform": "<string>",
    "userAgent": "<string>",
    "locale": "<string>",
    "timezone": "<string>",
    "viewport": {}
  },
  "profileId": "<string>",
  "timeout": 123,
  "recording": {
    "har": true,
    "screenshots": true,
    "video": true
  }
}
'
{
  "id": "<string>",
  "status": "<string>",
  "cdpUrl": "<string>",
  "proxy": {},
  "fingerprint": {},
  "expiresAt": "<string>"
}

​
Create Session

Launch a new isolated browser session with stealth configuration, proxy, and fingerprint.
​
proxy
object
Proxy configuration for the session.
​
stealth
string
default:"max"
Anti-detection level. One of: none, standard, max.
​
fingerprint
string | object
default:"auto"
Set to auto for automatic fingerprint generation, or provide a custom config.
​
profileId
string
Load a saved profile (cookies, localStorage, fingerprint preferences).
​
timeout
integer
default:"1800"
Maximum session duration in seconds. Max: 3600 (1 hour).
​
recording
object
Session recording options.

​
Request

curl -X POST https://api.meshbrow.dev/v1/sessions \
  -H "Authorization: Bearer mb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "proxy": {
      "type": "residential",
      "country": "US"
    },
    "stealth": "max",
    "fingerprint": "auto",
    "timeout": 1800
  }'

​
Response

​
id
string
Unique session identifier.
​
status
string
Session status: launching, ready, active, idle, destroyed, failed.
​
cdpUrl
string
CDP WebSocket URL for connecting Playwright/Puppeteer.
​
proxy
object
Assigned proxy details (IP, country, type).
​
fingerprint
object
Generated fingerprint details.
​
expiresAt
string
ISO 8601 timestamp when session will auto-destroy.
201
{
  "id": "ses_k8m2n4p6",
  "status": "ready",
  "cdpUrl": "wss://api.meshbrow.dev/cdp/ses_k8m2n4p6?token=ct_abc123",
  "proxy": {
    "type": "residential",
    "country": "US",
    "city": "Dallas",
    "ip": "104.xxx.xxx.xxx"
  },
  "fingerprint": {
    "platform": "Win32",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
    "locale": "en-US",
    "timezone": "America/Chicago"
  },
  "expiresAt": "2026-10-27T14:30:00Z"
}
400
{
  "error": {
    "code": "invalid_request",
    "message": "proxy.type must be one of: residential, datacenter, isp, mobile"
  }
}
402
{
  "error": {
    "code": "quota_exceeded",
    "message": "quota exceeded for account acct_123 (plan free): 100/100 sessions used"
  }
}
403
{
  "error": {
    "code": "proxy_access_denied",
    "message": "proxy type \"residential\" not available on plan free for account acct_123"
  }
}
429
{
  "error": {
    "code": "concurrency_limit_reached",
    "message": "concurrent session limit reached for plan free: 2 active, 1 requested, limit 2"
  }
}