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
}
}
'import requests
url = "https://api.example.com/v1/sessions"
payload = {
"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
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
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}
})
};
fetch('https://api.example.com/v1/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/sessions"
payload := strings.NewReader("{\n \"proxy\": {\n \"type\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"sticky\": true\n },\n \"stealth\": \"<string>\",\n \"fingerprint\": {\n \"platform\": \"<string>\",\n \"userAgent\": \"<string>\",\n \"locale\": \"<string>\",\n \"timezone\": \"<string>\",\n \"viewport\": {}\n },\n \"profileId\": \"<string>\",\n \"timeout\": 123,\n \"recording\": {\n \"har\": true,\n \"screenshots\": true,\n \"video\": true\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/sessions")
.header("Content-Type", "application/json")
.body("{\n \"proxy\": {\n \"type\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"sticky\": true\n },\n \"stealth\": \"<string>\",\n \"fingerprint\": {\n \"platform\": \"<string>\",\n \"userAgent\": \"<string>\",\n \"locale\": \"<string>\",\n \"timezone\": \"<string>\",\n \"viewport\": {}\n },\n \"profileId\": \"<string>\",\n \"timeout\": 123,\n \"recording\": {\n \"har\": true,\n \"screenshots\": true,\n \"video\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"proxy\": {\n \"type\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"sticky\": true\n },\n \"stealth\": \"<string>\",\n \"fingerprint\": {\n \"platform\": \"<string>\",\n \"userAgent\": \"<string>\",\n \"locale\": \"<string>\",\n \"timezone\": \"<string>\",\n \"viewport\": {}\n },\n \"profileId\": \"<string>\",\n \"timeout\": 123,\n \"recording\": {\n \"har\": true,\n \"screenshots\": true,\n \"video\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "<string>",
"cdpUrl": "<string>",
"proxy": {},
"fingerprint": {},
"expiresAt": "<string>"
}API Reference
Create Session
Launch a new stealth browser session
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
}
}
'import requests
url = "https://api.example.com/v1/sessions"
payload = {
"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
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
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}
})
};
fetch('https://api.example.com/v1/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/sessions"
payload := strings.NewReader("{\n \"proxy\": {\n \"type\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"sticky\": true\n },\n \"stealth\": \"<string>\",\n \"fingerprint\": {\n \"platform\": \"<string>\",\n \"userAgent\": \"<string>\",\n \"locale\": \"<string>\",\n \"timezone\": \"<string>\",\n \"viewport\": {}\n },\n \"profileId\": \"<string>\",\n \"timeout\": 123,\n \"recording\": {\n \"har\": true,\n \"screenshots\": true,\n \"video\": true\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/sessions")
.header("Content-Type", "application/json")
.body("{\n \"proxy\": {\n \"type\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"sticky\": true\n },\n \"stealth\": \"<string>\",\n \"fingerprint\": {\n \"platform\": \"<string>\",\n \"userAgent\": \"<string>\",\n \"locale\": \"<string>\",\n \"timezone\": \"<string>\",\n \"viewport\": {}\n },\n \"profileId\": \"<string>\",\n \"timeout\": 123,\n \"recording\": {\n \"har\": true,\n \"screenshots\": true,\n \"video\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"proxy\": {\n \"type\": \"<string>\",\n \"country\": \"<string>\",\n \"region\": \"<string>\",\n \"city\": \"<string>\",\n \"sticky\": true\n },\n \"stealth\": \"<string>\",\n \"fingerprint\": {\n \"platform\": \"<string>\",\n \"userAgent\": \"<string>\",\n \"locale\": \"<string>\",\n \"timezone\": \"<string>\",\n \"viewport\": {}\n },\n \"profileId\": \"<string>\",\n \"timeout\": 123,\n \"recording\": {\n \"har\": true,\n \"screenshots\": true,\n \"video\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "<string>",
"cdpUrl": "<string>",
"proxy": {},
"fingerprint": {},
"expiresAt": "<string>"
}Create Session
Launch a new isolated browser session with stealth configuration, proxy, and fingerprint.object
Proxy configuration for the session.
Show properties
Show properties
string
required
Proxy type. One of:
residential, datacenter, isp, mobile.string
ISO 3166-1 alpha-2 country code (e.g.,
US, GB, DE).string
Geographic region:
us, eu, asia, latam.string
City name (e.g.,
New York, London). Requires country.boolean
default:"false"
Use the same IP for the session duration.
string
default:"max"
Anti-detection level. One of:
none, basic, max (alias: full).string | object
default:"auto"
Set to
auto for automatic fingerprint generation, or provide a custom config.string
Load a saved profile (cookies, localStorage, fingerprint preferences).
integer
default:"1800"
Maximum session duration in seconds. Max: 3600 (1 hour).
object
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
string
Unique session identifier.
string
Session status:
launching, ready, active, idle, destroyed, failed.string
CDP WebSocket URL for connecting Playwright/Puppeteer.
object
Assigned proxy details (IP, country, type).
object
Generated fingerprint details.
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"
}
}
⌘I