canonical: https://jentic.com/apis/crossbrowsertesting.com/crossbrowsertesting-screenshot-comparisons

# Crossbrowsertesting.com Screenshot Comparisons API

The CrossBrowserTesting Screenshot Comparisons API exposes pixel-level layout-difference detection between captured browser screenshots, designed to plug visual-regression checks into automated test pipelines. Engineering teams use it to compare a target screenshot test against a baseline, a previous version, or a single browser, and surface a hosted Comparison UI link so reviewers can inspect highlighted differences. The three endpoints all return both a structured diff result and a UI link for human review.

## For AI agents

Compare CrossBrowserTesting screenshot test runs against a baseline or prior version to surface layout differences and a hosted review UI link.

## Scope

Does not handle test execution, browser session orchestration, or screenshot capture - use for comparing already-captured CrossBrowserTesting screenshots only.

## Capabilities

- Compare a full screenshot test run across browsers against a single baseline browser
- Compare two screenshot test versions to detect layout regressions between releases
- Compare a single browser screenshot against another single browser screenshot
- Retrieve a hosted Comparison UI link for visual review of detected differences
- Plug visual-regression checks into CI/CD pipelines via basic-auth REST calls

## Use cases

### Visual Regression in CI

Block a deploy when the rendered UI changes unexpectedly by comparing the current screenshot test version against the previous one in CI. The pipeline calls GET `/screenshots/{target_screenshot_test_id}/{target_version_id}/comparison/parallel/{base_version_id}` after each test run, parses the diff response, and fails the build if changes appear in protected pages. Reviewers open the returned Comparison UI link to inspect the highlighted regions.

Example prompt: Compare screenshot test version v42 against baseline version v41 and fail the build if any layout differences are detected

### Cross-Browser Layout Audit

Confirm that a page renders consistently across all supported browsers by comparing every browser's screenshot in a test against a single baseline browser. The team calls GET `/screenshots/{target_screenshot_test_id}/{target_version_id}/comparison/{base_result_id}` with the baseline result ID, then surfaces the diff metrics per browser. This is a faster check than human eyeballing for catching browser-specific layout bugs.

Example prompt: Compare every browser in screenshot test 88 against the Chrome 120 baseline result and report which browsers have layout deltas

### Single-Screenshot Targeted Comparison

Drill into a specific failing screenshot by comparing two individual results - useful when a regression is suspected on one browser/page combination and a full-test diff is overkill. The agent or developer hits `/screenshots/{target_screenshot_test_id}/{target_version_id}/{target_result_id}/comparison/{base_result_id}` and reviews the returned UI link.

Example prompt: Compare result 9001 in test 42 version v3 against baseline result 8999 to confirm the visual fix landed

### AI Agent Visual QA Reporting

An AI agent embedded in a release pipeline pulls visual-diff data from CrossBrowserTesting through Jentic and writes a release-ready summary. The agent searches for the crossbrowsertesting_compare_versions operation, executes against the customer's vaulted basic-auth credential, and renders a markdown report linking back to the Comparison UI for any browsers with detected differences.

Example prompt: Use the Jentic SDK to compare the latest screenshot test version against the previous one and produce a markdown summary of layout differences

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/screenshots/{target_screenshot_test_id}/{target_version_id}/comparison/parallel/{base_version_id}` | Compare two screenshot test versions |
| GET | `/screenshots/{target_screenshot_test_id}/{target_version_id}/comparison/{base_result_id}` | Compare a full screenshot test against a baseline result |
| GET | `/screenshots/{target_screenshot_test_id}/{target_version_id}/{target_result_id}/comparison/{base_result_id}` | Compare a single screenshot result against a baseline result |

## Key resources

- **Screenshot Comparisons** — Three GET endpoints under `/screenshots/{target_screenshot_test_id}/...` that compare versions, full tests against a baseline, or single results

## Why Jentic

- **Setup:** Wiring CrossBrowserTesting screenshot comparisons by hand means encoding its username and authkey for Basic auth and threading the test, version, and result ids through each comparison call. Through Jentic you install once, import CrossBrowserTesting from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The comparison endpoints are all read-only lookups that carry the screenshot test and version ids in the URL path, so scope the agent to the comparison operations it needs. It reads comparisons only and runs nothing you have not allowed.
- **Credential handling:** Your CrossBrowserTesting username and authkey are stored once, encrypted, by your own Jentic One instance and applied as the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'compare screenshot test versions', and Jentic returns the matching CrossBrowserTesting operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cronitor API** — Cronitor monitors the scheduled jobs that may run nightly visual regression tests
- **Cron-job.org API** — cron-job.org schedules the recurring HTTP calls that kick off a CrossBrowserTesting comparison check
- **crowd.dev API** — crowd.dev tracks community feedback that can flag visual regressions caught outside CrossBrowserTesting

## FAQ

### What authentication does the CrossBrowserTesting Screenshot Comparisons API use?

The API uses HTTP Basic Authentication - the username and authkey from your CrossBrowserTesting account are sent in the Authorization header. Through Jentic, both values are stored encrypted in the vault and injected at request time so they never enter the agent's context.

### Can I compare two specific screenshot test versions?

Yes. Call GET `/screenshots/{target_screenshot_test_id}/{target_version_id}/comparison/parallel/{base_version_id}` with the IDs of the target and base versions to get the structured diff and a Comparison UI link.

### How do I run a visual regression check through Jentic?

Search Jentic for 'compare screenshot test versions', load the operation schema, and execute with the test ID, target version, and base version. The Jentic SDK handles basic-auth header injection so the agent never holds the credentials.

### Does the API return a UI link or just diff data?

All three comparison endpoints return both structured diff data and a link to the hosted Comparison UI, so you can fail a build automatically and still hand reviewers a visual representation of the differences.

### How many endpoints does this API expose?

Three endpoints, all under `/screenshots/{target_screenshot_test_id}/...`, covering version-to-version, full-test-to-baseline, and single-result-to-single-result comparisons.

### Can I compare an individual screenshot result rather than a whole test?

Yes. GET `/screenshots/{target_screenshot_test_id}/{target_version_id}/{target_result_id}/comparison/{base_result_id}` compares a single target result against a single base result, which is useful for narrowly targeted regression confirmation.

### Can I limit what my agent is allowed to do with the CrossBrowserTesting Screenshot Comparisons API?

Yes. Because Jentic One is self-hosted, your own rules decide which operations and credentials the agent may use, so you can grant it only the comparison calls it needs. This API exposes three read-only lookups: comparing two screenshot test versions, comparing a full test against a baseline result, and comparing a single result against a base result. You can allow just one of these, and the agent reads comparison data only and runs nothing you have not permitted, since the stored username and authkey are applied at request time rather than exposed to the agent.