The Pixel House

API Reference

Base URL: https://api.thepixelhouse.co.uk

All endpoints require authentication via API key (Bearer token) or session cookie. Responses follow { data: T } for success and { error: { code, message } } for errors.

Authentication

Include your API key in the Authorization header as a Bearer token. API keys are created in your dashboard under Settings. Keys are hashed before storage and shown only once at creation time. Keep your key secure and never commit it to version control.

Authorization: Bearer ak_your_api_key_here

Rate limiting

API requests are rate-limited per account based on your plan. When you exceed your limit, the API returns a 429 Too Many Requests status. Rate limit information is included in every response via headers:

  • X-RateLimit-Limit — maximum requests per window
  • X-RateLimit-Remaining — requests remaining in the current window
  • X-RateLimit-Reset — UTC epoch time when the window resets

Pagination

List endpoints return paginated results using cursor-based pagination. Pass the cursor query parameter to fetch the next page. The default page size is 25 items, configurable up to 100 via the limit parameter.

GET /v1/screenshots?limit=25&cursor=ss_abc123

The response includes a nextCursor field. When this field is null, you have reached the end of the list.

Error codes

Error responses include a machine-readable code and a human-readable message. Common error codes:

400validation_errorRequest body or query parameters failed validation
401unauthorizedMissing or invalid API key
403forbiddenAPI key does not have access to the requested resource
404not_foundThe requested resource does not exist
429rate_limitedToo many requests or monthly screenshot limit reached
500internal_errorAn unexpected error occurred on our side

Endpoints

All endpoints use the https://api.thepixelhouse.co.uk base URL. Timestamps are in ISO 8601 UTC format. All IDs are prefixed for type safety: ss_ (screenshot), bl_ (baseline), cmp_ (comparison), mon_ (monitor), prj_ (project).

POST/v1/screenshotsCapture a new screenshot
GET/v1/screenshotsList screenshots for a project
GET/v1/screenshots/:idGet screenshot metadata
GET/v1/screenshots/:id/imageGet screenshot image (PNG)
DELETE/v1/screenshots/:idDelete a screenshot
POST/v1/baselinesCreate or promote a baseline
GET/v1/baselinesList baselines for a project
GET/v1/baselines/:idGet baseline metadata
PUT/v1/baselines/:idUpdate baseline screenshot
DELETE/v1/baselines/:idDeactivate a baseline
POST/v1/comparisonsCompare two screenshots
GET/v1/comparisonsList comparisons for a project
GET/v1/comparisons/:idGet comparison result
GET/v1/comparisons/:id/diffGet diff overlay image (PNG)
POST/v1/comparisons/:id/approveApprove changes and update baseline
POST/v1/tests/runCapture and compare in one call
GET/v1/tests/:idGet test result
POST/v1/projectsCreate a project
GET/v1/projectsList projects
GET/v1/projects/:idGet project details
PUT/v1/projects/:idUpdate project settings
DELETE/v1/projects/:idDelete a project
POST/v1/monitorsCreate a scheduled monitor
GET/v1/monitorsList monitors
GET/v1/monitors/:idGet monitor details and recent runs
PUT/v1/monitors/:idUpdate monitor settings
DELETE/v1/monitors/:idDelete a monitor
POST/v1/monitors/:id/pausePause a monitor
POST/v1/monitors/:id/resumeResume a monitor
POST/v1/alertsCreate an alert rule
GET/v1/alertsList alert rules
PUT/v1/alerts/:idUpdate an alert rule
DELETE/v1/alerts/:idDelete an alert rule
POST/v1/api-keysCreate an API key
GET/v1/api-keysList API keys
DELETE/v1/api-keys/:idRevoke an API key
POST/v1/billing/checkoutCreate Stripe Checkout session
POST/v1/billing/portalCreate Stripe Customer Portal session