Skip to main content
Every endpoint shares a common base URL, auth header, and response envelope. Always check status first, then read data (success) or error (failure).

​
Features

SmartScraper

Structured JSON from any URL.

Scrape

Raw HTML, cleaned markdown, or PDF, with optional stealth.

SmartBrowse

Replay clicks, typing, and pagination on real Chrome.

​
Base URL

All endpoints are served from a single base URL: 
https://api.webscrape.ai/v1

​
Authentication

Every request needs your API key in the X-API-Key header. Generate one from the dashboard — keys look like wsg_live_<32 base62 chars>. 
curl https://api.webscrape.ai/v1/scrape \
  -H "X-API-Key: wsg_live_..." \
  -H "Content-Type: application/json" \
  -d '{"website_url": "https://example.com"}'
See Authentication for rotation, revocation, and the full error table.

​
Response envelope

Every response has a top-level status field. Check it first, then read data (success or queued) or error (failure).

completed

Synchronous success. Read data, credits_used, credits_remaining.

queued

Async dispatch (SmartBrowse). Read data.run_id and poll.

error

Branch on error.code (stable). Log error.message, which can change.
{
  "status": "completed",
  "data": { "...": "..." },
  "credits_used": 5,
  "credits_remaining": 495,
  "request_id": "req_aB3xY9Kp"
}
Every response also returns the request_id as the X-Request-ID response header. Include it when you contact support.

​
Status codes

CodeWhenerror.code
200 OKSynchronous successn/a
202 AcceptedAsync dispatch (SmartBrowse)n/a
400 Bad RequestMalformed requestinvalid_request
401 UnauthorizedMissing or revoked API keyunauthorized
402 Payment RequiredOut of credits or unverified emailinsufficient_credits / email_verification_required
403 ForbiddenAuthenticated but not allowedforbidden
404 Not FoundResource doesn’t existnot_found
409 ConflictResource state disallows actionconflict / account_deletion_pending
422 Unprocessable EntitySchema validation failedvalidation_failed
429 Too Many RequestsRate limited. Back offrate_limited
500 / 502Internal failure. Safe to retryinternal_error / service_unavailable
See Errors for the full retry policy. Failed requests cost 0 credits.

​
Conventions

  • Headers: Content-Type: application/json on every request with a body. X-API-Key: wsg_live_... for auth.
  • Timestamps: ISO 8601 UTC, e.g. 2026-05-21T17:42:01Z.
  • IDs: SmartBrowse runs and recipes use opaque string IDs (~11 base62 chars, e.g. k7Xb9dRmQ2p). Treat them as opaque — don’t parse them, sort them, or assume a fixed length.
  • Async results: dispatch with POST, poll the matching GET, or subscribe via webhooks.
  • Stealth mode: a per-request flag ("stealth": true) on the endpoints that support it. See Stealth mode.

​
OpenAPI spec

The full spec lives at /openapi.yaml. Drop it into Postman, OpenAPI Generator, or anything else that speaks OpenAPI 3.1.