openapi: 3.1.0 info: title: Happo API version: 1.0.0 description: Public API for the Happo visual regression and accessibility regression testing platform. servers: - url: https://happo.io security: - basicAuth: [] - bearerAuth: [] components: securitySchemes: basicAuth: type: http scheme: basic description: "Base64-encoded apiKey:apiSecret passed as an Authorization: Basic header." bearerAuth: type: http scheme: bearer bearerFormat: JWT description: "JWT token generated from apiKey and apiSecret, passed as an Authorization: Bearer header." schemas: Snapshot: type: object description: An object describing a screenshot of a certain component variant properties: url: type: - string - "null" description: 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. variant: type: - string - "null" description: The name of the variant (e.g. "disabled") target: type: - string - "null" description: The snapshot's target (e.g. "firefox", "iphone 7") component: type: - string - "null" description: The name of the component shown in the screenshot (e.g. "Button") width: type: - number - "null" description: The pixel width of the screenshot image height: type: - number - "null" description: The pixel height of the screenshot image id: type: - string - "null" description: A unique identifier for the snapshot SnapshotInfo: type: object description: An object with information about a screenshot image. properties: url: type: - string - "null" description: URL leading to the screenshot image width: type: - number - "null" description: The pixel width of the screenshot image height: type: - number - "null" description: The pixel height of the screenshot image ReportStatus: type: object description: An object with useful properties for a report. properties: url: type: - string - "null" description: A URL leading to the report page completedAt: type: - string - "null" format: date-time description: (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. createdAt: type: - string - "null" format: date-time description: (An ISO 8601 string) The timestamp for when the report was initially created. snapshotCount: type: - number - "null" description: The total number of snapshots included in the report IgnoredDiffDetails: type: object description: An object with details about why a diff was ignored. properties: byName: type: - string - "null" description: The display name of the user who ignored the diff, or null if ignored automatically. byEmail: type: - string - "null" description: The email of the user who ignored the diff, or null if ignored automatically. createdAt: type: - string - "null" format: date-time description: ISO 8601 timestamp for when the ignore was recorded. dataHappoHide: type: - boolean - "null" description: Present and true when the diff was automatically ignored because the element uses the `data-happo-hide` attribute. sourceComparison: type: object description: Present when the diff was ignored as a result of a reported flake. Contains `beforeSha`, `afterSha`, and `projectId` identifying the comparison that triggered the ignore. Comparison: type: object description: An object with useful properties describing the differences between two reports. properties: diffs: type: array items: type: array items: $ref: "#/components/schemas/Snapshot" description: A list of snapshots that are different. Each item in the array is a tuple/array with the before snapshot and the after snapshot. ignoredDiffs: type: array items: type: array prefixItems: - $ref: "#/components/schemas/Snapshot" - $ref: "#/components/schemas/Snapshot" - $ref: "#/components/schemas/IgnoredDiffDetails" minItems: 3 maxItems: 3 description: A list of diffs that were ignored. Each item in the array is a tuple/array with the before snapshot, the after snapshot, and details about why the diff was ignored. added: type: array items: $ref: "#/components/schemas/Snapshot" description: Snapshots that have been added deleted: type: array items: $ref: "#/components/schemas/Snapshot" description: Snapshots that have been removed unchanged: type: array items: $ref: "#/components/schemas/Snapshot" description: A list of identical snapshots summary: type: - string - "null" description: A summary of the results, with the most important information listed equal: type: - boolean - "null" description: True if the two reports are identical, false otherwise status: type: - string - "null" description: 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". compareUrl: type: - string - "null" description: A link to a happo report page statusImageUrl: type: - string - "null" description: A link to an image showing the status for the comparison ComparisonStatus: type: object description: An object with information about the status of a comparison. properties: sha1: type: - string - "null" description: The id of the "before" report. sha2: type: - string - "null" description: The id of the "after" report. status: type: - string - "null" description: 'One 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' url: type: - string - "null" description: A URL leading to the comparison page createdAt: type: - string - "null" format: date-time description: (An ISO 8601 string) The timestamp for when the comparison was initially created. diffs: type: - number - "null" description: The number of diffs in this comparison unchanged: type: - number - "null" description: The number of unchanged snapshots added: type: - number - "null" description: The number of added snapshots deleted: type: - number - "null" description: The number of added snapshots link: type: - string - "null" description: A URL leading to the PR/commit that triggered the comparison message: type: - string - "null" description: A description of the PR/commit that triggered the comparison project: type: - string - "null" description: The name of the project that this comparison belongs to Flake: type: object description: An object describing a reported flake. properties: project: type: - string - "null" description: The name of the project that this flake belongs to component: type: - string - "null" description: The component name variant: type: - string - "null" description: The variant name target: type: - string - "null" description: The target name snapshots: type: array items: $ref: "#/components/schemas/SnapshotInfo" description: An array with the before and after snapshots, in that order comparison: $ref: "#/components/schemas/ComparisonStatus" description: Comparison status for the flake, if available user: type: object properties: displayName: type: - string - "null" description: The display name of the user email: type: - string - "null" description: The email of the user required: - displayName - email description: The user who reported the flake createdAt: type: - string - "null" format: date-time description: (An ISO 8601 string) The creation timestamp occurrenceCount: type: - number - "null" description: The total number of times this flake has been detected across all comparisons Job: type: object description: A small object with basic properties for a job. properties: url: type: - string - "null" description: A URL leading to the job page id: type: - number - "null" description: A unique identifier for the job Usage: type: object description: Snapshots usage information properties: total: type: - number - "null" description: The number of snapshots used in a billing cycle quota: type: - number - "null" description: The number of snapshots included in the subscription start: type: - string - "null" format: date-time description: (An ISO 8601 string) The timestamp when the billing cycle starts end: type: - string - "null" format: date-time description: (An ISO 8601 string) The timestamp when the billing cycle ends ProjectInfo: type: object description: A small object with basic properties for a project. properties: id: type: - number - "null" description: A unique identifier for the project name: type: - string - "null" description: The name of the project JobDetails: type: object description: An object with useful properties for a job. properties: id: type: - number - "null" description: A unique identifier for the job createdAt: type: - string - "null" format: date-time description: (An ISO 8601 string) The creation timestamp for the job finishedAt: type: - string - "null" format: date-time description: (An ISO 8601 string) The timestamp when the job finished sha1: type: - string - "null" description: The ID of the "before" report sha2: type: - string - "null" description: The ID of the "after" report description: type: - string - "null" description: A description of the status that the job has status: type: - string - "null" description: Can be "failure", "success", or "pending" link: type: - string - "null" description: URL to the source of the job (e.g. PR URL). message: type: - string - "null" description: A short string describing the source of the job (e.g. PR title). url: type: - string - "null" description: A URL leading to the job page projects: type: array items: $ref: "#/components/schemas/ProjectInfo" description: A list of projects associated with the job DeepCompareSettings: type: object description: An object with settings for deep compare. properties: diffAlgorithm: type: - string - "null" description: Algorithm to use for diff comparison. Must be "color-delta" or "ssim". compareThreshold: type: - number - "null" description: Threshold for comparing images with the given diff algorithm (float between 0 and 1). ignoreThreshold: type: - number - "null" description: Threshold for ignoring individual pixel differences, side-stepping the compare threshold. Used relatively to the image size. E.g. a value of 0.01 means 1% of the pixels can be above the compare threshold. (float between 0 and 1). ignoreWhitespace: type: - boolean - "null" description: Whether to ignore whitespace in the diff. If true, whitespace differences will be ignored when comparing images. applyBlur: type: - boolean - "null" description: Whether to apply blur to the diff. This can be used to smooth out subtle differences that would otherwise be above the compare threshold. AsyncComparison: type: object description: "An object returned when a comparison is created with `isAsync: true`. The comparison will be completed asynchronously in the background." properties: id: type: - number - "null" description: The id of the async comparison. statusImageUrl: type: - string - "null" description: A URL to an SVG image showing the current status of the comparison. compareUrl: type: - string - "null" description: A URL to the comparison page. responses: Error401: description: Missing or invalid authentication credentials. All endpoints require authentication via Basic auth or Bearer token. content: text/plain: schema: type: string paths: /api/reports/{sha}: post: operationId: createReport summary: Create report security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: sha in: path required: true description: The id of the report. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: snaps: type: array items: $ref: "#/components/schemas/Snapshot" description: A list of snapshot objects associated with the report project: type: string description: The identifying name of the project this report should belong to. If none is specified, the default project will be used. link: type: string description: URL to the source of the report (e.g. PR URL). message: type: string description: A short string describing the source of the report (e.g. PR title). partial: type: boolean description: 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. required: - snaps responses: "200": description: An object containing a url where the uploaded report can be accessed content: application/json: schema: $ref: "#/components/schemas/ReportStatus" "400": description: The snapshot data is invalid (e.g. missing required fields), or the report has been archived and can no longer be modified. content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" get: operationId: getReport summary: Get report security: - basicAuth: [] - bearerAuth: [] description: Gets a list of snapshots for a certain identifier (usually a commit sha). parameters: - name: sha in: path required: true description: The id of the report. schema: type: string - name: project in: query required: false description: The identifying name of the project this report belongs to. If none is specified, the default project will be assumed. schema: type: string responses: "200": description: A list of snapshots associated with this sha. content: application/json: schema: type: array items: $ref: "#/components/schemas/Snapshot" "401": $ref: "#/components/responses/Error401" "404": description: No report found for the given sha and project. content: text/plain: schema: type: string /api/reports/{sha}/status: get: operationId: getReportStatus summary: Get report status security: - basicAuth: [] - bearerAuth: [] description: |- 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: ```json [ { "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" } ] ``` parameters: - name: sha in: path required: true description: The id of the report. schema: type: string - name: project in: query required: false description: 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". schema: type: string - name: projects in: query required: false description: 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". schema: type: string responses: "200": description: 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. content: application/json: schema: anyOf: - $ref: "#/components/schemas/ReportStatus" - type: array items: $ref: "#/components/schemas/ReportStatus" "400": description: Both `project` and `projects` were specified (they are mutually exclusive), or `projects` is not a valid comma-separated string. content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" "404": description: 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. content: text/plain: schema: type: string /api/reports/{sha}/complete: post: operationId: completeReport summary: Complete a report security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: sha in: path required: true description: The id of the report. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: project: type: string description: 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: type: array items: type: string description: 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". responses: "200": description: 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. content: application/json: schema: anyOf: - $ref: "#/components/schemas/ReportStatus" - type: array items: $ref: "#/components/schemas/ReportStatus" "400": description: Both `project` and `projects` were specified (they are mutually exclusive), or `projects` is not an array. content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" "404": description: 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. content: text/plain: schema: type: string /api/reports/{sha1}/compare/{sha2}: post: operationId: compareReports summary: Compare reports security: - basicAuth: [] - bearerAuth: [] description: Compare reports and get useful information on the possible differences. parameters: - name: sha1 in: path required: true description: The id of the "before" report. schema: type: string - name: sha2 in: path required: true description: The id of the "after" report. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: project: type: string description: 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: type: array items: type: string description: 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: type: string description: URL to the source of the report (e.g. PR URL). message: type: string description: A short string describing the source of the report (e.g. PR title). notify: type: string description: An email address, or a list of comma-separated email addresses that you want to notify with the results of the comparison. isAsync: type: boolean description: 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: type: array items: type: string description: 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: $ref: "#/components/schemas/DeepCompareSettings" description: Override project deep compare settings for this comparison. When provided, these settings override any settings on the project. responses: "200": description: '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.' content: application/json: schema: anyOf: - $ref: "#/components/schemas/Comparison" - $ref: "#/components/schemas/AsyncComparison" - type: array items: $ref: "#/components/schemas/Comparison" - type: array items: $ref: "#/components/schemas/AsyncComparison" "400": description: 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. content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" /api/reports/{sha1}/compare/{sha2}/status: get: operationId: getComparisonStatus summary: Get comparison status security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: sha1 in: path required: true description: The id of the "before" report. schema: type: string - name: sha2 in: path required: true description: The id of the "after" report. schema: type: string - name: project in: query required: false description: The identifying name of the project the reports belong to. If none is specified, the default project will be assumed. schema: type: string responses: "200": description: An object with the current comparison status content: application/json: schema: $ref: "#/components/schemas/ComparisonStatus" "401": $ref: "#/components/responses/Error401" "404": description: No comparison found for the given sha pair and project. content: text/plain: schema: type: string /api/reports/{sha1}/compare/{sha2}/results: get: operationId: getComparisonResults summary: Get comparison results security: - basicAuth: [] - bearerAuth: [] description: |- 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. parameters: - name: sha1 in: path required: true description: The id of the "before" report. schema: type: string - name: sha2 in: path required: true description: The id of the "after" report. schema: type: string - name: project in: query required: false description: The identifying name of the project the reports belong to. If none is specified, the default project will be assumed. schema: type: string responses: "200": description: A Comparison object with full snapshot data for all diffs, added, deleted, unchanged, and ignored diffs. content: application/json: schema: $ref: "#/components/schemas/Comparison" "401": $ref: "#/components/responses/Error401" "404": description: No comparison found for the given sha pair and project. content: text/plain: schema: type: string /api/reports/{sha}/comparison-statuses: get: operationId: getComparisonStatuses summary: Get comparison statuses security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: sha in: path required: true description: The id of a report. schema: type: string - name: project in: query required: false description: The identifying name of the project the reports belong to. If none is specified, the default project will be assumed. schema: type: string responses: "200": description: A list of comparison statuses for the :sha content: application/json: schema: type: array items: $ref: "#/components/schemas/ComparisonStatus" "401": $ref: "#/components/responses/Error401" /api/flake: get: operationId: getFlakes summary: Get flakes security: - basicAuth: [] - bearerAuth: [] description: Get a list of reported flakes for the current account, optionally filtered by project, component, variant, target, or sha. parameters: - name: project in: query required: false description: The identifying name of the project to filter flakes for. If omitted, flakes for all projects are returned. schema: type: string - name: limit in: query required: false description: Default 100. Controls how many items are returned. Max is 1000. schema: type: number - name: page in: query required: false description: Page number for pagination. First page is 1. schema: type: number - name: component in: query required: false description: Filter flakes by component name. schema: type: string - name: variant in: query required: false description: Filter flakes by variant name. schema: type: string - name: target in: query required: false description: Filter flakes by target name. schema: type: string - name: sha in: query required: false description: Filter flakes by comparisons that include this sha as before or after. schema: type: string responses: "200": description: A list of reported flakes content: application/json: schema: type: array items: $ref: "#/components/schemas/Flake" "401": $ref: "#/components/responses/Error401" /api/comparisons: get: operationId: getComparisons summary: Get comparisons security: - basicAuth: [] - bearerAuth: [] description: Get comparisons from your account. parameters: - name: from in: query required: false description: (An ISO 8601 string) Get comparisons created after this timestamp. schema: type: string format: date-time - name: to in: query required: false description: (An ISO 8601 string) Get comparisons created before this timestamp. schema: type: string format: date-time - name: limit in: query required: false description: Default 10. Controls how many items are returned. schema: type: number - name: project in: query required: false description: The name of the project to return comparisons for. If left out, comparisons for all projects will be returned. schema: type: string responses: "200": description: A list of comparison statuses content: application/json: schema: type: array items: $ref: "#/components/schemas/ComparisonStatus" "401": $ref: "#/components/responses/Error401" /api/jobs/{sha1}/{sha2}/orchestrate: post: operationId: orchestrate summary: Create orchestration job security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: sha1 in: path required: true description: The id of the "before" report. schema: type: string - name: sha2 in: path required: true description: The id of the "after" report. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: projects: type: array items: type: string description: A list of projects (identifying names) that you want to be part of the job. link: type: string description: URL to the source of the orchestration job (e.g. PR URL). message: type: string description: A short string describing the source of the job (e.g. PR title). required: - projects responses: "200": description: An object with details about the job that was created/found. content: application/json: schema: $ref: "#/components/schemas/Job" "400": description: "`projects` must be an array." content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" /api/jobs/{sha1}/{sha2}: post: operationId: createJob summary: Create job security: - basicAuth: [] - bearerAuth: [] description: 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). parameters: - name: sha1 in: path required: true description: The id of the "before" report. schema: type: string - name: sha2 in: path required: true description: The id of the "after" report. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: project: type: string description: The project (identifying name) which this job is running for. Leave empty to use the default project. projects: type: array items: type: string description: 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. link: type: string description: URL to the source of the job (e.g. PR URL). message: type: string description: A short string describing the source of the job (e.g. PR title). responses: "200": description: A Job object, or an array of Job objects when "projects" is used. content: application/json: schema: anyOf: - $ref: "#/components/schemas/Job" - type: array items: $ref: "#/components/schemas/Job" "401": $ref: "#/components/responses/Error401" /api/jobs/{sha1}/{sha2}/cancel: post: operationId: cancelJob summary: Cancel job security: - basicAuth: [] - bearerAuth: [] description: |- 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. parameters: - name: sha1 in: path required: true description: The id of the "before" report. schema: type: string - name: sha2 in: path required: true description: The id of the "after" report. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: project: type: string description: The project (identifying name) which this job is running for. Leave empty to use the default project. status: type: string description: Either "failure" or "success". This will control what status will be posted to GitHub. The default is "failure". link: type: string description: URL to the source of the report (e.g. PR URL). message: type: string description: A description of why the job was cancelled, e.g. "Cancelled in CI" responses: "204": description: No content "401": $ref: "#/components/responses/Error401" "404": description: No job found for the given sha pair and project. content: text/plain: schema: type: string "409": description: The job has already been completed and cannot be cancelled. This is expected when the job has already finished processing. content: text/plain: schema: type: string /api/jobs: get: operationId: getJobs summary: Get jobs security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: from in: query required: false description: (An ISO 8601 string) Get jobs created after this timestamp. schema: type: string format: date-time - name: to in: query required: false description: (An ISO 8601 string) Get jobs created before this timestamp. schema: type: string format: date-time - name: limit in: query required: false description: 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. schema: type: number responses: "200": description: A list of jobs content: application/json: schema: type: array items: $ref: "#/components/schemas/JobDetails" "401": $ref: "#/components/responses/Error401" /api/jobs/{id}: get: operationId: getJob summary: Get job security: - basicAuth: [] - bearerAuth: [] description: Get a job by its ID parameters: - name: id in: path required: true description: The ID of the job schema: type: number responses: "200": description: Details about the job content: application/json: schema: $ref: "#/components/schemas/JobDetails" "401": $ref: "#/components/responses/Error401" "404": description: No job found with the given ID. content: text/plain: schema: type: string /api/ignored-diffs: post: operationId: ignoreDiff summary: Ignore diff security: - basicAuth: [] - bearerAuth: [] description: Use this endpoint to mark a diff between two snapshots as ignored. The snapshotId1/snapshotId2 params need to correspond to `id`s from Snapshot objects. requestBody: required: true content: application/json: schema: type: object properties: snapshot1Id: type: string description: A snapshot id snapshot2Id: type: string description: A snapshot id project: type: string description: 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. required: - snapshot1Id - snapshot2Id responses: "200": description: An empty object. content: application/json: schema: type: object "401": $ref: "#/components/responses/Error401" "404": description: One or both snapshot IDs do not match any known snapshot. content: text/plain: schema: type: string delete: operationId: deleteIgnoredDiff summary: Delete ignored diff security: - basicAuth: [] - bearerAuth: [] description: Use this endpoint to remove an ignored diff between two snapshots. The snapshot1Id/snapshot2Id params need to correspond to `id`s from Snapshot objects. requestBody: required: true content: application/json: schema: type: object properties: snapshot1Id: type: string description: A snapshot id snapshot2Id: type: string description: A snapshot id required: - snapshot1Id - snapshot2Id responses: "204": description: No content "401": $ref: "#/components/responses/Error401" "404": description: One or both snapshot IDs were not provided or do not match any known ignored diff. content: text/plain: schema: type: string /api/subscriptions/{component}: post: operationId: addSubscriptions summary: Add component subscriptions security: - basicAuth: [] - bearerAuth: [] description: 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. parameters: - name: component in: path required: true description: The name of a component. Should match component names that are in the reports. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: emailAddresses: type: array items: type: string description: A list of email addresses to add as subscribers. required: - emailAddresses responses: "204": description: No content "400": description: "`emailAddresses` is missing or contains invalid email addresses." content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" delete: operationId: removeSubscriptions summary: Remove component subscriptions security: - basicAuth: [] - bearerAuth: [] description: Remove subscribers for a specific UI component. parameters: - name: component in: path required: true description: The name of a component. Should match component names that are in the reports. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: emailAddresses: type: array items: type: string description: A list of email addresses to remove subscriptions for. required: - emailAddresses responses: "204": description: No content "401": $ref: "#/components/responses/Error401" /api/components/{component}/{variant}/{target}: get: operationId: snapshot summary: Get snapshot security: - basicAuth: [] - bearerAuth: [] description: Get the latest snapshot for a component variant. parameters: - name: component in: path required: true description: The name of a component. Should match component names that are in the reports. schema: type: string - name: variant in: path required: true description: The name of the variant. Should match variant names that are in the reports. schema: type: string - name: target in: path required: true description: The target of the snapshot. Should match target names that are in the reports. schema: type: string - name: project in: query required: false description: The identifying name of the project this report belongs to. If none is specified, the default project will be assumed. schema: type: string responses: "200": description: An object with details about the snapshot. content: application/json: schema: $ref: "#/components/schemas/Snapshot" "401": $ref: "#/components/responses/Error401" "404": description: No snapshot found for the given component, variant, and target. content: text/plain: schema: type: string /api/skip/{sha}: post: operationId: skip summary: Skip report security: - basicAuth: [] - bearerAuth: [] description: |- 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. If the SHA is not present in the origin repo, the call will fail with a 404 error. parameters: - name: sha in: path required: true description: The SHA of the commit to skip. This must be the full SHA, not a partial SHA. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: project: type: string description: The identifying name of the project associated with the call (default is the default project for the account). label: type: string description: An optional message to use with the build status (default is "Skipped") responses: "204": description: No content "401": $ref: "#/components/responses/Error401" "404": description: The given SHA is not present in the origin repository. content: text/plain: schema: type: string /api/reports/{fromSha}/clone/{toSha}: post: operationId: cloneReport summary: Clone report security: - basicAuth: [] - bearerAuth: [] description: |- 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. parameters: - name: fromSha in: path required: true description: The id of the report to clone from schema: type: string - name: toSha in: path required: true description: The id of the report to clone to schema: type: string requestBody: required: false content: application/json: schema: type: object properties: project: type: string description: The identifying name of the project for which the clone should be created. If none is specified, the default project will be used. link: type: string description: URL to the source of the report (e.g. PR URL). If omitted, the link from the source/from report will be used message: type: string description: 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. responses: "200": description: An object containing a url where the uploaded report can be accessed content: application/json: schema: $ref: "#/components/schemas/ReportStatus" "401": $ref: "#/components/responses/Error401" "404": description: The source report (`fromSha`) does not exist for the given project. content: text/plain: schema: type: string /api/diff-counts: get: operationId: diffCounts summary: Get diff counts security: - basicAuth: [] - bearerAuth: [] description: Get a sorted list of components and the number of diffs they have for reports created on the main branch. This endpoint can be used to figure out what components contribute the most to flaky/spurious diffs. parameters: - name: project in: query required: false description: The identifying name of the project to fetch diff counts for. If none is specified, the default project will be used. schema: type: string - name: from in: query required: false description: (An ISO 8601 string) Show diff counts after this point in time. Default is 30 days ago. schema: type: string format: date-time - name: to in: query required: false description: (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. schema: type: string format: date-time responses: "200": description: An ordered list of components and their respective diff counts. content: application/json: schema: type: array "400": description: The `from` or `to` date parameter is not a valid ISO 8601 date string. content: text/plain: schema: type: string "401": $ref: "#/components/responses/Error401" /api/billing/current-usage: get: operationId: billingCurrentUsage summary: Get current usage security: - basicAuth: [] - bearerAuth: [] description: Get the snapshots usage in the current billing cycle. If there is no active subscription for the account, you'll receive a 404 response. responses: "200": description: Usage information for the current billing cycle content: application/json: schema: $ref: "#/components/schemas/Usage" "401": $ref: "#/components/responses/Error401" "404": description: The account has no active subscription. content: text/plain: schema: type: string /api/projects: get: operationId: getProjects summary: Get projects security: - basicAuth: [] - bearerAuth: [] description: Get all active projects (not archived) for the current account. responses: "200": description: A list of projects content: application/json: schema: type: array items: $ref: "#/components/schemas/ProjectInfo" "401": $ref: "#/components/responses/Error401"