Requirements
Before you start
Production API keys are not being issued yet. When account access opens, keys will use the shot_live_ or shot_test_ prefix and must be sent as bearer credentials.
Use the HTTPS base URL https://api-screenshot.com/v1. Never place an API key, cookie, authorization header, or other secret in a URL query string.
- Store the API key in a secret manager or server-side environment variable.
- Generate a stable Idempotency-Key for each logical screenshot request.
- Submit only public HTTP or HTTPS URLs without embedded credentials.
POST /v1/screenshots
1. Create the job
This example captures the full page after the load event, hides common overlays, and stores the result as WebP.
Request
bash
curl https://api-screenshot.com/v1/screenshots \
-H "Authorization: Bearer $SCREENSHOT_API_KEY" \
-H "Idempotency-Key: audit-example-com-001" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"preset": "desktop",
"full_page": true,
"format": "webp",
"quality": 82,
"wait_until": "load",
"block_ads": true,
"block_cookie_banners": true,
"block_chat_widgets": true
}'
HTTP 202 response
json
{
"data": {
"id": "shot_01KEXAMPLE",
"status": "queued",
"url": "https://example.com",
"format": "webp",
"attempt_count": 0,
"artifact": null,
"error": null,
"created_at": "2026-07-30T07:00:00Z"
}
}
GET /v1/screenshots/{id}
2. Observe the job
Poll with backoff until status is succeeded, failed, canceled, or deleted. Treat queued, claimed, rendering, uploading, and cancel_requested as non-terminal.
Status request
bash
curl https://api-screenshot.com/v1/screenshots/shot_01KEXAMPLE \
-H "Authorization: Bearer $SCREENSHOT_API_KEY"
Successful resource
json
{
"data": {
"id": "shot_01KEXAMPLE",
"status": "succeeded",
"final_url": "https://example.com/",
"width": 1440,
"height": 4820,
"format": "webp",
"duration_ms": 2310,
"artifact": {
"id": "artifact_01KEXAMPLE",
"mime_type": "image/webp",
"byte_count": 184220,
"sha256": "4cf7...64-hex-characters...",
"width": 1440,
"height": 4820,
"expires_at": "2026-07-31T07:00:00Z",
"download_url": "https://private-storage.example/...",
"download_expires_at": "2026-07-30T07:05:00Z"
},
"error": null
}
}
Private artifact
3. Download and verify
The download URL is short-lived and account-authorized. Fetch it promptly, verify the SHA-256 value when provenance matters, and do not persist the signed URL itself.
Node.js
javascript
const response = await fetch(downloadUrl);
if (!response.ok) throw new Error(`Download failed: ${response.status}`);
const screenshot = Buffer.from(await response.arrayBuffer());
// Store screenshot bytes and artifact.sha256 with the agent trace.
Safe retries
If the create request times out, repeat it with the same Idempotency-Key and identical JSON. A different body with the same key returns HTTP 409.
