API Keys & Authentication

At a glance

Using	How you authenticate	Learn more
REST API	Send your key in an `Authorization: Bearer` header	Making requests
CLI and CI	Store the key as `CHECKSUM_API_KEY`	Your API key
Coding agents (MCP)	Sign in through your browser, or use the key	MCP clients

Reference for AI: authentication at a glance

Interface	How it authenticates
REST API	`Authorization: Bearer $CHECKSUM_API_KEY` on every request
CLI	`npx checksumai dotenv --download --api-key=$CHECKSUM_API_KEY`, plus `apiKey: process.env.CHECKSUM_API_KEY` in `checksum.config.ts`
CI	CI secret named `CHECKSUM_API_KEY`
GitHub Action	`api-key: ${{ secrets.CHECKSUM_API_KEY }}`
MCP	Browser sign-in (recommended) or `Authorization: Bearer $CHECKSUM_API_KEY`
Key check	`GET https://api.checksum.ai/public-api/v1/me`

Where the key lives: web app → Settings → Project Settings. One key per project, created by Checksum during onboarding.
Base URLs: https://api.checksum.ai/public-api/v1/ for almost everything; https://api.checksum.ai/public-api/v2/ for POST /execution/grep and GET /execution/status/{jobName}.
Async: execution returns a runId (poll until isTerminal is true); generation and healing return a batchId (poll until allTerminal is true).
Validation: invalid bodies return 400; a missing or invalid key returns 401.
No cancel: API-triggered runs can’t be cancelled through the API.

Developer guide

Your API key, making requests, checking a key, and the typical integration flow

Your API key

Your project’s API key is in the web app under Settings → Project Settings. Checksum creates it with your project during onboarding, so you don’t need to generate one. Store it as the environment variable CHECKSUM_API_KEY wherever you use it: your shell, your CI secrets, or your coding agent’s config.

# Local shell: export the key once per session
export CHECKSUM_API_KEY="<your project API key>"

# CLI: download the project's environment variables into .env
npx checksumai dotenv --download --api-key="$CHECKSUM_API_KEY"

In CI, add it as a secret named CHECKSUM_API_KEY (see CI/CD Integration). The GitHub Action takes it as api-key: ${{ secrets.CHECKSUM_API_KEY }}, and your tests read it through apiKey: process.env.CHECKSUM_API_KEY in checksum.config.ts.

Keep it secretThe key is unique to your project. Anyone who has it can run tests, start billable agent sessions, open pull requests, and read results for the project. Keep it in a secrets manager or CI secret, and never commit it. A key is always tied to exactly one project.

Reference for AI: where the API key is used

Used by	How
CLI	`npx checksumai dotenv --download --api-key=<KEY>`, and `apiKey: process.env.CHECKSUM_API_KEY` in `checksum.config.ts`
CI	Stored as a CI secret named `CHECKSUM_API_KEY`
GitHub Action	`api-key: ${{ secrets.CHECKSUM_API_KEY }}`
REST API	`Authorization: Bearer <KEY>` header
MCP (optional)	As a bearer header for clients that can’t do browser sign-in (see MCP clients)

Scope: one key per project. Location: Settings → Project Settings. Environment variable name: CHECKSUM_API_KEY.

Making requests

Every call to the REST API sends your key in an Authorization: Bearer header, and requests with a body send JSON. Calls that start agent work (runs, generation, healing) return right away with an ID, and you poll for the result. The examples in these docs poll every 10–30 seconds.

# Template for every Checksum REST call
curl -X POST https://api.checksum.ai/public-api/v1/<endpoint> \
  -H "Authorization: Bearer $CHECKSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Base URL and versions

Almost everything lives under the v1 base URL. Two endpoints also have a v2 with more options. For running tests by name pattern, use v2.

v1 base URL

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

v2 base URL

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

Reference for AI: request conventions and API versions

Convention	Rule
Auth	Every request includes `Authorization: Bearer <YOUR_API_KEY>`.
Bodies	JSON, with `Content-Type: application/json`.
Async work	Endpoints that start agent work return right away with an ID to poll. Execution returns a `runId`. Generation (`202 Accepted`) and healing return a `batchId`.
Polling	Poll runs until `isTerminal` is `true`, and poll batches until `allTerminal` is `true`. Recommended interval 10–30 seconds.
Validation errors	Invalid bodies return `400`. For example, reserved `envOverrides` keys, or a `shardCount` above 40 (rejected, not capped).

Capability	v1	v2	Use
Run tests by name pattern	`POST /v1/execution/grep`, legacy (`grep` only)	`POST /v2/execution/grep` with `branch`, `envOverrides`, `shardCount`, `autoHeal`	v2
Status by job name	`GET /v1/execution/status/:jobName`	`GET /v2/execution/status/:jobName` adds `testRunId` when terminal	Prefer `/v1/execution/status/run/:runId` for everything new
Everything else	`/v1/…`	n/a	v1

Check that your key works

Before wiring up runs, call GET /me. It’s a lightweight check that returns the project your key belongs to, and whether a tests repository is connected.

GEThttps://api.checksum.ai/public-api/v1/me

curl https://api.checksum.ai/public-api/v1/me \
  -H "Authorization: Bearer $CHECKSUM_API_KEY"

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

If you get 401, the key is missing, malformed, or has been rotated. Once this call works, you’re ready to start a run.

Reference for AI: GET /me

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

Returns basic information about the project the API key belongs to. Use it as a lightweight auth check before triggering runs.

Header	Value
`Authorization`	`Bearer $CHECKSUM_API_KEY`

Response field (200)	Type	Description
`id`	string	Project ID
`name`	string	Project name
`hasTestsRepo`	boolean	Whether a tests repository is connected. Generation and healing PRs require one.

Error	Cause	Fix
`401`	Missing, malformed, or rotated key	Send exactly `Authorization: Bearer $CHECKSUM_API_KEY`, with no stray whitespace or quotes from your secret store

Next: trigger a run with an execution endpoint (Running Tests → execution endpoints).

A typical integration

Most integrations follow the same path: check the key, pick tests, start a run, wait for the verdict, read the details, and heal what broke.

Confirm the key

Call GET /public-api/v1/me.

Choose tests (optional)

POST /public-api/v1/affected-tests with your changed files returns the test IDs most likely affected. See Selecting tests.

Trigger a run

Run the suite, a collection, specific tests, or a grep pattern. Add autoHeal to heal failures automatically. See Execution endpoints.

Poll the run

GET /public-api/v1/execution/status/run/{runId} until isTerminal, then gate on verdict. See Run status.

Read the details

Per-test results, HTML report, and attachments. See Results API.

Heal

Include autoHeal at step 3, or call POST /public-api/v1/auto-heal afterward with the run’s UUID. See Trigger healing.

On GitHub Actions?checksum-ai/test-run-action wraps steps 2–6 in a single step, including verdict gating and auto-heal.

Which ID goes where

The most common mistake is passing the wrong ID. Use the run’s UUID (runId) for status, results, and healing. The job name only works with the legacy status endpoint.

Reference for AI: which ID goes where

You have	Pass it to
`runId` (UUID) from an execution call	`/execution/status/run/:runId`, `/test-runs/:id/*`, and `POST /auto-heal` as `testRunId`
`name` (job name, non-sharded runs only)	Legacy `/execution/status/:jobName` only, never to `/auto-heal`
`batchId` from generate or heal	`/auto-generate/batch/:batchId` or `/auto-heal/batch/:batchId`
`checksumTestId`	`POST /execution/tests` (`testIds`), attachments, verdicts

The full table, with where each ID comes from, is in Key Concepts → IDs you’ll meet.

Current limitations

Runs can’t be cancelled via the APICancelling your CI job only stops your workflow from polling. The Checksum run keeps going until it finishes. Plan concurrency settings with this in mind: GitHub Actions’ cancel-in-progress, for example, cancels your workflow, not the run on Checksum.

A few other things to know: envOverrides rejects reserved variable names, the API can read bug entities but not change their status, and sharded runs need a recent checksumai.

Reference for AI: API limitations

Limitation	Details
No cancel	API-triggered runs can’t be cancelled through the public API. Cancelling the CI job stops polling only.
Reserved variables	`envOverrides` rejects `CI` and any key starting with `CHECKSUM_` with `400`.
Bug state is read-only	The API can list bug entities but not change their status. Use the Feature Health Dashboard, or submit per-run verdicts.
Sharding	2–40 shards per run. Requires `checksumai` 4.4.0 or later on the tests branch (see Sharding limits).

Authenticating MCP clients

The Checksum MCP server (https://api.checksum.ai/public-api/mcp) supports two sign-in methods. On your own machine, use browser sign-in: you approve the connection while logged in to app.checksum.ai, choose which projects the client may use, and no key is stored. For CI, containers, or clients that only accept a static token, send your API key as a bearer header instead. Browser-sign-in connections belong to you, not the project. Review or revoke them from the MCP connections card on My Profile. An API key is always scoped to one project. Setup per client is on Coding Agents & MCP.

Reference for AI: MCP authentication

Method	How	Use when
Browser sign-in (recommended)	OAuth approval in your browser while logged in to app.checksum.ai. You choose which projects the client may use. No key is stored.	Claude Code, Cursor, VS Code, and Claude web/desktop on your own machine
API key	`Authorization: Bearer <YOUR_API_KEY>` header in the client config	CI, containers, or clients that only support static tokens

Server URL: https://api.checksum.ai/public-api/mcp. Browser connections are per user and revocable from My Profile → MCP connections. API keys are per project.

Troubleshooting

Every call returns 401 Unauthorized

Check that the header is exactly Authorization: Bearer <key>, that there is no stray whitespace or quoting from your secret store, and that the key hasn’t been rotated. Call GET /me to test the key on its own.

GET /me returns hasTestsRepo: false

No tests repository is connected, so generation and healing can’t open PRs. See Git Integration or contact your Checksum team.

My grep run ignores branch or envOverrides

Those fields are only supported on the v2 grep endpoint. Check that you’re calling /public-api/v2/execution/grep.

Running Tests

Execution and status endpoints.

Key Concepts

Outcomes, verdicts, and IDs.

Start Here

Managing Your Project

Test Generation

Test Execution

Maintenance & Monitoring

Integrations

Security & Admin

API Keys & Authentication

At a glance

Your API key

Making requests

Base URL and versions

Check that your key works

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

A typical integration

Which ID goes where

Current limitations

Authenticating MCP clients

Troubleshooting

Running Tests

Key Concepts

​At a glance

​Your API key

​Making requests

​Base URL and versions

​Check that your key works

​GET https://api.checksum.ai/public-api/v1/me

​A typical integration

​Which ID goes where

​Current limitations

​Authenticating MCP clients

​Troubleshooting

​Related

Running Tests

Key Concepts

At a glance

Your API key

Making requests

Base URL and versions

Check that your key works

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

A typical integration

Which ID goes where

Current limitations

Authenticating MCP clients

Troubleshooting

Related