Automation API

Drive a real browser programmatically: login flows, form filling, data extraction after JavaScript, screenshots — with persistent sessions.

POST /v1/automate

Execute a sequence of browser automation steps. Sessions persist across calls, so you can log in once and keep working.

Request body (AutomateRequest):

Field	Type	Default	Description
session_id	string	—	Reuse an existing browser session
steps	array<AutomateStep>	—	Required. Ordered list of steps
headless	boolean	true	Run headless
viewport	object	—	Viewport override {width, height}

Step schema (AutomateStep):

Field	Type	Default	Description
action	string	—	Required. Step action (see below)
selector	string	—	CSS selector for the target element
value	string	—	Value to type/set
url	string	—	URL for navigate
timeout	integer	30000	Step timeout (ms)
wait_until	string	networkidle	Wait condition

Actions include navigate, click, type, extract, and more (wait, screenshot, scroll, submit, …).

Example — login flow:

curl -X POST http://localhost:8005/v1/automate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{
    "steps": [
      {"action": "navigate", "url": "https://login.example.com"},
      {"action": "type", "selector": "#username", "value": "user"},
      {"action": "type", "selector": "#password", "value": "pass"},
      {"action": "click", "selector": "#login-btn"},
      {"action": "extract", "selectors": {"title": "h1"}}
    ]
  }'

Response (200): the extracted data from the final step, e.g. { "title": "Welcome, user" }.

Sessions

Sessions let you keep cookies, storage, and login state between requests.

Endpoint	Purpose
POST /v1/session/create	Create a persistent browser session (?persist=true to persist to disk)
GET /v1/sessions	List all persisted sessions
POST /v1/session/save	Save current session state (cookies, storage) to disk
POST /v1/session/restore	Restore a saved session into a browser context
POST /v1/session/destroy	Destroy a session (save_state optionally saves first)

Example — create and reuse:

# Create
curl -X POST "http://localhost:8005/v1/session/create?persist=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{}'

# → { "session_id": "sess_abc123" }

# Reuse in automation
curl -X POST http://localhost:8005/v1/automate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{
    "session_id": "sess_abc123",
    "steps": [{"action": "navigate", "url": "https://example.com"}]
  }'

Saved sessions are stored in the sessions volume (/app/sessions in Docker, ~/.pry/sessions on bare metal) and survive restarts.

Screenshots

Endpoint	Purpose
POST /v1/screenshot	Take a screenshot of a URL
POST /v1/ss	CLI alias (pry ss <url> -o shot.png)

Example:

curl -X POST http://localhost:8005/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"url": "https://example.com", "fullPage": true}'

TLS impersonation

The anti-detection stack includes TLS fingerprint randomization (tls_fingerprint.py) — per-request unique TLS fingerprints so the transport layer doesn't give the bot away. Combined with the stealth engine and browser pool, this makes the browser look like a genuine client at the network level.

Camoufox (Firefox anti-detection)

For the highest-fidelity stealth, Pry integrates Camoufox — a patched Firefox build that evades fingerprinting more effectively than Playwright/Puppeteer. It's a drop-in Playwright alternative focused on stealth:

• Patches Firefox at the source level to bypass fingerprinting
• Ships multiple default configurations (e.g. chrome_windows) for a convincing browser profile
• Falls back gracefully when camoufox is not installed

Camoufox is part of the BSL-licensed stealth module — free for non-production use (see Pricing & Monetization).

Anti-detection in automation

Automated browsers automatically inherit the stealth stack:

• 6 injected stealth scripts (webdriver hiding, canvas/WebGL/audio noise, human mouse/typing behavior)
• Cookie warming and behavioral biometrics for session realism
• Random human-like delays between steps (PRY_MIN_DELAY_MS / PRY_MAX_DELAY_MS)

See Stealth & Anti-detection for the full picture.

Other automation endpoints

Endpoint	Purpose
POST /v1/record/start	Action recorder — record real browser actions
POST /v1/auth/captcha	CAPTCHA solving (6 providers with auto-fallback)
POST /v1/auth/credentials	Encrypted credential vault
POST /v1/auth/sso	SSO login script generation
POST /v1/auth/session/health	Session health check
GET /v1/cookies/sessions	List cookie sessions

Next steps

• Stealth & Anti-detection — how browsers stay undetected
• Extraction API — structured data from scraped content