Webcap API Documentation

Capture high-quality screenshots of any website with a simple, reliable API. Built-in queueing, retries, and webhooks.

🚀 Fast & Reliable

Average response time under 3s

🎛️ Customizable

20+ parameters to control output

📱 Device-true

Mobile & desktop profiles

Base URL

https://api.getwebcap.com

Authentication

Webcap uses API keys. Include your key in the request headers.

Keep your API key secret—never expose it in client-side code.

Header Authentication

Authorization: Bearer YOUR_API_KEY
# or
x-authorization: YOUR_API_KEY

Screenshot API

Capture any public page with sensible defaults and fine-grained control.

POST /screenshot

Request Parameters

Required

Parameter	Type	Description
`url` REQUIRED	string	Valid HTTP(S) URL to capture

Content Blocking

block_ads

Block ads (boolean)

block_resources

Block unnecessary resources

block_cookie_banners

Hide cookie banners

block_chat_widgets

Hide chat widgets

Device & Viewport

device

"desktop" | "mobile" (default: desktop)

window_width

200–10000 (default 1920)

window_height

200–10000 (default 1080)

full_page

Capture full page height

Timing & Waiting

timeout

1000–140000 (default 140000)

wait

Extra delay ms

wait_browser

"domcontentloaded" | "load" | "networkidle0"

wait_for

CSS selector to wait for

Image Options

image_type

"png" | "jpeg" (default png)

image_quality

1–100 (jpeg only)

screenshot_selector

Capture a specific element

clip

{x,y,width,height}

Advanced Options

js_code

Run JS before snapshot

cookies

Set cookies

forward_headers

Forward request headers

forward_headers_pure

Forward headers without modification

Response

{
  "url": "https://wikipedia.org",
  "image_url": "https://cdn.getwebcap.com/screenshots/abc123.png",
  "expires_at": "2024-01-15T12:00:00.000Z",
  "error_message": "",
  "total_time": 2341
}

Field	Type	Description
`url`	string	Captured URL
`image_url`	string	Direct link to image
`expires_at`	string	Deletion timestamp (24h)
`error_message`	string	Error if failed
`total_time`	number	Processing time (ms)

Account API

Retrieve credit balance and subscription details.

GET /account

Response

{
  "email": "user@example.com",
  "credits": 142,
  "next_billing_date": "2024-02-01T00:00:00.000Z",
  "plan": "builder"
}

Field	Type	Description
`email`	string	Account email
`credits`	number	Remaining credits
`next_billing_date`	string	Next renewal
`plan`	string	Plan name

Error Handling

Standard HTTP codes indicate request success or failure.

HTTP Status Codes

Code	Description
`200`	Success (check `success` field)
`401`	Unauthorized – invalid/missing key
`422`	Validation error
`400`	Bad request

Error Response Formats

Validation Error (422)

{
  "error": "Validation failed",
  "details": [{ "type": "field","msg": "url must be a valid http(s) URL","path": "url","location": "body"}]
}

Screenshot Error (200 with success: false)

{
  "success": false,
  "error": "Timeout: Page did not load within 140 seconds"
}

Authentication Error (401)

{}

Code Examples

Pick your language and endpoint.

// Node.js (fetch API)
import fetch from "node-fetch";

const url = "https://api.getwebcap.com/screenshot";
const res = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ url: "https://wikipedia.org", window_width:1920, window_height:1080, full_page:true, device:"desktop", block_ads:true, image_type:"png" })
});

if (!res.ok) throw new Error(await res.text());
const data = await res.json();
console.log("Screenshot URL:", data.image_url);

# Python (requests)
import requests
r = requests.post("https://api.getwebcap.com/screenshot",
  json={"url":"https://wikipedia.org","window_width":1920,"window_height":1080,"full_page":True,"device":"desktop","block_ads":True,"image_type":"png"},
  headers={"Content-Type":"application/json","Authorization":"Bearer YOUR_API_KEY"})
r.raise_for_status()
print(r.json())

"https://wikipedia.org","window_width"=>1920,"window_height"=>1080,"full_page"=>true,"device"=>"desktop","block_ads"=>true,"image_type"=>"png"]);
curl_setopt_array($curl,[CURLOPT_URL=>"https://api.getwebcap.com/screenshot",CURLOPT_RETURNTRANSFER=>true,CURLOPT_CUSTOMREQUEST=>"POST",CURLOPT_POSTFIELDS=>$payload,CURLOPT_HTTPHEADER=>["Content-Type: application/json","Authorization: Bearer YOUR_API_KEY"]]);
$response = curl_exec($curl); if ($response===false) { throw new Exception(curl_error($curl)); }
curl_close($curl); echo $response;

curl -X POST "https://api.getwebcap.com/screenshot" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"url":"https://wikipedia.org","window_width":1920,"window_height":1080,"full_page":true,"device":"desktop","block_ads":true,"image_type":"png"}'

import fetch from "node-fetch";
const res = await fetch("https://api.getwebcap.com/account",{headers:{Authorization:"Bearer YOUR_API_KEY"}});
if(!res.ok) throw new Error(await res.text());
console.log(await res.json());

import requests
r = requests.get("https://api.getwebcap.com/account", headers={"Authorization":"Bearer YOUR_API_KEY"})
r.raise_for_status(); print(r.json())

"https://api.getwebcap.com/account",CURLOPT_RETURNTRANSFER=>true,CURLOPT_HTTPHEADER=>["Authorization: Bearer YOUR_API_KEY"]]);
echo curl_exec($ch); curl_close($ch);

Remember: replace YOUR_API_KEY with the key from your dashboard.

Rate Limits

Limits are enforced per minute by plan.

10

requests / min

Free

50

requests / min

Sandbox

100

requests / min

Builder

100

requests / min

On-demand

Response Headers

Header	Description
`CREDITS`	Remaining credits