Happo exposes a public, REST-like, API that you can use to create or enhance custom integrations. The API resides at https://happo.io, and all endpoints use the /api namespace.
OpenAPI spec for the public Happo API
Want to use Happo from Claude, ChatGPT, Cursor, or another AI assistant? Happo also runs an MCP server with OAuth so AI agents can list comparisons, inspect diffs, and approve, reject, or report flakes for them.
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.
With Basic authentication, you provide an Authorization: Basic <token> header where the token is a base64 encoded string of your apiKey:apiSecret tokens.
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.
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.
POST /
:sha Stringsnaps Array<Snapshot>project optional Stringlink optional Stringmessage optional Stringpartial optional Booleanjson ReportStatus400401GET /
:sha Stringproject optional Stringjson Array<Snapshot>401404GET /
:sha Stringproject optional Stringprojects optional Stringjson ReportStatus | Array<ReportStatus>400401404POST /
:sha Stringproject optional Stringprojects optional Array<String>json ReportStatus | Array<ReportStatus>400401404POST /
:fromSha String:toSha Stringproject optional Stringlink optional Stringmessage optional Stringjson ReportStatus401404POST /
:sha Stringproject optional Stringlabel optional String401404POST /
:sha1 String:sha2 Stringproject optional Stringprojects optional Array<String>link optional Stringmessage optional Stringnotify optional StringisAsync optional BooleanfallbackShas optional Array<String>deepCompare optional DeepCompareSettingsblockApproval optional BlockApprovaljson Comparison | AsyncComparison | Array<Comparison> | Array<AsyncComparison>400401GET /
:sha1 String:sha2 Stringproject optional Stringjson ComparisonStatus401404GET /
:sha Stringproject optional Stringjson Array<ComparisonStatus>401GET /
:sha1 String:sha2 Stringproject optional Stringjson Comparison401404GET /
from optional Dateto optional Datelimit optional Numberproject optional Stringjson Array<ComparisonStatus>401POST /
:sha1 String:sha2 Stringproject optional Stringprojects optional Array<String>link optional Stringmessage optional String401POST /
:sha1 String:sha2 Stringprojects Array<String>link optional Stringmessage optional Stringjson Job400401POST /
:sha1 String:sha2 Stringproject optional Stringstatus optional Stringlink optional Stringmessage optional String401404409GET /
from optional Dateto optional Datelimit optional Numberjson Array<JobDetails>401POST /
:sha1 String:sha2 Stringresolution Stringproject optional Stringjson ComparisonStatus400401403404409GET /
project optional Stringlimit optional Numberpage optional Numbercomponent optional Stringvariant optional Stringtarget optional Stringsha optional Stringjson Array<Flake>401POST /
snapshot1Id Stringsnapshot2Id Stringproject optional Stringjson Object401404DELETE /
snapshot1Id Stringsnapshot2Id String401404POST /
:component StringemailAddresses Array<String>400401DELETE /
:component StringemailAddresses Array<String>401GET /
:component String:variant String:target Stringproject optional Stringjson Snapshot401404GET /
project optional Stringfrom optional Dateto optional Datejson Array400401These are the domain objects you can come across while communicating with the API.
An object describing a screenshot of a certain component variant
url Stringvariant Stringtarget Stringcomponent Stringwidth Numberheight Numberid StringAn object with useful properties for a report.
url StringcompletedAt DatecreatedAt DatesnapshotCount NumberAn object with details about why a diff was ignored.
byName StringbyEmail StringcreatedAt DatedataHappoHide optional BooleansourceComparison optional ObjectAn object with useful properties describing the differences between two reports.
An object with information about the status of a comparison.
sha1 Stringsha2 Stringstatus Stringurl StringcreatedAt Datediffs Numberunchanged Numberadded Numberdeleted Numberlink Stringmessage Stringproject StringAn object describing a reported flake.
project Stringcomponent Stringvariant Stringtarget Stringsnapshots Array<SnapshotInfo>comparison ComparisonStatususer ObjectcreatedAt DateoccurrenceCount NumberAn object with useful properties for a job.
id NumbercreatedAt DatefinishedAt Datesha1 Stringsha2 Stringdescription Stringstatus Stringlink optional Stringmessage optional Stringurl Stringprojects Array<ProjectInfo>An object with settings for deep compare.
diffAlgorithm StringcompareThreshold NumberignoreThreshold NumberignoreWhitespace BooleanapplyBlur BooleanWhat keeps a comparison from being approved. Both attributes are optional, and leaving one out means it is not specified. Approving a blocked comparison is refused with a 409, and an approval carried over from an earlier comparison does not apply to it.
renderErrors BooleanaccessibilityViolations BooleanAn object returned when a comparison is created with `isAsync: true`. The comparison will be completed asynchronously in the background.
id NumberstatusImageUrl StringcompareUrl String