API Reference

Create report

POST /api/reports/:sha

Uploads a list of snapshots for a certain identifier (usually a commit sha). If there is an existing report for the same sha, it will be overwritten as a result of calling this endpoint, unless you're posting partial reports.

URL params

• :sha String

  The id of the report.

Body params

• snaps Array<Snapshot>

  A list of snapshot objects associated with the report

• project optional String

  The identifying name of the project this report should belong to. If none is specified, the default project will be used.

• link optional String

  URL to the source of the report (e.g. PR URL).

• message optional String

  A short string describing the source of the report (e.g. PR title).

• partial optional Boolean

  Set this to true to amend the report instead of overwriting it. This is useful if you are running multiple processes for the same sha. Remember to call the Complete Report endpoint once you are done uploading all the partials, otherwise the report will never be fully constructed and useful.

Response

• json ReportStatus

  An object containing a url where the uploaded report can be accessed

Error responses

• 400

  The snapshot data is invalid (e.g. missing required fields), or the report has been archived and can no longer be modified.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Get report

GET /api/reports/:sha

Gets a list of snapshots for a certain identifier (usually a commit sha).

URL params

• :sha String

  The id of the report.

Query params

• project optional String

  The identifying name of the project this report belongs to. If none is specified, the default project will be assumed.

Response

• json Array<Snapshot>

  A list of snapshots associated with this sha.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No report found for the given sha and project.

Get report status

GET /api/reports/:sha/status

Gets some metadata about a report.

To fetch status for multiple projects in one request, pass a comma-separated list of project names in the projects query parameter:

GET /api/reports/abc123/status?projects=web,mobile,ios

The response is an array with one entry per project, in the same order as the input. If no report exists for a given project the entry will contain an error field instead of the usual status fields:

[
  {
    "project": "web",
    "url": "https://happo.io/a/1/p/2/report/abc123",
    "snapshotCount": 42,
    "completedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:00:00.000Z"
  },
  {
    "project": "mobile",
    "error": "report not found"
  },
  {
    "project": "ios",
    "url": "https://happo.io/a/1/p/4/report/abc123",
    "snapshotCount": 18,
    "completedAt": "2024-01-15T10:45:00.000Z",
    "createdAt": "2024-01-15T10:05:00.000Z"
  }
]

URL params

• :sha String

  The id of the report.

Query params

• project optional String

  The identifying name of the project this report belongs to. If none is specified, the default project will be assumed. Cannot be combined with "projects".

• projects optional String

  Comma-separated list of project names to fetch status for (e.g. "web,mobile,ios"). When provided, the response will be an array of ReportStatus objects, each including a "project" field. If no report exists for a project, that item will include an "error" field instead. Cannot be combined with "project".

Response

• json ReportStatus | Array<ReportStatus>

  A ReportStatus object, or an array of ReportStatus objects when "projects" is used. Each array item includes a "project" field identifying the project, and an "error" field if no report was found for that project.

Error responses

• 400

  Both project and projects were specified (they are mutually exclusive), or projects is not a valid comma-separated string.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No report found for the given sha and project. Only returned when using the project parameter — when using projects, missing reports appear as { project, error } items in the 200 response array instead.

Complete a report

POST /api/reports/:sha/complete

When you're uploading partial reports (via the Create Report endpoint), you need to use this endpoint to signal that all the partials have been added and that the report is complete.

URL params

• :sha String

  The id of the report.

Body params

• project optional String

  The identifying name of the project the reports belong to. If none is specified, the default project will be assumed. Cannot be combined with "projects".

• projects optional Array<String>

  An array of project names to complete in a single request. When provided, the response will be an array of ReportStatus objects, each including a "project" field. Cannot be combined with "project".

Response

• json ReportStatus | Array<ReportStatus>

  A ReportStatus object, or an array of ReportStatus objects when "projects" is used. Each array item includes a "project" field identifying the project, and an "error" field if completion failed for that project.

Error responses

• 400

  Both project and projects were specified (they are mutually exclusive), or projects is not an array.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No partial report found to complete. Only returned when using the project parameter — when using projects, failures appear as { project, error } items in the 200 response array instead.

Clone report

POST /api/reports/:fromSha/clone/:toSha

Clones a report from one identifier/sha to another. This is useful if you know a commit doesn't introduce any visual changes but you still want it to be associated with a report. An example use-case of this would be if you have some logic to skip a Happo run if a PR has already run Happo on a commit, and a subsequent commit does not touch any UI code. You can then clone the existing report (from the previous commit) to the new commit. After that you can run a comparison with the cloned report set as the "after" report to trigger a Happo build status on the PR.

Cloning a report does not affect your snapshot usage.

URL params

• :fromSha String

  The id of the report to clone from

• :toSha String

  The id of the report to clone to

Body params

• project optional String

  The identifying name of the project for which the clone should be created. If none is specified, the default project will be used.

• link optional String

  URL to the source of the report (e.g. PR URL). If omitted, the link from the source/from report will be used

• message optional String

  A short string describing the source of the report (e.g. PR title). If omitted, the link from the source/from report will be used.

Response

• json ReportStatus

  An object containing a url where the uploaded report can be accessed

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  The source report (fromSha) does not exist for the given project.

Skip report

POST /api/skip/:sha

Tells Happo to skip running for a certain commit SHA. This is useful if you have Happo configured as a required check for your PRs but want to avoid running Happo tests (e.g. because no UI code changed). The given SHA must be present in your origin repo (e.g. on GitHub) before calling this endpoint. Calling this endpoint will post a successful build status to the PR/commit.

If the skip is successful, this endpoint will return a 204 status code, or with ifNotStarted, a 200 with { "posted": true }, or { "posted": false, "reason": "…" } when a run had already started. If the SHA is not present in the origin repo, the call will fail with a 404 error.

Without ifNotStarted, a project that already has a Happo run on the commit is taken out of that run.

Example, in the CI step that decides not to run Happo:

curl --fail-with-body --silent --show-error \
  -u "$HAPPO_API_KEY:$HAPPO_API_SECRET" \
  --json '{"project": "components", "group": true, "ifNotStarted": true}' \
  "https://happo.io/api/skip/$HEAD_SHA"

URL params

• :sha String

  The SHA of the commit to skip. This must be the full SHA, not a partial SHA.

Body params

• project optional String

  The identifying name of the project associated with the call (default is the default project for the account).

• label optional String

  An optional message to use with the build status (default is "Skipped")

• group optional Boolean | String

  The status check group to post the status for, when no job has the project: true for the default group's Happo status check, or a group's name for Happo (<group>). Leave empty to post the project's own status.

• ifNotStarted optional Boolean

  Post nothing when a Happo run for the project (or, with a group, for any project in the group) has already started on the commit, instead of taking the project out of it. The response is then a JSON object saying whether a status was posted. Pass true wherever CI calls this in place of running Happo.

Response

• json SkipResult

  What the skip did, when called with ifNotStarted.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  The given SHA is not present in the origin repository.

Compare reports

POST /api/reports/:sha1/compare/:sha2

Compare reports and get useful information on the possible differences.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Body params

• project optional String

  The identifying name of the project the reports belong to. If none is specified, the default project will be assumed. Cannot be combined with "projects".

• projects optional Array<String>

  An array of project names to compare in a single request. When provided, the response will be an array of Comparison objects, each including a "project" field. If a comparison fails for an individual project (e.g. no report exists for that sha), that item will include an "error" field instead of comparison data — the other projects in the array are unaffected. Cannot be combined with "project".

• link optional String

  URL to the source of the report (e.g. PR URL).

• message optional String

  A short string describing the source of the report (e.g. PR title).

• notify optional String

  An email address, or a list of comma-separated email addresses that you want to notify with the results of the comparison.

• isAsync optional Boolean

  Set this option to true to make calls return immediately, without waiting for comparison results. You'll have to rely on the build status for the results. Using this option will also allow you to schedule future comparisons on reports that are currently being processed.

• fallbackShas optional Array<String>

  Provide a list of shas/report identifiers that the comparison is allowed to fall back to, if the sha1 param isn't matching any reports. The order of this list matters -- put the most desirable fallback first in the list.

• deepCompare optional DeepCompareSettings

  Override project deep compare settings for this comparison. When provided, these settings override any settings on the project.

• blockApproval optional BlockApproval

  What keeps this comparison from being approved. The happo library sends its blockApproval config option here. It applies to this comparison only, and replaces what an earlier request for the same two reports set.

Response

• json Comparison | AsyncComparison | Array<Comparison> | Array<AsyncComparison>

  When isAsync is false (default): a Comparison object, or an array of Comparison objects when "projects" is used. When isAsync is true: an AsyncComparison object, or an array of AsyncComparison objects when "projects" is used. Each array item includes a "project" field identifying the project, and an "error" field if the comparison failed for that project.

Error responses

• 400

  Both project and projects were specified (they are mutually exclusive), projects is not an array, or another validation error occurred. When using projects, per-project failures are returned as { project, error } items in the 200 response array rather than as a 400 status.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Get comparison status

GET /api/reports/:sha1/compare/:sha2/status

Get the comparison status between two reports. This endpoint can be used after the "Compare two reports" endpoint has been used, to check for the current resolution status.

An async comparison (isAsync: true) can compare with another "before" report than sha1: the report the "after" report extends, or a fallback or earlier commit when sha1 has no report. Asked for with sha1, this endpoint answers with that comparison, whose sha1 is the report it compared with. Until an async comparison is done, it answers 404.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Query params

• project optional String

  The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

• json ComparisonStatus

  An object with the current comparison status

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No comparison found for the given sha pair and project, or an async comparison of them that is not done yet.

Get comparison statuses

GET /api/reports/:sha/comparison-statuses

Get all comparison statuses for a sha. The response will contain a list of comparison statuses where the report is either the "before" report or the "after" report.

URL params

• :sha String

  The id of a report.

Query params

• project optional String

  The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

• json Array<ComparisonStatus>

  A list of comparison statuses for the :sha

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Get comparison results

GET /api/reports/:sha1/compare/:sha2/results

Get the full comparison results between two reports, including all snapshots grouped by their status: diffs, added, deleted, unchanged, and ignored diffs.

This endpoint is useful for programmatically reviewing visual changes — for example, to enable AI agents to inspect diffs for pull requests they are opening.

To look up results using a Happo comparison URL (/a/{accountId}/p/{projectId}/compare/{sha1}/{sha2}), extract the sha1 and sha2 path segments and use them as the path parameters here.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Query params

• project optional String

  The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

• json Comparison

  A Comparison object with full snapshot data for all diffs, added, deleted, unchanged, and ignored diffs.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No comparison found for the given sha pair and project.

Get comparisons

GET /api/comparisons

Get comparisons from your account.

Query params

• from optional Date

  (An ISO 8601 string) Get comparisons created after this timestamp.

• to optional Date

  (An ISO 8601 string) Get comparisons created before this timestamp.

• limit optional Number

  Default 10. Controls how many items are returned.

• project optional String

  The name of the project to return comparisons for. If left out, comparisons for all projects will be returned.

Response

• json Array<ComparisonStatus>

  A list of comparison statuses

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Create job

POST /api/jobs/:sha1/:sha2

Tell Happo that you are about to run a comparison between two shas. A job will either be created (when no orchestration job exists for the same shas) or reused (when an orchestration job exists for the shas).

When you pass a group, every project for the same shas joins one job instead, without an orchestration call, and the job posts one status check per group: Happo for the default group (true), and Happo (<group>) for a named one.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Body params

• project optional String

  The project (identifying name) which this job is running for. Leave empty to use the default project.

• projects optional Array<String>

  Pass an array of project names to create multiple jobs in one go. If orchestration is used, only one job will be created. If multiple jobs are created, the response will be an array of jobs.

• group optional Boolean | String

  The status check group the project reports to: true for the default group, which posts the Happo status check, or a name for a group of its own, Happo (<group>). Leave empty (or pass false) to get a job of its own for the project, as before groups existed.

• link optional String

  URL to the source of the job (e.g. PR URL).

• message optional String

  A short string describing the source of the job (e.g. PR title).

Response

• json Job | Array<Job>

  A Job object, or an array of Job objects when "projects" is used.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Create orchestration job

POST /api/jobs/:sha1/:sha2/orchestrate

Tell Happo that you are about to run multiple comparisons between two shas. A special report will be created and a single, combined build status will be posted to GitHub.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Body params

• projects Array<String>

  A list of projects (identifying names) that you want to be part of the job.

• link optional String

  URL to the source of the orchestration job (e.g. PR URL).

• message optional String

  A short string describing the source of the job (e.g. PR title).

Response

• json Job

  An object with details about the job that was created/found.

Error responses

• 400

  projects must be an array.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Cancel job

POST /api/jobs/:sha1/:sha2/cancel

Tell Happo that a job comparing two shas had to be cancelled for some reason. It might have been cancelled in CI or failed in some other way. When you're using orchestrated jobs, this can help prevent orchestrated jobs getting in an infinite "pending" state.

If the job is successfully cancelled, this endpoint will return a 204 No Content response.

If no job is found for the given SHA pair, this endpoint will return a 404 Not Found response.

If the job has already been completed, this endpoint will return a 409 Conflict response. This is expected behavior when the job has already finished processing.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Body params

• project optional String

  The project (identifying name) which this job is running for. Leave empty to use the default project.

• status optional String

  Either "failure" or "success". This will control what status will be posted to GitHub. The default is "failure".

• link optional String

  URL to the source of the report (e.g. PR URL).

• message optional String

  A description of why the job was cancelled, e.g. "Cancelled in CI"

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No job found for the given sha pair and project.

• 409

  The job has already been completed and cannot be cancelled. This is expected when the job has already finished processing.

Get jobs

GET /api/jobs

Get jobs from your account. A job encompasses creating a report and comparing that report with a previous report. Jobs can be automatically created (if you e.g. use any of the happo-ci* scripts) or manually via the API.

Query params

• from optional Date

  (An ISO 8601 string) Get jobs created after this timestamp.

• to optional Date

  (An ISO 8601 string) Get jobs created before this timestamp.

• limit optional Number

  Default 10. Controls how many items are returned. Max is 100 -- if you specify a larger number you will still get at most 100 back.

Response

• json Array<JobDetails>

  A list of jobs

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Get job

GET /api/jobs/:id

Get a job by its ID

URL params

• :id Number

  The ID of the job

Response

• json JobDetails

  Details about the job

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No job found with the given ID.

Resolve comparison

POST /api/reports/:sha1/compare/:sha2/resolve

Approve or reject the comparison between two reports, the same way a reviewer does from the Happo comparison page. The resolution isn't attributed to a Happo user. If the comparison is linked to a pull request, its Happo status check is updated too.

Pull request tokens can't be used with this endpoint. On an account that only lets selected users review, the request has to come from one of those reviewers: an API key one of them created, or their own Google IAP identity.

URL params

• :sha1 String

  The id of the "before" report.

• :sha2 String

  The id of the "after" report.

Body params

• resolution String

  Either "success" (approve the comparison) or "failure" (reject it).

• project optional String

  The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

• json ComparisonStatus

  An object with the updated comparison status

Error responses

• 400

  resolution is missing or not one of the allowed values, or project is not a string.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 403

  The request was authenticated with a pull request token, or the account only lets selected users review and the API key was not created by one of them.

• 404

  No project with the given name, or no comparison found for the given sha pair and project.

• 409

  The comparison cannot be approved because of what its blockApproval holds against it: examples in the after report failed to render, or the after report introduces new accessibility violations. Rejecting is still allowed.

Get flakes

GET /api/flake

Get a list of reported flakes for the current account, optionally filtered by project, component, variant, target, or sha.

Query params

• project optional String

  The identifying name of the project to filter flakes for. If omitted, flakes for all projects are returned.

• limit optional Number

  Default 100. Controls how many items are returned. Max is 1000.

• page optional Number

  Page number for pagination. First page is 1.

• component optional String

  Filter flakes by component name.

• variant optional String

  Filter flakes by variant name.

• target optional String

  Filter flakes by target name.

• sha optional String

  Filter flakes by comparisons that include this sha as before or after.

Response

• json Array<Flake>

  A list of reported flakes

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Ignore diff

POST /api/ignored-diffs

Use this endpoint to mark a diff between two snapshots as ignored. The snapshotId1/snapshotId2 params need to correspond to ids from Snapshot objects.

An ignored diff counts as accepted in every comparison that contains it. On an account that only lets selected users review, the request has to come from one of those reviewers: an API key one of them created, or their own Google IAP identity.

Body params

• snapshot1Id String

  A snapshot id

• snapshot2Id String

  A snapshot id

• project optional String

  The name of the project to ignore the diff for. If omitted, the project will be looked up in the database. Providing a project name is more efficient.

Response

• json Object

  An empty object.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 403

  The account only lets selected users review, and the request did not come from one of them (or from an API key one of them created).

• 404

  One or both snapshot IDs do not match any known snapshot.

Delete ignored diff

DELETE /api/ignored-diffs

Use this endpoint to remove an ignored diff between two snapshots. The snapshot1Id/snapshot2Id params need to correspond to ids from Snapshot objects.

On an account that only lets selected users review, the request has to come from one of those reviewers: an API key one of them created, or their own Google IAP identity.

Body params

• snapshot1Id String

  A snapshot id

• snapshot2Id String

  A snapshot id

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 403

  The account only lets selected users review, and the request did not come from one of them (or from an API key one of them created).

• 404

  One or both snapshot IDs were not provided or do not match any known ignored diff.

Add component subscriptions

POST /api/subscriptions/:component

Add subscribers (email addresses) to a specific UI component. When a diff is found in a component, subscribers are notified with a link to the Happo comparison. Users can themselves unsubscribe manually. If you try adding an email address that has been unsubscribed by the user, it will be ignored and the user will continue to be unsubscribed.

URL params

• :component String

  The name of a component. Should match component names that are in the reports.

Body params

• emailAddresses Array<String>

  A list of email addresses to add as subscribers.

Error responses

• 400

  emailAddresses is missing or contains invalid email addresses.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Remove component subscriptions

DELETE /api/subscriptions/:component

Remove subscribers for a specific UI component.

URL params

• :component String

  The name of a component. Should match component names that are in the reports.

Body params

• emailAddresses Array<String>

  A list of email addresses to remove subscriptions for.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Get snapshot

Experimental

GET /api/components/:component/:variant/:target

Get the latest snapshot for a component variant.

URL params

• :component String

  The name of a component. Should match component names that are in the reports.

• :variant String

  The name of the variant. Should match variant names that are in the reports.

• :target String

  The target of the snapshot. Should match target names that are in the reports.

Query params

• project optional String

  The identifying name of the project this report belongs to. If none is specified, the default project will be assumed.

Response

• json Snapshot

  An object with details about the snapshot.

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  No snapshot found for the given component, variant, and target.

Get diff counts

GET /api/diff-counts

Get a sorted list of components and the number of diffs they have in the project's comparisons. This endpoint can be used to figure out what components contribute the most to flaky/spurious diffs. Diffs are kept for a limited time (10 days by default), so a longer date range has no more to count.

Query params

• project optional String

  The identifying name of the project to fetch diff counts for. If none is specified, the default project will be used.

• from optional Date

  (An ISO 8601 string) Show diff counts after this point in time. Default is 30 days ago.

• to optional Date

  (An ISO 8601 string) Show diff counts up until this point in time. If you don't pass in this parameter, you'll get diff counts up until the current timestamp.

Response

• json Array

  An ordered list of components and their respective diff counts.

Error responses

• 400

  The from or to date parameter is not a valid ISO 8601 date string.

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

Get current usage

GET /api/billing/current-usage

Get the snapshots usage in the current billing cycle. If there is no active subscription for the account, you'll receive a 404 response.

Response

• json Usage

  Usage information for the current billing cycle

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.

• 404

  The account has no active subscription.

Get projects

GET /api/projects

Get all active projects (not archived) for the current account.

Response

• json Array<ProjectInfo>

  A list of projects

Error responses

• 401

  Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token.