API Docs
apps/api/src/routes. Edit the JSDoc block above a route to update its public API copy./auth/forgot-passwordRequest a password reset link.
Request a password reset link. Creates a short-lived reset token when the email exists. The response is intentionally generic so callers cannot discover registered emails.
/auth/loginSign in with email and password.
Sign in with email and password. Sets the same httpOnly session cookie used by the web app and returns the authenticated user payload.
/auth/logoutClear the current session cookie.
Clear the current session cookie. Use this from the browser when a user signs out. It is safe to call even when the cookie is already missing.
/auth/meReturn the current signed-in user.
Return the current signed-in user. Reads the JWT from the session cookie and returns the browser-safe user shape used to hydrate the dashboard session.
/auth/registerCreate an account and sign the user in.
Create an account and sign the user in. Stores a password-based user, sets the session cookie and returns the safe user payload with a JWT for non-browser clients.
/auth/reset-passwordReset a password with a valid reset token.
Reset a password with a valid reset token. Verifies the token, stores the new password hash and consumes the token so it cannot be reused.
/baseline-versionsList baseline versions for a page.
List baseline versions for a page. Returns immutable baseline history entries newest first. Pass a viewport to narrow the list for compare dropdowns.
/baseline-versions/:idGet one baseline version.
Get one baseline version. Returns a single immutable baseline history entry, including reviewer attribution when available.
/baseline-versions/compareCompare any two baseline versions.
Compare any two baseline versions. Generates an on-demand diff image between immutable versions. The versions must use the same viewport and belong to the same test suite.
/baselinesList current baselines for a test suite.
List current baselines for a test suite. Returns the approved baseline pointer documents, newest first. Use baseline versions when you need the full approval history.
/baselines/:idDelete a baseline and its screenshot file.
Delete a baseline and its screenshot file. Removes the database document and best-effort deletes the referenced image file. Missing files are logged but do not block the delete.
/baselines/:idGet one current baseline.
Get one current baseline. Fetches the current approved screenshot pointer by baseline id.
/baselines/:id/approveApprove one changed page result.
Approve one changed page result. The id is a PageResult id. Manual and branch runs promote the current screenshot immediately; PR runs mark the change accepted for merge-time promotion.
/integrations/github/installationsList GitHub App installations.
List GitHub App installations. Best-effort reconciles live installation data from GitHub unless `sync=0` is passed, then returns the stored installation list.
/integrations/github/installations/:installationId/reposList repositories for one GitHub App installation.
List repositories for one GitHub App installation. Reads live repository access from GitHub so the suite-linking UI can show the repos available to that installation.
/integrations/github/installations/syncForce a GitHub installation sync.
Force a GitHub installation sync. Calls GitHub for the current installation list, stores it locally and returns the refreshed records.
/integrations/github/statusGet GitHub App integration status.
Get GitHub App integration status. Tells the UI whether the app is configured, where to install it and which Check Run name viz will report.
/internal/cron/recrawlScan for suites due for a scheduled recrawl and enqueue them.
Scan for suites due for a scheduled recrawl and enqueue them. Wired to a Vercel Cron (hourly). Locally: `curl -H 'x-vercel-cron: 1' ...`.
/manual-runsList manual-run buckets.
List manual-run buckets. Returns lightweight single-URL buckets with run counts and their latest run, newest first. Only buckets the caller owns or has been granted access to are returned — scoped exactly like `GET /test-suites`.
/manual-runsCreate a manual-run bucket and start its first run.
Create a manual-run bucket and start its first run. Adds the supplied URL as the only tracked page. The first run captures the initial approved baseline for later comparisons. The caller becomes the owner and holds an implicit, non-removable ADMIN role on the bucket.
/manual-runs/:idDelete a manual-run bucket and its related data.
Delete a manual-run bucket and its related data. Removes page results, runs, tracked page records, baselines, every access grant on it, and then the bucket itself.
/manual-runs/:idGet a manual-run bucket with recent runs and baselines.
Get a manual-run bucket with recent runs and baselines. Manual-run buckets are stored as TestSuite documents with `kind: MANUAL`.
/manual-runs/:id/runStart another run for a manual-run bucket.
Start another run for a manual-run bucket. Re-tests the bucket's single URL and compares it with the baseline captured by the first run.
/test-runsList test runs with pagination.
List test runs with pagination. Returns recent runs from suites the caller can access, optionally filtered by suite or run status, with a small suite summary and page-result count for list screens.
/test-runs/:idDelete a test run.
Delete a test run. Removes the TestRun document. Related screenshots and page results are not cleaned up by this endpoint.
/test-runs/:idGet a test run with its suite and page results.
Get a test run with its suite and page results. Powers the run detail screen, including per-page screenshot, baseline and diff data.
/test-runs/:idUpdate a running test run.
Update a running test run. Currently supports the `cancel` action, which marks the run as cancelled. In-flight job runners check status and stop when they see CANCELLED.
/test-runs/:id/approve-visualsApprove every changed page in a run.
Approve every changed page in a run. Manual and branch runs promote baselines immediately. PR runs mark changes accepted and unblock the GitHub Check Run; promotion happens on merge.
/test-runs/:id/logsList stored logs for a test run.
List stored logs for a test run. Returns structured log entries in timestamp order. Pass `after` (ISO timestamp) to fetch only newer lines for incremental polling.
/test-runs/:id/rerunRe-run errored viewports for one page.
Re-run errored viewports for one page. Targets only ERROR-status results for the supplied URL inside an existing finished run, then updates those results in place.
/test-suitesList the caller's test suites with run counts and latest run.
List the caller's test suites with run counts and latest run. Only suites the caller owns or has been granted access to are returned; `scope` narrows that to just owned or just shared-with-me. Crawl-based suites are returned by default — pass `kind=MANUAL` for the lightweight manual-run buckets instead.
/test-suitesCreate a crawl-based test suite.
Create a crawl-based test suite. Creates the suite, queues the first discovery crawl and registers the automatic recrawl schedule from the suite settings. The creator becomes the owner and holds an implicit, non-removable ADMIN role on the suite.
/test-suites/:idDelete a test suite.
Delete a test suite. Removes the suite, its discovered pages, every access grant on it and its repeatable recrawl job. Run and baseline clean-up is handled separately.
/test-suites/:idGet a suite with recent runs and current baselines.
Get a suite with recent runs and current baselines. Use this for the suite detail screen before drilling into pages or an individual run.
/test-suites/:idUpdate a test suite.
Update a test suite. Updates basic settings, active state or GitHub link data. Changing the base URL queues a fresh discovery crawl because the sitemap is stale. Requires EDITOR, except for linking or unlinking a GitHub repo, which is an ADMIN action — it changes who the suite reports to outside the app.
/test-suites/:id/accessList who a suite is shared with.
List who a suite is shared with. Returns the owner separately (they hold an implicit ADMIN that has no grant row), every grant, and the caller's own access so the UI knows whether to render the management controls at all.
/test-suites/:id/accessShare a suite with a person (or, once teams ship, a team).
Share a suite with a person (or, once teams ship, a team). Identify the grantee by `email` or `userId`; the account must already exist. Re-sharing with someone who already has a grant updates their role rather than failing, so the UI can use one code path for both.
/test-suites/:id/access/:grantIdRevoke a share.
Revoke a share. The owner has no grant row, so this can never remove the owner's access.
/test-suites/:id/access/:grantIdChange the role on an existing share.
/test-suites/:id/crawlQueue a discovery crawl for a suite.
Queue a discovery crawl for a suite. Starts or restarts page discovery unless a recent crawl is already queued or running.
/test-suites/:id/pagesList discovered pages for a suite.
List discovered pages for a suite. Returns the sitemap view with crawl state, tracked counts and each page's outcome in the most recent finished manual run.
/test-suites/:id/pagesApply a bulk action to discovered pages.
Apply a bulk action to discovered pages. Tracks, untracks, acknowledges or deletes selected page records within a suite's discovered sitemap.
/test-suites/:id/pages/:pageIdGet one discovered page with current baselines.
Get one discovered page with current baselines. Returns the page, its latest per-viewport baselines and its latest manual run outcome for the page detail view.
/test-suites/:id/pages/:pageId/historyGet baseline history for one discovered page.
Get baseline history for one discovered page. Returns the timeline newest first. Each event includes the previous version where available so the UI can render before and after without another call.
/test-suites/:id/runQueue a new suite run.
Queue a new suite run. Omit the body for a manual run against the suite base URL, or pass a target preview URL for a branch diff that does not mutate baselines or GitHub.
/webhooks/githubReceive GitHub App webhooks.
Receive GitHub App webhooks. Verifies the GitHub HMAC signature, records installation changes and creates or promotes PR visual-regression runs for linked suites.
/webhooks/vercelReceive Vercel deployment webhooks.
Receive Vercel deployment webhooks. Verifies the Vercel signature and attaches ready preview deployment URLs to matching PR runs so screenshots can be queued.