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

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

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

Run tests by grep pattern

POST /public-api/v1/execution/grep

Runs all tests whose name matches a grep pattern. Request body

{
  "grep": "pattern"
}

Get test run status

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

Polls the current status of a test run.

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

Response — while running

{
  "status": "running"
}

Response — when complete

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

Mark a test as a bug

POST /public-api/v1/health-dashboard/mark-bug

Flags a test as a known bug so it is tracked on the Health Dashboard. Request body

{
  "checksumTestId": "test-abc-123",
  "description": "Button is unresponsive after latest deploy",
  "severity": "critical"
}

Field	Required	Description
`checksumTestId`	Yes	The test to flag
`description`	Yes	A short description of the bug
`severity`	Yes	One of `critical`, `major`, or `minor`

Clear bug status

POST /public-api/v1/health-dashboard/mark-clean

Removes the bug flag from a test. Request body

{
  "checksumTestId": "test-abc-123"
}

Bulk mark as bugs

POST /public-api/v1/health-dashboard/bulk-mark-bug

Marks multiple tests as bugs in a single request (up to 500 tests). Request body

{
  "tests": [
    {
      "checksumTestId": "test-abc-123",
      "description": "Login button broken",
      "severity": "critical"
    },
    {
      "checksumTestId": "test-def-456",
      "description": "Minor layout shift",
      "severity": "minor"
    }
  ]
}

Bulk clear bug status

POST /public-api/v1/health-dashboard/bulk-mark-clean

Removes the bug flag from multiple tests in a single request. Request body

{
  "checksumTestIds": ["test-abc-123", "test-def-456"]
}

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,
  "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	The target branch for the PR
`prNumber`	number	No	Associate healing with an existing pull request
`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
  }'

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, waits for it to finish, and kicks off auto-healing if any tests fail:

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

API_KEY="<YOUR_API_KEY>"
BASE="https://api.checksum.ai/public-api/v1"

# 1. Start a full suite run
JOB_NAME=$(curl -s -X POST "$BASE/execution/suite" \
  -H "Authorization: Bearer $API_KEY" | 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

# 3. If there are failures, trigger auto-healing
FAILED=$(echo "$RESULT" | jq '.failed')
if [[ "$FAILED" -gt 0 ]]; then
  echo "$FAILED test(s) failed — triggering auto-heal..."
  curl -s -X POST "$BASE/auto-heal" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"testRunId\": \"$JOB_NAME\", \"autoCreatePR\": true, \"branch\": \"main\"}"
fi

API

​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

​Mark a test as a bug

​Clear bug status

​Bulk mark as bugs

​Bulk clear bug status

​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

Mark a test as a bug

Clear bug status

Bulk mark as bugs

Bulk clear bug status

Auto-Healing

Trigger auto-healing

Poll healing progress

Project Info

Get project info

Quick-Start Example