Watchero exposes a REST API that lets you capture visual snapshots, compare builds, and extract key URLs from a sitemap. All endpoints live under the same authentication model and share a few common headers and behaviors described on this page.

Base URL

All endpoints are available under https://api.watchero.io/api/v1.

Authentication

Every request must include an API key issued from your Watchero account. Provide it in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.watchero.io/api/v1/snapshots

Requests that omit the header or use an unknown key return 401 Unauthorized.

Required Headers

• Authorization: Bearer <api_key>
• Content-Type: application/json for requests that send JSON payloads

Snapshot Status Lifecycle

Snapshot jobs progress through three states:

• QUEUED – the request has been accepted and queued for processing.
• COMPLETE – all jobs finished successfully and include screenshots.
• ERROR – at least one job failed; the response body contains error details per job or URL.

Endpoints that create or poll snapshots return HTTP 202 while any job is still queued and HTTP 200 once processing completes.

Handling Timeouts

Long-running operations support a timeout query parameter (milliseconds) that instructs the API to wait for up to the specified duration before returning the latest known status. When the timeout elapses, the current snapshot state is returned even if jobs are still running.

Error Format

Validation problems return HTTP 400 with an error message and a details array describing schema issues. Server-side faults respond with HTTP 500 and an error message.

With these basics in place, explore the endpoint-specific documentation in the sidebar for concrete examples and response payloads.