# Empirical

- [Introduction](https://empirical.run/docs/index.md): Welcome to Empirical docs
- [CLI](https://empirical.run/docs/cli.md): Install and configure the Empirical command line tool
- [Environments](https://empirical.run/docs/platform/environments.md): Run your tests across different deployments
- [Repository](https://empirical.run/docs/platform/repository.md): Your test code repository on GitHub
- [Requests](https://empirical.run/docs/platform/requests.md): Ask our agents to write new tests
- [Issues](https://empirical.run/docs/platform/issues.md): Investigate and resolve test failures
- [Snoozes](https://empirical.run/docs/platform/snoozes.md): Suppress known failures while you work on a fix
- [Memories](https://empirical.run/docs/platform/memories.md): Durable knowledge about your product that guides test generation agents
- [Test Run Configuration](https://empirical.run/docs/platform/test-run-configuration.md): Configure regions, shards, and notifications for your test runs
- [Branching](https://empirical.run/docs/features/branching.md): Align tests changes with new feature and environments
- [Concurrency Limits](https://empirical.run/docs/features/concurrency-limits.md): Control how concurrent test runs are handled within a project
- [Analytics](https://empirical.run/docs/features/analytics.md): Track test health and performance over time
- [Code Coverage](https://empirical.run/docs/features/code-coverage.md): Measure code coverage for your test runs
- [Slack Notifications](https://empirical.run/docs/features/slack-notifications.md): Tag test owners in Slack when tests fail
- [Email Testing](https://empirical.run/docs/features/email-testing.md): Test email workflows like OTPs, invitations, and notifications
- [Webhook Testing](https://empirical.run/docs/features/webhook-testing.md): Assert that your application sends the correct webhooks
- [Slack](https://empirical.run/docs/integrations/slack.md): Install and configure our Slack app
- [GitHub Reporter](https://empirical.run/docs/integrations/github.md): Install and configure our GitHub Reporter app
- [Linear](https://empirical.run/docs/integrations/linear.md): Create coverage requests from Linear issues
- [Jira](https://empirical.run/docs/integrations/jira.md): Create coverage requests from Jira tickets
- [From CI/CD pipelines](https://empirical.run/docs/triggers/ci-cd.md): Run tests after production or pre-prod deployments
- [Scheduled runs](https://empirical.run/docs/triggers/scheduled.md): Run tests on schedule
- [Ad-hoc runs](https://empirical.run/docs/triggers/ad-hoc.md): Trigger a test run once via Dashboard or Slack
- [Introduction](https://empirical.run/docs/api-reference/introduction.md): Base URL and authentication for the Empirical API
- [List test runs](https://empirical.run/docs/api-reference/test-runs/list-test-runs.md): Returns a paginated list of test runs for the scoped project, with optional filtering by id, branch, state, result, environment, and time window.
- [Trigger a test run](https://empirical.run/docs/api-reference/test-runs/trigger-a-test-run.md): Triggers a new end-to-end test run for the scoped project against the given environment, resolving the branch/build and dispatching the run.
- [Get a test run](https://empirical.run/docs/api-reference/test-runs/get-a-test-run.md): Retrieves a single test run by ID, including its project and per-test summary details. Access is derived from the run's project; inaccessible or unknown runs return 404.
- [List test run artifacts](https://empirical.run/docs/api-reference/test-runs/list-test-run-artifacts.md): Lists downloadable artifacts (traces, reports, screenshots, etc.) stored for a test run. Provide `key` for an exact lookup, or `prefix`/`suffix` to filter the listing. Returns an empty list when nothing matches.
- [Cancel a test run](https://empirical.run/docs/api-reference/test-runs/cancel-a-test-run.md): Cancels an in-progress test run, recording an optional reason and the cancelling user. Returns 412 when the run is already in a terminal state.
- [Re-run a test run](https://empirical.run/docs/api-reference/test-runs/re-run-a-test-run.md): Re-triggers a test run from a source run's branch, build, and overrides. Optionally re-runs only the failed tests of a completed run.
- [Skip a test run](https://empirical.run/docs/api-reference/test-runs/skip-a-test-run.md): Marks the Empirical check run on a commit as skipped. Callers authenticate with a project API key.
- [List test case tags](https://empirical.run/docs/api-reference/test-cases/list-test-case-tags.md): Returns the distinct set of tags across the scoped project's active test cases (those present at the last synced commit; all synced test cases if the project has never synced). The response is a bare `{ tags }` object (no `data` envelope) and is cached for 5 minutes via a `Cache-Control` header.
- [List test cases](https://empirical.run/docs/api-reference/test-cases/list-test-cases.md): Returns a paginated list of the scoped project's test cases with optional filtering, along with the project's latest test-cases sync error.
- [Get a test case](https://empirical.run/docs/api-reference/test-cases/get-a-test-case.md): Retrieves a single test case by its Playwright test ID. Access is derived from the test case's project, returning 403 when the caller cannot access it.
- [Update test case tags](https://empirical.run/docs/api-reference/test-cases/update-test-case-tags.md): Replaces the tags on a test case and attempts to update the source file. Access is derived from the test case's project, returning 403 when the caller cannot access it.
- [List environments](https://empirical.run/docs/api-reference/environments/list-environments.md): Returns the scoped project's environments, optionally filtered by slug and disabled state. The run worker uses this to resolve env vars by slug.
- [Create an environment](https://empirical.run/docs/api-reference/environments/create-an-environment.md): Creates an environment in the scoped project. Rejected for projects managed by environments.yaml.
- [Sync environments from YAML](https://empirical.run/docs/api-reference/environments/sync-environments-from-yaml.md): Upserts the scoped project's environments from its environments.yaml file and flags the project as YAML-managed.
- [Delete an environment](https://empirical.run/docs/api-reference/environments/delete-an-environment.md): Deletes an environment by ID and prunes environment-specific subscriptions. The project is derived from the entity.
- [Update an environment](https://empirical.run/docs/api-reference/environments/update-an-environment.md): Updates an environment by ID. The project is derived from the entity. Returns the bare updated row (no `data` envelope), matching the dashboard settings UI it serves.
- [List snoozes](https://empirical.run/docs/api-reference/snoozes/list-snoozes.md): Returns a paginated list of snoozes for the scoped project, with optional filtering by environment and status.
- [Create a snooze](https://empirical.run/docs/api-reference/snoozes/create-a-snooze.md): Creates a snooze to temporarily suppress failures for the given Playwright tests until `snooze_until`.
- [Get a snooze](https://empirical.run/docs/api-reference/snoozes/get-a-snooze.md): Retrieves a single snooze by ID.
- [Delete a snooze](https://empirical.run/docs/api-reference/snoozes/delete-a-snooze.md): Permanently deletes a snooze.
- [Update a snooze](https://empirical.run/docs/api-reference/snoozes/update-a-snooze.md): Updates a snooze — extend it, change its tests/description, or expire it immediately with `expire_now`.
- [Add tests to a snooze](https://empirical.run/docs/api-reference/snoozes/add-tests-to-a-snooze.md): Adds Playwright tests to an existing snooze.
- [Test-run analytics](https://empirical.run/docs/api-reference/analytics/test-run-analytics.md): Returns daily test-run statistics and a period summary for the scoped project.
- [Test-count analytics](https://empirical.run/docs/api-reference/analytics/test-count-analytics.md): Returns the number of distinct test cases run per day for the scoped project.
- [Test-case analytics](https://empirical.run/docs/api-reference/analytics/test-case-analytics.md): Returns aggregated test-case metrics for the scoped project (without per-test history).
- [Test-case execution history (batch)](https://empirical.run/docs/api-reference/analytics/test-case-execution-history-batch.md): Returns per-test-case execution history for the requested test cases, plus echoed query metadata.
- [Last passing run per environment](https://empirical.run/docs/api-reference/analytics/last-passing-run-per-environment.md): Returns the most recent passing run for a test case, grouped by environment.
- [List resources](https://empirical.run/docs/api-reference/resources/list-resources.md): Returns a paginated list of uploaded resources for the project.
- [Create a resource](https://empirical.run/docs/api-reference/resources/create-a-resource.md): Creates a resource. With `url`, creates a link-type file; otherwise creates a pending upload and returns a signed `upload_url` to stream the file into R2.
- [Download resource content](https://empirical.run/docs/api-reference/resources/download-resource-content.md): Streams an uploaded resource's content from R2. Authorized by the signed capability URL (HMAC in the query string), not bearer auth.
- [Upload resource content](https://empirical.run/docs/api-reference/resources/upload-resource-content.md): Streams the request body into R2 for a pending resource. Authorized by the signed capability URL (HMAC in the query string), not bearer auth.
- [Get a resource](https://empirical.run/docs/api-reference/resources/get-a-resource.md): Retrieves a single resource by ID, with a fresh download URL.
- [Delete a resource](https://empirical.run/docs/api-reference/resources/delete-a-resource.md): Deletes a resource, removing its R2 object and stopping any active Drive watch.
- [Update a resource](https://empirical.run/docs/api-reference/resources/update-a-resource.md): Updates a resource's name/description, or confirms a pending upload with `status: "uploaded"`.
- [List failure groups](https://empirical.run/docs/api-reference/failure-groups/list-failure-groups.md): Returns a paginated list of failure groups for the scoped project, newest sighting first. Use this to match a failure against an existing group before creating a new one.
- [Create a failure group](https://empirical.run/docs/api-reference/failure-groups/create-a-failure-group.md): Creates a durable failure group for a new failure mode. Labels are unique per project: if the label already exists the request fails with 409 and returns the existing group unchanged — inspect it (note its status) and either reuse it via PATCH/attach or create under a different label.
- [List a run's failure-group members](https://empirical.run/docs/api-reference/failure-groups/list-a-runs-failure-group-members.md): Returns one entry per failed test in the run that is attached to a failure group, with the group's content hydrated. Read from the canonical membership-event log; when several sources attached the same test, human wins over agent over machine. Dedupe on group_id for the run's distinct groups.
- [Get a failure group](https://empirical.run/docs/api-reference/failure-groups/get-a-failure-group.md): Retrieves a single failure group. Its members are served by `GET /api/failure-groups/{id}/members`.
- [Delete a failure group](https://empirical.run/docs/api-reference/failure-groups/delete-a-failure-group.md): Deletes a failure group and its members. Its edit-history revisions survive.
- [Update a failure group](https://empirical.run/docs/api-reference/failure-groups/update-a-failure-group.md): Updates a group's authored fields. `fingerprint`, when present, replaces the stored one; omit it to keep it. Latest write wins. Renaming to a label another group holds fails with 409 and returns that group — if the two are the same failure mode, merge them instead.
- [Get a failure group's activity](https://empirical.run/docs/api-reference/failure-groups/get-a-failure-groups-activity.md): Returns the group's activity timeline (newest first): creation, authored edits, status changes, merges, member joins, repeat sightings, and removals. Derived from the revision trail and the membership-event log.
- [List a failure group's members](https://empirical.run/docs/api-reference/failure-groups/list-a-failure-groups-members.md): Returns the group's members (one entry per test, newest sighting first), derived from the membership-event log: state, provenance of the latest attach, first/last sighting, sighting count and environments.
- [Attach a failing test to a failure group](https://empirical.run/docs/api-reference/failure-groups/attach-a-failing-test-to-a-failure-group.md): Records that a run's failing test belongs to this group, refreshing the group's last-seen rollups, and returns the derived member entry. Idempotent: re-attaching an existing member refreshes its sighting (the entry's sighting_count and last_seen reflect it). An agent attach will not resurrect a memb…
- [Merge a failure group into another](https://empirical.run/docs/api-reference/failure-groups/merge-a-failure-group-into-another.md): Moves this group's members into the target, unions fingerprints, and deletes this group. Returns the target.
- [Get an environment status badge](https://empirical.run/docs/api-reference/badges/get-an-environment-status-badge.md): Renders an SVG status badge (passing/failing/running/etc.) for the latest test run of a project environment. Served unauthenticated for embedding in READMEs.

## OpenAPI Specs

- [openapi.generated](/docs/api-reference/openapi.generated.json)
- [openapi](/docs/api-reference/openapi.json)