/v1/session — Stateful Browser Sessions

Create persistent browser sessions that maintain state across multiple requests. Navigate pages, interact with UI elements, take screenshots, and extract content — all within a single authenticated browser context.

Use Cases

• Login flows — Authenticate once, then scrape protected pages across the session
• Multi-step scraping — Navigate through pagination, search results, or wizard flows
• Form interaction — Fill and submit forms, then capture the result
• SPA navigation — Navigate within a single-page app while preserving JS state
• Visual debugging — Screenshot at each step to verify automation is on track

Create a Session

Start a new browser session at a given URL. Returns a session ID you'll use for all subsequent calls.

POST /v1/session

Request Body

{
  "url": "https://example.com"
}

curl Example

curl -X POST "https://api.webpeel.dev/v1/session" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

Response

{
  "id": "sess_abc123xyz",
  "url": "https://example.com",
  "status": "ready",
  "created": "2026-03-07T10:00:00Z"
}

Get Content

Retrieve the current page content as clean markdown (or another format).

GET /v1/session/:id

curl Example

curl "https://api.webpeel.dev/v1/session/sess_abc123xyz" \
  -H "Authorization: Bearer wp_live_xxxx"

Response

{
  "id": "sess_abc123xyz",
  "url": "https://example.com",
  "title": "Example Domain",
  "content": "# Example Domain\n\nThis domain is for use in illustrative examples...",
  "status": "ready"
}

Navigate

Navigate the session browser to a new URL, maintaining all cookies and session state.

POST /v1/session/:id/navigate

Request Body

{
  "url": "https://example.com/dashboard"
}

curl Example

curl -X POST "https://api.webpeel.dev/v1/session/sess_abc123xyz/navigate" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/dashboard" }'

Interact (Act)

Perform browser actions — click, type, scroll, wait — on the current page. Optionally take a screenshot after the actions complete.

POST /v1/session/:id/act

Request Body

{
  "actions": [
    { "type": "click", "selector": "#login-button" },
    { "type": "type", "selector": "#email", "value": "user@example.com" },
    { "type": "type", "selector": "#password", "value": "secret" },
    { "type": "click", "selector": "[type=submit]" },
    { "type": "wait", "ms": 2000 }
  ],
  "screenshot": true
}

Action Types

curl Example

curl -X POST "https://api.webpeel.dev/v1/session/sess_abc123xyz/act" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      { "type": "click", "selector": ".load-more" },
      { "type": "wait", "ms": 1500 }
    ],
    "screenshot": true
  }'

Response

{
  "id": "sess_abc123xyz",
  "url": "https://example.com/results",
  "actionsCompleted": 2,
  "screenshot": "data:image/png;base64,iVBORw0KGgo..."
}

Screenshot

Capture a screenshot of the current state of the session browser.

GET /v1/session/:id/screenshot

curl Example

curl "https://api.webpeel.dev/v1/session/sess_abc123xyz/screenshot" \
  -H "Authorization: Bearer wp_live_xxxx" \
  --output screenshot.png

Returns a PNG image directly (Content-Type: image/png).

Close Session

Terminate the session and free server-side resources. Sessions auto-expire after inactivity, but it's best practice to close them explicitly.

DELETE /v1/session/:id

curl Example

curl -X DELETE "https://api.webpeel.dev/v1/session/sess_abc123xyz" \
  -H "Authorization: Bearer wp_live_xxxx"

Full Example: Login Flow

A complete multi-step example: create a session, log in, navigate to a protected page, and extract content.

# 1. Create session
SESSION=$(curl -s -X POST "https://api.webpeel.dev/v1/session" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/login" }' \
  | jq -r '.id')

echo "Session: $SESSION"

# 2. Log in
curl -X POST "https://api.webpeel.dev/v1/session/$SESSION/act" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      { "type": "type", "selector": "#email", "value": "user@example.com" },
      { "type": "type", "selector": "#password", "value": "mypassword" },
      { "type": "click", "selector": "[type=submit]" },
      { "type": "wait", "ms": 3000 }
    ]
  }'

# 3. Navigate to protected content
curl -X POST "https://api.webpeel.dev/v1/session/$SESSION/navigate" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://app.example.com/reports" }'

# 4. Get the content
curl "https://api.webpeel.dev/v1/session/$SESSION" \
  -H "Authorization: Bearer wp_live_xxxx"

# 5. Close session
curl -X DELETE "https://api.webpeel.dev/v1/session/$SESSION" \
  -H "Authorization: Bearer wp_live_xxxx"

MCP Tool: webpeel_act

The webpeel_act MCP tool exposes browser session interaction directly to AI assistants like Claude and Cursor. When you configure the WebPeel MCP server, Claude can create sessions, navigate pages, and interact with UI elements on your behalf.

# Set up MCP (see MCP docs for full setup)
npx webpeel-mcp

See the MCP Server documentation for setup instructions.

Related

• /v1/ask — LLM-free web Q&A without needing a session
• Fetch API — Single-request page fetching with action support
• Screenshot API — Standalone screenshot capture
• MCP Server — Use webpeel_act directly inside Claude and Cursor
• Changelog — Sessions shipped in v0.19.0