pixel-eagle Pixel Eagle

API Reference

This page documents the most commonly used endpoints. For the full API documentation, see the Swagger UI. All API endpoints require a project-scoped Bearer token, which you can create from your project settings (see Authentication). Pass it via the Authorization header.

Runs

POST/runs

Create a new run. Send a JSON body with metadata fields. 

curl https://pixel-eagle.com/runs \
  --json '{"gitref": "abc123", "branch": "main"}' \
  --oauth2-bearer $token

Set compare_with_golden to true to automatically compare each screenshot against the golden record as it is uploaded, so the comparison is ready as soon as the run finishes. 

curl https://pixel-eagle.com/runs \
  --json '{"compare_with_golden": true, "branch": "main"}' \
  --oauth2-bearer $token

POST/runs/:run_id

Upload a screenshot to a run. Use multipart form data with data (the image file) and screenshot (the name). 

curl https://pixel-eagle.com/runs/$run_id \
  -F 'data=@file.png' \
  -F 'screenshot=home-page' \
  --oauth2-bearer $token

POST/runs/:run_id/hashes

Send screenshot hashes before uploading. If the server already has the image, the upload can be skipped - saving bandwidth in CI pipelines where screenshots rarely change.

Golden Record

A golden record is a mutable, approved baseline of screenshots for a project (one per project). Runs are compared against it, and approved changes update the baseline.

POST/runs/:run_id/golden

Set a run as the project's golden record. Fails if one already exists. 

curl https://pixel-eagle.com/runs/$run_id/golden \
  -X POST --oauth2-bearer $token

POST/runs/:run_id/compare/golden

Compare a run against the golden record, triggering diff computation for changed screenshots. 

curl https://pixel-eagle.com/runs/$run_id/compare/golden \
  -X POST --oauth2-bearer $token

GET/runs/:run_id/compare/golden

Retrieve comparison results between a run and the golden record. Poll this endpoint until all screenshot comparisons are complete.

POST/runs/:run_id/golden/approve

Update the golden record by approving a run's changes. An empty body approves all changed and new screenshots. 

curl https://pixel-eagle.com/runs/$run_id/golden/approve \
  -X POST --oauth2-bearer $token

Optionally restrict to specific screenshots and/or remove ones missing from the run. 

curl https://pixel-eagle.com/runs/$run_id/golden/approve \
  --json '{"screenshots": ["home-page"], "remove_missing": true}' \
  --oauth2-bearer $token

Comparison

POST/runs/:run_id_a/compare/:run_id_b

Trigger a comparison between two runs. Screenshots are matched by name. 

curl https://pixel-eagle.com/runs/$run_id_a/compare/$run_id_b \
  -X POST --oauth2-bearer $token

GET/runs/:run_id_a/compare/:run_id_b

Retrieve comparison results. Poll this endpoint until all screenshot comparisons are complete.

POST/runs/:run_id/compare/auto

Automatically find a matching run to compare against based on metadata filters. See Comparison for details. 

curl https://pixel-eagle.com/runs/$run_id/compare/auto \
  --json '{"branch": "main"}' \
  --oauth2-bearer $token