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.

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

{
  "name": "job-name-12345"
}

Use the returned name value to poll for status (see Get test run status). 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"}}'

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" },
  "autoHeal": {
    "autoCreatePR": true,
    "branch": "main",
    "repoName": "acme-co/my-tests",
    "prNumber": 42
  }
}

Field	Description
`grep`	Substring or regex matched against test names (required)
`branch`	Branch checked out for this test run in the customer repo (optional)
`envOverrides`	Per-run environment variables (optional; grep only on v2)
`autoHeal`	Opt into heal-on-failure — same shape as Run all tests. `autoHeal.branch` is the tests-repo branch for 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.

Get test run status

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

Polls the current status of a test run started from v1 execution endpoints.

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 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

Health Dashboard

The public REST API exposes read access to bug entities (GET /health-dashboard/bugs). Marking tests as bugs or clean is done in the Feature Health Dashboard in the web app — those write operations are not on the public API surface.

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.

Project Info

Get project info

GET /public-api/v1/me

Returns basic information about the project associated with the API key. Response

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

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)
JOB_NAME=$(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 '.name')

echo "Started run: $JOB_NAME"

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

  echo "Status: $STATUS"
  if [[ "$STATUS" != "running" && "$STATUS" != "queued" ]]; then
    break
  fi
  sleep 10
done

FAILED=$(echo "$RESULT" | jq '.failed // 0')
if [[ "$FAILED" -gt 0 ]]; then
  echo "$FAILED test(s) failed — auto-heal was dispatched with the run."
else
  echo "All tests passed."
fi

To heal a run that already finished without autoHeal, call POST /auto-heal with testRunId set to the run’s UUID (from GET /public-api/v2/execution/status/:jobName for v2 grep runs, or GET /public-api/v1/test-runs/latest), not the dispatch jobName.

​Authentication

​Execution

​Run all tests

​Run a collection

​Run specific tests

​Run tests by grep pattern

​Get test run status

​Test Results

​Get detailed results

​Get HTML report

​Get test attachments

​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

​Project Info

​Get project info

​Quick-Start Example

Authentication

Execution

Run all tests

Run a collection

Run specific tests

Run tests by grep pattern

Get test run status

Test Results

Get detailed results

Get HTML report

Get test attachments

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

Project Info

Get project info

Quick-Start Example