API Reference

Authentication

All API endpoints are auth protected. To successfully issue a command, you need to provide an authentication header with your request. There are two ways to authenticate. JWT authentication is more secure but can be a little tricky to set up. HTTP Basic authentication is a less secure alternative, but is a good option if you want a simpler setup.

Basic authentication

With Basic authentication, you provide an Authorization: Basic <token> header where the token is a base64 encoded string of your apiKey:apiSecret tokens.

JWT authentication

This auth token is a JSON web token generated based on your API key and API secret. Pass { key: <your API key> } as the payload of the JWT call and the API secret as the secret, and set a kid header equal to the API key. Pass the resulting token as a Authorization: Bearer <generated token> header in all API requests.

An example of how to construct the JWT token can be found in the source code for the happo.io client.

Endpoints

Here's a full list of API paths you can call. All endpoints speak JSON. Body params are sent as a JSON blob in the body of the request. Responses are sent as JSON in the body of the HTTP response.

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

shaStringThe id of the report.

Body params

snapsArray<Snapshot>A list of snapshot objects associated with the report
projectString(optional) The identifying name of the project this report should belong to. If none is specified, the default project will be used.
linkString(optional) URL to the source of the report (e.g. PR URL).
messageString(optional) A short string describing the source of the report (e.g. PR title).
partialBoolean(optional) 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

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

Get report

GET /api/reports/:sha

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

URL params

shaStringThe id of the report.

Query params

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

Response

jsonArray<Snapshot>A list of snapshots associated with this sha.

Get report status

GET /api/reports/:sha/status

Gets some metadata about a report

URL params

shaStringThe id of the report.

Query params

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

Response

jsonReportStatusAn object containing useful information about a report

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

shaStringThe id of the report.

Body params

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

Response

jsonReportStatusAn object containing useful information about a report

Compare two reports

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

Compare reports and get useful information on the possible differences.

URL params

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.

Body params

projectString(optional) The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.
linkString(optional) URL to the source of the report (e.g. PR URL).
messageString(optional) A short string describing the source of the report (e.g. PR title).
notifyString(optional) An email address, or a list of comma-separated email addresses that you want to notify with the results of the comparison.
isAsyncBoolean(optional) 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 enable comparison fallbacks (see `fallbackShas`) and will allow you to schedule future comparisons on reports that are currently being processed.
fallbackShasArray<String>(optional) 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.

Response

jsonComparisonAn object with useful properties describing the differences between the two reports.

Get a 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.

URL params

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.

Body params

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

Response

jsonComparisonStatusAn object with the current comparison status

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

shaStringThe id of a report.

Body params

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

Response

jsonArray<ComparisonStatus>A list of comparison statuses for the :sha

Create an 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

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.

Body params

projectsArray<String> A list of projects (identifying names) that you want to be part of the job.
linkString(optional) URL to the source of the orchestration job (e.g. PR URL).
messageString(optional) A short string describing the source of the job (e.g. PR title).

Response

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

Create a 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).

URL params

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.

Body params

projectString(optional) The project (identifying name) which this job is running for. Leave empty to use the default project.
linkString(optional) URL to the source of the job (e.g. PR URL).
messageString(optional) A short string describing the source of the job (e.g. PR title).

Response

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

Cancel a 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.

URL params

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.

Body params

projectString(optional) The project (identifying name) which this job is running for. Leave empty to use the default project.
statusString(optional) Either "failure" or "success". This will control what status will be posted to GitHub. The default is "failure".
linkString(optional) URL to the source of the report (e.g. PR URL).
messageString(optional) A description of why the job was cancelled, e.g. "Cancelled in CI"

Fail a job

POST /api/jobs/:sha1/:sha2/fail

Deprecated - see "Cancel a job".

Ignore diff

POST /api/ignored-diffs

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

Body params

snapshot1IdStringA snapshot id
snapshot2IdStringA snapshot id

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 report. 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

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

Body params

emailAddressesArray<String>A list of email addresses to add as subscribers.

Remove component subscriptions

DELETE /api/subscriptions/:component

Remove subscribers for a specific UI component.

URL params

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

Body params

emailAddressesArray<String>A list of email addresses to remove subscriptions for.

Get snapshot
Experimental

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

Get the latest snapshot for a component variant.

URL params

componentStringThe name of a component. Should match component names that are in the reports.
variantStringThe name of the variant. Should match variant names that are in the reports.
targetStringThe target of the snapshot. Should match target names that are in the reports.

Query params

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

Response

jsonSnapshotAn object with details about the snapshot.

Skip

POST /api/skip/:sha

Tells Happo to skip running for a certain 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). Calling this endpoint will post a successful build status to the PR/commit.

URL params

shaStringThe sha of the commit to skip.

Body params

projectString(optional) The identifying name of the project associated with the call.
labelString(optional) An optional message to use with the build status (default is "Skipped")

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

fromShaStringThe id of the report to clone from
toShaStringThe id of the report to clone to

Body params

projectString(optional) The identifying name of the project for which the clone should be created. If none is specified, the default project will be used.
linkString(optional) URL to the source of the report (e.g. PR URL). If omitted, the link from the source/from report will be used
messageString(optional) 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

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

Objects

These are the domain objects you can come across while communicating with the API.

Snapshot

An object describing a screenshot of a certain component variant

urlString URL of the screenshot image. It's important that the URL is deterministically generated based on the contents of the image. A hash function (like md5) is of good help here, so that two images that have the same bitmap content end up having the same URL. More about URL creation.
variantStringThe name of the variant (e.g. "disabled")
targetStringThe snapshot's target (e.g. "firefox", "iphone 7")
componentStringThe name of the component shown in the screenshot (e.g. "Button")
heightNumberThe pixel height of the screenshot image
widthNumberThe pixel width of the screenshot image
idStringA unique identifier for the snapshot

ReportStatus

An object with useful properties for a report.

urlStringA URL leading to the report page
completedAtDate (An ISO 8601 string) Present if all the partials for a report have been added. Null otherwise. If you're not using partial reports, this value is always present.
createdAtDate (An ISO 8601 string) The timestamp for when the report was initially created.
snapshotCountNumberThe total number of snapshots included in the report

Comparison

An object with useful properties describing the differences between two reports.

diffsArray<Snapshot>A list of snapshots that are different
addedArray<Snapshot>Snapshots that have been added
deletedArray<Snapshot>Snapshots that have been removed
unchangedArray<Snapshot>A list of identical snapshots
summaryStringA summary of the results, with the most important information listed
equalBooleanTrue if the two reports are identical, false otherwise
statusString Either "failure" or "success". If the two reports are equal, or a user has manually accepted the comparison, the value is "success". If the two reports are not equal, or a user has manually rejected the comparison, the value is "failure".
compareUrlStringA link to a happo report page
statusImageUrlString A link to an image showing the status for the comparison

ComparisonStatus

An object with information about the status of a comparison.

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.
statusStringOne of three values: "success" when the comparison is approved, "failure" when the comparison has been rejected or "awaiting review" when the comparison needs a review
urlStringA URL leading to the comparison page
createdAtDate (An ISO 8601 string) The timestamp for when the comparison was initially created.

Job

An object with useful properties for a job.

urlStringA URL leading to the job page
idNumberA unique identifier for the job