API Reference - Checksum AI

Base URL

https://api.checksum.ai/public-api/v1/

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

You can create and manage API keys from Settings > Project Settings in the Checksum dashboard.

Typical Flow

Most integrations use the endpoints in this order:

Confirm the API key and project with GET /me.
Trigger a run with an execution endpoint, or choose affected tests first with POST /affected-tests.
Poll the returned run ID with GET /execution/status/run/:runId.
Read the run details with the test result endpoints.
Send failures into auto-healing, either by including autoHeal when you start the run or by calling POST /auto-heal afterward.

Project Info

Get project info

GET /public-api/v1/me

Returns basic information about the project associated with the API key. This is useful as a lightweight auth check before triggering runs. Response

{
  "id": "project-abc-123",
  "name": "My Project",
  "hasTestsRepo": true
}

Test Selection

Get affected tests

POST /public-api/v1/affected-tests

Returns the Checksum test IDs most likely affected by a set of changed source files. Use those IDs with POST /execution/tests when you want CI to run only the relevant tests for a change. Request body

{
  "changedFiles": [
    "src/checkout/payment.ts",
    "src/cart/cart.service.ts"
  ]
}

Field	Required	Description
`changedFiles`	Yes	Changed source file paths, such as the output of `git diff --name-only`. Capped at 1,000 files

Response

{
  "affectedTestIds": ["D7iP0", "Ab3xY"]
}

Execution

Run all tests

POST /public-api/v1/execution/suite

Triggers a full test-suite run. Optional body — auto-heal on failure

{
  "autoHeal": {
    "autoCreatePR": true,
    "branch": "main",
    "repoName": "acme-co/my-tests",
    "prNumber": 42
  }
}

When present, Checksum automatically starts healing if the run ends failed. Same autoHeal block is supported on collection, tests, and grep execution endpoints. See Auto-heal when a run finishes. Response

{
  "runId": "9f2c7a4e-8b31-4d6a-a2f0-3c5e1b7d9a42",
  "name": "job-name-12345",
  "sharded": false
}

Use the returned runId value to poll for status (see Get run status by run ID). For non-sharded runs, name is the underlying job name. For sharded runs, name is null. curl example

curl -X POST https://api.checksum.ai/public-api/v1/execution/suite \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"autoHeal": {"autoCreatePR": true, "branch": "main", "repoName": "acme-co/my-tests"}}'

Sharding options

Execution endpoints accept optional sharding fields to run larger suites in parallel and report one final Checksum result.

Field	Type	Description
`shardCount`	integer	Number of parallel shards. Omit it, or set `1`, for a non-sharded run. Set `2` through `40` to run in parallel. Each shard runs one Playwright worker, so total parallelism scales with `shardCount`.

Use sharding when a suite is too slow as a single run and you want faster CI feedback.

Prerequisite — update checksumai first. After all shards finish, Checksum combines their results using the checksumai version installed on the branch you run against. If that version is too old to support sharded report merging, the shards still run but their results are never combined, and the run never returns a final verdict. Before enabling sharding, update checksumai on your tests branch to a recent release (for example npm install checksumai@latest), commit it, and re-run. If you’re unsure which version you need, use the latest stable release or contact Checksum support.

API-triggered runs can’t currently be cancelled through the public API. Cancelling your CI job only stops your workflow from checking status — the Checksum run continues until it finishes. Plan concurrency settings accordingly: GitHub Actions’ cancel-in-progress, for example, cancels your workflow, not the run on Checksum.

Sharding composes with autoHeal. Once the shards are merged, a merged run that ends failed is healed exactly as a non-sharded run would be, and a lost shard does not stop the surviving shards’ failures from being healed. If the shards never merge (see the checksumai prerequisite above), the autoHeal request is never evaluated.

Run a collection

POST /public-api/v1/execution/collection/:id

Runs every test that belongs to the specified collection.

Path parameter	Description
`id`	The collection ID

Run specific tests

POST /public-api/v1/execution/tests

Runs a hand-picked set of tests. Request body

{
  "testIds": ["id1", "id2"]
}

Optional autoHeal block — same shape as Run all tests.

Run tests by grep pattern

POST /public-api/v2/execution/grep

Runs all tests whose name matches a grep pattern. Use the v2 base URL for this endpoint:

https://api.checksum.ai/public-api/v2/

Request body

{
  "grep": "checkout",
  "branch": "feature/preview",
  "envOverrides": { "BASE_URL": "https://pr-42.preview.example.com" },
  "shardCount": 8
}

Field	Description
`grep`	Substring or regex matched against test names (required)
`branch`	Branch of your tests repository to check out for this test run (optional)
`envOverrides`	Per-run environment variables (optional; grep only on v2)
`shardCount`	Number of parallel shards (`2` through `40` for sharded runs; optional). Each shard runs one Playwright worker
`autoHeal`	Opt into heal-on-failure — same shape as Run all tests; composes with `shardCount` (see Sharding options). `autoHeal.branch` is the branch in your tests repository where Checksum should open the heal PR, not the run checkout branch

A legacy POST /public-api/v1/execution/grep endpoint exists with a smaller body (grep only). New integrations should use v2.

envOverrides is for your own application variables only (for example BASE_URL). Names reserved by Checksum — including CI and any key starting with CHECKSUM_ — are rejected with 400.

For pull-request checks, use POST /public-api/v2/execution/grep with branch, envOverrides, and sharding fields:

curl -X POST https://api.checksum.ai/public-api/v2/execution/grep \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "grep": "@smoke",
    "branch": "feature/checkout-preview",
    "envOverrides": {
      "BASE_URL": "https://pr-42.preview.example.com"
    },
    "shardCount": 8
  }'

Poll the returned runId with Get run status by run ID, then pass the CI check only when verdict is "pass".

Get run status by run ID

GET /public-api/v1/execution/status/run/:runId

Returns the server-computed status of a run by the runId returned from an execution endpoint. This status endpoint works for both non-sharded and sharded runs.

Path parameter	Description
`runId`	The `runId` value returned when the run was triggered

For CI checks, poll until isTerminal is true, then pass the check only when verdict is "pass". Gate on verdict rather than the passed/failed counts: Checksum computes verdict only after a sharded run has fully combined its results, and treats an empty test selection as a failure. Response — while running

{
  "status": "running",
  "isTerminal": false,
  "verdict": "pending",
  "phase": "sharding",
  "executedCount": 0,
  "sharded": true,
  "shardTotal": 8,
  "passed": 0,
  "failed": 0,
  "recovered": 0,
  "bug": 0,
  "failureReason": null
}

Response — when complete

{
  "status": "passed",
  "isTerminal": true,
  "verdict": "pass",
  "phase": "complete",
  "executedCount": 47,
  "sharded": true,
  "shardTotal": 8,
  "passed": 45,
  "failed": 0,
  "recovered": 2,
  "bug": 0,
  "failureReason": null
}

Field	Description
`status`	Current run state (e.g. `queued`, `running`, `passed`, `failed`). Use `verdict` for CI gating, not `status` alone — a `passed` status with `executedCount: 0` still returns `verdict: "fail"`
`isTerminal`	`true` when the run has reached a final state
`verdict`	CI-friendly result: `pass`, `fail`, or `pending`
`phase`	Progress stage for the run: `running`, `sharding`, `merging`, `complete`, or `failed`. For information only — gate on `isTerminal` and `verdict`, not `phase`
`executedCount`	Number of tests that actually ran. An empty selection returns `verdict: "fail"`
`passed` / `failed`	Count of tests that passed / failed
`recovered`	Tests that failed and then passed on auto-heal or retry
`bug`	Tests Checksum flagged as likely product bugs
`sharded`	Whether the run used sharding
`shardTotal`	Number of shards, or `1` for a non-sharded run
`failureReason`	Details when a run fails for infrastructure reasons, when available

curl example

curl https://api.checksum.ai/public-api/v1/execution/status/run/<RUN_ID> \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Get test run status by job name

GET /public-api/v1/execution/status/:jobName

Returns the current status of a non-sharded test run by job name. Prefer Get run status by run ID for new integrations and for all sharded runs.

Path parameter	Description
`jobName`	The `name` value returned when the run was triggered

For runs started via v2 grep, prefer:

GET /public-api/v2/execution/status/:jobName

The v2 response includes testRunId (UUID) when the run has reached a terminal state — use that value for POST /auto-heal, not jobName. Response — while running

{
  "status": "running"
}

Response — when complete (v1)

{
  "status": "passed",
  "passed": 45,
  "failed": 2,
  "recovered": 1,
  "bug": 0
}

Response — when complete (v2)

{
  "testRunId": "00000000-0000-0000-0000-000000000000",
  "status": "passed",
  "passed": 45,
  "failed": 2,
  "recovered": 1,
  "bug": 0
}

Possible status values

Status	Meaning
`queued`	The run is waiting to start
`running`	Tests are currently executing
`passed`	All tests passed (or were recovered)
`healed`	Tests passed after auto-healing was applied
`failed`	One or more tests failed
`process-error`	The run encountered an infrastructure error
`cancelled`	The run was cancelled

curl example

curl https://api.checksum.ai/public-api/v1/execution/status/job-name-12345 \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Test Results

Get latest test run

GET /public-api/v1/test-runs/latest

Returns the latest completed non-manual run for the project. Use the returned id with the result, report, attachment, and auto-heal endpoints. Response

{
  "id": "run-id",
  "status": "failed",
  "branch": "main"
}

Get detailed results

GET /public-api/v1/test-runs/:id/results

Returns detailed, per-test results for a completed run.

Path parameter	Description
`id`	The test run ID

Query parameter	Required	Description
`status`	No	Filter results by test status (e.g. `failed`)

Response

{
  "id": "run-id",
  "status": "failed",
  "branch": "main",
  "passed": 45,
  "failed": 2,
  "recovered": 1,
  "bug": 0,
  "tests": [
    {
      "checksumTestId": "test-abc-123",
      "testTitle": "User can add item to cart",
      "testFilePath": "checksum/tests/cart.spec.ts",
      "status": "passed",
      "errorMessage": null,
      "healthStatus": "healthy",
      "tags": ["smoke", "cart"]
    },
    {
      "checksumTestId": "test-def-456",
      "testTitle": "User can complete checkout",
      "testFilePath": "checksum/tests/checkout.spec.ts",
      "status": "failed",
      "errorMessage": "Timeout waiting for selector #pay-button",
      "healthStatus": "flaky",
      "tags": ["checkout"]
    }
  ]
}

Get HTML report

GET /public-api/v1/test-runs/:id/report

Returns a URL to the full HTML report for the run.

Path parameter	Description
`id`	The test run ID

Get test attachments

GET /public-api/v1/test-runs/:runId/tests/:testId/attachments

Returns attachments for a specific test within a run, including traces, screenshots, and videos.

Path parameter	Description
`runId`	The test run ID
`testId`	The individual test ID

Submit report verdicts

POST /public-api/v1/test-runs/:testRunId/report/verdicts

Submits human or automation verdicts for tests in a run report, then updates the run counts.

Path parameter	Description
`testRunId`	The test run ID

Request body

{
  "verdicts": [
    {
      "testId": "test-def-456",
      "verdict": "bug",
      "annotation": "Checkout returns 500 when payment method is missing"
    }
  ]
}

Field	Required	Description
`verdicts[].testId`	Yes	Test ID from the run report
`verdicts[].verdict`	Yes	One of `bug`, `recovered`, `healing`, or `triage`
`verdicts[].annotation`	Yes	Note explaining the verdict

Response

{
  "updated": 1,
  "stats": {
    "passed": 45,
    "failed": 1,
    "healed": 0,
    "bug": 1,
    "skipped": 0
  },
  "pendingVerdicts": []
}

Health Dashboard

The public REST API exposes read access to bug entities (GET /health-dashboard/bugs). Most manual bug-state changes happen in the Feature Health Dashboard in the web app. To submit verdicts directly against a run report, use POST /test-runs/:testRunId/report/verdicts.

List bugs

GET /public-api/v1/health-dashboard/bugs

Query parameter	Description
`status`	Filter by bug status (`needs-triage`, `confirmed`, `fixed`, `not-bug`, `snoozed`)
`severity`	Filter by `critical`, `major`, or `minor`
`search`	Search string
`limit`	Page size
`offset`	Pagination offset
`tags`	Filter by tags (repeatable)
`project`	Filter by project
`collectionName`	Filter by collection name

Test Generation (pull request)

Trigger generation for a PR

POST /public-api/v1/auto-generate

Starts a generation agent session that reads a pull request diff and opens a tests-repo PR when complete. Progress is posted as a sticky comment on the source PR. Request body

{
  "prNumber": 42,
  "repoName": "acme-co/webapp",
  "branch": "feature/checkout-redesign",
  "metadata": { "triggeredBy": "release-bot" },
  "envOverrides": {
    "BASE_URL": "https://preview.example.com/pr-42/"
  }
}

Field	Required	Description
`prNumber`	Yes	PR to associate with generation (sticky comments + agent context)
`repoName`	Yes	Repository hosting the PR, `<owner>/<repo>`
`branch`	Yes	PR head branch the agent should diff against
`metadata`	No	Arbitrary metadata forwarded to the agent
`envOverrides`	No	Per-session env overrides (e.g. preview URL) layered on project env

Response — 202 Accepted

{
  "batchId": "batch-abc",
  "sessionId": "sess-xyz",
  "links": { "session": "https://app.checksum.ai/..." }
}

Poll generation batch progress

GET /public-api/v1/auto-generate/batch/:batchId

Same response shape as Poll healing progress. See also Generate Tests and Git integration for /checksum generate on GitHub.

Auto-Healing

Trigger auto-healing

POST /public-api/v1/auto-heal

Starts an auto-healing session for failing tests in a run. Checksum will analyze the failures, attempt to fix the tests, and optionally open a pull request with the changes. Request body

{
  "testRunId": "run-id",
  "autoCreatePR": true,
  "branch": "main",
  "prNumber": 42,
  "repoName": "<owner>/<repo>",
  "metadata": { "context": "post-deploy healing" }
}

Field	Type	Required	Description
`testRunId`	string	Yes	The test run containing failures to heal
`autoCreatePR`	boolean	No	When `true`, Checksum opens a PR with the fixes (default: `true`)
`branch`	string	No	Branch in the tests repository that healing clones and targets the healed PR against (not a per-repo map). Defaults to the test run’s branch when omitted — set explicitly to your tests repo’s main branch when the run was triggered from app-code CI. See Where healing runs
`prNumber`	number	No	Associate healing with an existing pull request — progress is posted as comments on that PR
`repoName`	string	Conditional	`<owner>/<repo>` that hosts `prNumber` (for comment correlation). Required when `autoCreatePR` is `true` (the default) or when `prNumber` is set
`metadata`	object	No	Arbitrary key-value pairs included as context in the agent’s prompt

Response

{
  "batchId": "batch-xyz-789",
  "sessionIds": ["sess-1", "sess-2", "sess-3"],
  "failureCount": 3,
  "testIds": ["test-abc-123", "test-def-456", "test-ghi-789"]
}

curl example

curl -X POST https://api.checksum.ai/public-api/v1/auto-heal \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "testRunId": "run-id",
    "autoCreatePR": true,
    "branch": "main",
    "prNumber": 42,
    "repoName": "<owner>/<repo>"
  }'

Poll healing progress

GET /public-api/v1/auto-heal/batch/:batchId

Returns the current progress of a healing batch.

Path parameter	Description
`batchId`	The batch ID returned by the trigger endpoint

Response

{
  "batchId": "batch-xyz-789",
  "status": "in_progress",
  "testRunId": "run-id",
  "totalSessions": 3,
  "completedCount": 1,
  "failedCount": 0,
  "allTerminal": false,
  "sessions": [
    {
      "sessionId": "sess-1",
      "checksumTestId": "test-abc-123",
      "status": "completed",
      "prUrl": "https://github.com/org/repo/pull/42"
    },
    {
      "sessionId": "sess-2",
      "checksumTestId": "test-def-456",
      "status": "running",
      "prUrl": null
    },
    {
      "sessionId": "sess-3",
      "checksumTestId": "test-ghi-789",
      "status": "running",
      "prUrl": null
    }
  ]
}

Batch status values

Status	Meaning
`pending`	Healing has not started yet
`in_progress`	One or more sessions are still running
`completed`	All sessions finished successfully
`failed`	One or more sessions failed

Poll this endpoint until allTerminal is true to know that every session has finished.

Quick-Start Example

The following script triggers a full suite run with auto-heal on failure, then polls until it finishes. When the run fails, Checksum starts healing automatically — no separate heal call is required.

#!/usr/bin/env bash
set -euo pipefail

API_KEY="<YOUR_API_KEY>"
BASE="https://api.checksum.ai/public-api/v1"
TESTS_REPO="acme-co/my-tests"
TESTS_BRANCH="main"

# 1. Start a full suite run (opt into heal-on-failure)
RUN_ID=$(curl -s -X POST "$BASE/execution/suite" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg repo "$TESTS_REPO" \
    --arg branch "$TESTS_BRANCH" \
    '{autoHeal: {autoCreatePR: true, repoName: $repo, branch: $branch}}')" \
  | jq -r '.runId')

echo "Started run: $RUN_ID"

# 2. Poll until the run finishes
while true; do
  RESULT=$(curl -s "$BASE/execution/status/run/$RUN_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  TERMINAL=$(echo "$RESULT" | jq -r '.isTerminal')

  echo "Status: $STATUS"
  if [[ "$TERMINAL" == "true" ]]; then
    break
  fi
  sleep 10
done

VERDICT=$(echo "$RESULT" | jq -r '.verdict')
if [[ "$VERDICT" == "pass" ]]; then
  echo "All tests passed."
else
  echo "Run did not pass (verdict: $VERDICT) — auto-heal was dispatched with the run."
fi

To heal a run that already finished without autoHeal, call POST /auto-heal with testRunId set to the run’s UUID (the runId returned by the execution endpoint, or the id from GET /public-api/v1/test-runs/latest), not the dispatch name.

​Authentication

​Typical Flow

​Project Info

​Get project info

​Test Selection

​Get affected tests

​Execution

​Run all tests

​Sharding options

​Run a collection

​Run specific tests

​Run tests by grep pattern

​Get run status by run ID

​Get test run status by job name

​Test Results

​Get latest test run

​Get detailed results

​Get HTML report

​Get test attachments

​Submit report verdicts

​Health Dashboard

​List bugs

​Test Generation (pull request)

​Trigger generation for a PR

​Poll generation batch progress

​Auto-Healing

​Trigger auto-healing

​Poll healing progress

​Quick-Start Example

Authentication

Typical Flow

Project Info

Get project info

Test Selection

Get affected tests

Execution

Run all tests

Sharding options

Run a collection

Run specific tests

Run tests by grep pattern

Get run status by run ID

Get test run status by job name

Test Results

Get latest test run

Get detailed results

Get HTML report

Get test attachments

Submit report verdicts

Health Dashboard

List bugs

Test Generation (pull request)

Trigger generation for a PR

Poll generation batch progress

Auto-Healing

Trigger auto-healing

Poll healing progress

Quick-Start Example