Create Snapshot

Docs

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`	`object`	No	Basic Auth credentials forwarded to the target site. See Credentials for details and examples.
`metadata`	`Record<string, unknown>`	No	Arbitrary metadata echoed back in job payloads. See Metadata for usage patterns.
`options`	`SnapshotOptions`	No	Controls output capture and content filtering. See below for details.

Snapshot Options

Field	Type	Default	Notes
`format`	`"png" \| "jpeg" \| "webp" \| "pdf"`	`"png"`	Output format. Use `pdf` for PDF document generation.
`darkMode`	`boolean`	`false`	Enable dark color scheme for the page.
`imageOptions`	`ImageOptions`	—	Options specific to image output (png/jpeg/webp). See Image Options.
`pdfOptions`	`PdfOptions`	—	Options specific to PDF output. See PDF Options.
`block`	`BlockOptions`	—	Content blocking options. See Block Options.

Example Request

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/"
    ],
    "viewports": [
      {
        "width": 1280,
        "height": 800
      }
    ],
    "options": {
      "format": "jpeg",
      "block": {
        "cookieBanners": true,
        "chats": true,
        "ads": true,
        "trackers": true
      }
    }
  }' \
  "https://api.watchero.io/api/v1/snapshots"

See Image Options and PDF Options for format-specific examples.

Response

`202 Accepted` (Jobs still running)

When jobs are still processing or the timeout expires before completion:

{
  "id": "cmhdgfak60002mdtxnen6g2qi",
  "status": "QUEUED",
  "results": []
}

`200 OK` (Complete)

When every job finishes before the timeout expires, the endpoint responds with a COMPLETE payload identical to the Get Snapshot response.

Error Responses

Status	Description
`400 Bad Request`	Invalid schema. Includes a `details` array from Zod validation.
`500 Internal Server Error`	Server failure with an `error` message.