Docs
Create Snapshot
Create Snapshot
Kick off snapshot capture jobs for one or more URLs.
Endpoint
POST /api/v1/snapshots
Query Parameters
| Name | Type | Default | Description |
|---|---|---|---|
timeout | integer (ms) | 0 | Optional. Waits for up to the given duration before returning. When omitted the endpoint returns immediately with the initial snapshot status. |
Request Body
The body must satisfy the SnapshotRequestSchema from @watchero/types:
| Field | Type | Required | Notes |
|---|---|---|---|
urls | string[] | Yes | Absolute URLs to capture. Each URL creates an individual job. |
viewports | Viewport[] | Yes | Every viewport must include width and height. Optional flags like deviceScaleFactor, isMobile, isLandscape, and hasTouch mirror the schema defaults. |
credentials | { name: string; pass: string; } | No | Basic Auth credentials forwarded to the target site. |
metadata | Record<string, unknown> | No | Arbitrary metadata echoed back in job payloads, useful for correlating results. |
options | { fullPage?: boolean; format?: "png" | "jpeg" | "webp"; quality?: number } | No | Controls screenshot capture. Defaults to full-page PNG. Set fullPage to false for viewport-only shots, choose format to force png, jpeg, or webp, and supply quality (1-100) when using jpeg/webp to tune compression. |
Example Request
curl -s -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://site.com/"
],
"viewports": [
{
"width": 1496,
"height": 812,
"deviceScaleFactor": 2
}
]
}' \
"https://api.watchero.io/api/v1/snapshots"Example Response (202 Accepted while jobs are still running)
{
"id": "cmhdgfak60002mdtxnen6g2qi",
"status": "QUEUED",
"results": []
}When every job finishes before the timeout expires, the endpoint responds with HTTP 200 and a COMPLETE payload identical to the Get Snapshot response.
Errors with invalid schemas return HTTP 400 and include a details array from Zod. Server failures return HTTP 500 with an error message.