Screenshot API v1

Parameters, constraints, and examples for POST /api/v1/screenshots.

Authentication

Send your API key in the Authorization header:

Authorization: Bearer <api_key>

Create screenshot

Endpoint: POST /api/v1/screenshots

Body: JSON

Minimal request

curl -X POST "https://api.your-domain.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Sync request (when allowed)

curl -X POST "https://api.your-domain.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "sync",
    "timeoutMs": 8000,
    "fullPage": false
  }'

Key parameters

url

Required. Target URL to capture.

mode

Optional. async (default) or sync.

timeoutMs

Required for sync. Must be > 0 and < 10000.

fullPage

Optional. For sync mode, it must be false.

Sync mode constraints

Even if you request mode=sync, the server will fall back to async unless:

timeoutMs is provided AND 0 < timeoutMs < 10000 AND fullPage == false

Parameters reference (full)

Field	Type	Required	Default	Notes
url	string	Yes	-	Target URL.
mode	string	No	async	Accepts async or sync (case-insensitive).
timeoutMs	int?	No	-	Only used for sync. Must be 0 < timeoutMs < 10000.
fullPage	bool	No	false	Sync requires false.
viewport	object?	No	-	Viewport override.
format	string?	No	-	Suggested: png, jpeg, webp.
quality	int?	No	-	Suggested: 1-100. Only meaningful for jpeg/webp.
waitUntil	string?	No	-	Suggested: load, domcontentloaded, networkidle.
delayMs	int?	No	-	Extra delay after waitUntil.
selector	string?	No	-	Capture only a specific element.
headers	object?	No	-	Dictionary of extra request headers.
cookies	array?	No	-	Cookie injection list.
javascript	string?	No	-	Custom JS to inject (implementation-dependent).
css	string?	No	-	Custom CSS to inject (implementation-dependent).
device	string?	No	-	Suggested: desktop/iphone/ipad/pixel.
strictDevice	bool?	No	-	If true, unsupported device should fail (implementation-dependent).
colorScheme	string?	No	-	Suggested: light/dark/no-preference.
proxy	string?	No	-	Proxy string (implementation-dependent).
trace	bool?	No	-	Enable trace (implementation-dependent).
har	bool?	No	-	Enable HAR (implementation-dependent).
returnDom	bool?	No	-	Return DOM (implementation-dependent).
returnNetwork	bool?	No	-	Return network info (implementation-dependent).
priority	int?	No	-	Job priority (implementation-dependent).

viewport

Field	Type	Required	Notes
viewport.width	int	No	Viewport width.
viewport.height	int	No	Viewport height.

cookies[]

Field	Type	Required	Notes
cookies[].name	string	Yes	Cookie name.
cookies[].value	string	Yes	Cookie value.
cookies[].domain	string?	No	Cookie domain.
cookies[].path	string?	No	Cookie path.

Responses

Async (default)

{ "jobId": "<guid>", "status": "pending" }

Sync (completed)

{ "jobId": "<guid>", "status": "completed", "result": { "url": "https://..." } }

Sync (failed)

{ "jobId": "<guid>", "status": "failed", "errorMessage": "..." }

Sync (timeout)

{ "jobId": "<guid>", "status": "processing" }

Errors

HTTP	When	Body
400	Missing/empty url	Empty body (BadRequest)
401	Invalid/missing API key	Middleware response
402	Quota exceeded	{ "error": "quota_exceeded", "operationKey": "screenshot.capture", ... }
429	Rate limited	{ "error": "rate_limited", "operationKey": "screenshot.capture", ... }
404	Job not found	NotFound

How-to examples

Practical examples for common integration needs.

Pass target-site auth token (via headers)

If the page you want to capture is protected (Bearer/JWT/session token), forward it using headers:

{
  "url": "https://example.com/dashboard",
  "headers": {
    "Authorization": "Bearer <target_site_token>"
  }
}

Set cookies (session-based login)

If the website uses cookies for authentication, pass them using cookies:

{
  "url": "https://example.com/account",
  "cookies": [
    { "name": "session", "value": "<cookie_value>", "domain": "example.com", "path": "/" }
  ]
}

Custom request headers (User-Agent / locale)

{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept-Language": "en-US,en;q=0.9"
  }
}

Viewport + format + quality

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "format": "jpeg",
  "quality": 85
}

Wait for page load + add delay

{
  "url": "https://example.com",
  "waitUntil": "networkidle",
  "delayMs": 500
}

Capture a specific element (selector)

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

Get status

Poll the job:

GET /api/v1/screenshots/{jobId}