API reference

Start runs from CI or scripts, follow them and read the findings. Every instance serves this description at /api/v1/openapi.json (OpenAPI 3.1): feed it to your client generator. For GitHub Actions use qaitai/action@v1, for other CI qaitai run --instance.

Authentication

Create a workspace API key in Settings → API keys (admins only) and send it as a bearer token:

curl "$QAITAI_INSTANCE/api/v1/runs?limit=5" -H "Authorization: Bearer $QAITAI_API_KEY"

• A key belongs to one workspace and only ever sees that workspace's data. Keys are shown once and stored as SHA-256 hashes.
• Each operation needs one scope (listed below). A key without it gets 403; a missing, unknown or revoked key gets 401.
• Runs started with a key are ordinary runs: the same domain verification, plan concurrency, allowance, spend caps and BYOK rules as in the app. They show api_key:<id> as their creator and in the audit log.
• The API is for servers and CI: responses carry no CORS headers, so browsers on other sites can't call it with your key.

Conventions

• Errors are JSON: { "error": { "code": "run_rejected", "message": "…", "reason": "domain_unverified" } }. message is safe to show; issues lists field problems for invalid_request.
• Lists are newest first. Pass limit (1–100, default 20) and the previous page's nextCursor as cursor; nextCursor is null on the last page.
• Idempotency: send Idempotency-Key on POST /runs and POST /suites/{suiteId}/run. A retry with the same key within 24 hours returns the first run (200, Idempotent-Replayed: true) instead of starting and billing another; the same key with a different request is 409.
• Rate limits per key and minute: Free 60, Pro 300, Team 600, Enterprise and self-hosted 1,200 (self-hosters can set QAITAI_API_RATE_LIMIT). Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; 429 comes with Retry-After. Limits are counted per web replica.

Scopes

Runs

Start, follow and cancel runs.

Start a run

POST /api/v1/runs · scope runs:write

Same checks as starting a run in the app: the project must be in the key's workspace, cloud runs on qaitai Cloud need a verified domain, and plan concurrency, allowance and spend caps apply. Policy refusals are 422 run_rejected with a reason.

Body (application/json):

Response 201: Run. The queued run. 200 when an Idempotency-Key replay returns an earlier run.

Errors: 400, 401, 403, 404, 409, 422, 429.

curl -X POST "$QAITAI_INSTANCE/api/v1/runs" \
  -H "Authorization: Bearer $QAITAI_API_KEY" \
  -H "Idempotency-Key: $GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://staging.acme.dev","prompt":"Sign up, create a project and invite a teammate"}'

List runs

GET /api/v1/runs · scope runs:read

Response 200: RunPage. Newest first.

Errors: 400, 401, 403, 429.

curl "$QAITAI_INSTANCE/api/v1/runs" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Get a run

GET /api/v1/runs/{runId} · scope runs:read

The run with its workers and findings. Poll this or stream /events until status is terminal.

Response 200: RunDetail. The run.

Errors: 401, 403, 404, 429.

curl "$QAITAI_INSTANCE/api/v1/runs/<runId>" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Cancel a run

POST /api/v1/runs/{runId}/cancel · scope runs:write

Response 200: Run. The cancelled run.

Errors: 401, 403, 404, 409, 429.

curl -X POST "$QAITAI_INSTANCE/api/v1/runs/<runId>/cancel" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Stream run events (SSE)

GET /api/v1/runs/{runId}/events · scope runs:read

Server-sent events until the run finishes: run {id, status, startedAt, finishedAt} on change, worker {id, label, status, startedAt, finishedAt} on change, step {id, runWorkerId, index, kind, summary, at} (the SSE id is its timestamp), issue {id, severity, title, stepId, createdAt}, then end {}. The server closes the stream after 10 minutes; reconnect with Last-Event-ID to resume without repeating steps.

Response 200: text/event-stream. An event stream.

Errors: 401, 403, 404, 429.

curl -N "$QAITAI_INSTANCE/api/v1/runs/<runId>/events" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Suites

Saved journeys you can run on demand or on a schedule.

List suites

GET /api/v1/suites · scope suites:read

Response 200: SuitePage. Newest first.

Errors: 400, 401, 403, 429.

curl "$QAITAI_INSTANCE/api/v1/suites" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Create a suite

POST /api/v1/suites · scope suites:write

Body (application/json):

Response 201: Suite. The suite.

Errors: 400, 401, 403, 404, 429.

curl -X POST "$QAITAI_INSTANCE/api/v1/suites" \
  -H "Authorization: Bearer $QAITAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<projectId>","name":"<name>","prompt":"Sign up, create a project and invite a teammate"}'

Get a suite

GET /api/v1/suites/{suiteId} · scope suites:read

Response 200: Suite. The suite.

Errors: 401, 403, 404, 429.

curl "$QAITAI_INSTANCE/api/v1/suites/<suiteId>" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Run a suite

POST /api/v1/suites/{suiteId}/run · scope runs:write

Starts the suite now, against url or the project's app URL: a replay when the suite is compiled, else an exploratory run. Needs runs:write because it starts a run.

Body (application/json):

Response 201: Run. The queued run.

Errors: 400, 401, 403, 404, 409, 422, 429.

curl -X POST "$QAITAI_INSTANCE/api/v1/suites/<suiteId>/run" \
  -H "Authorization: Bearer $QAITAI_API_KEY" \
  -H "Idempotency-Key: $GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" \
  -H "Content-Type: application/json" \
  -d '{}'

Issues

Findings reported by workers.

List issues

GET /api/v1/issues · scope issues:read

Response 200: IssuePage. Newest first.

Errors: 400, 401, 403, 429.

curl "$QAITAI_INSTANCE/api/v1/issues" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Get an issue

GET /api/v1/issues/{issueId} · scope issues:read

Response 200: Issue. The issue.

Errors: 401, 403, 404, 429.

curl "$QAITAI_INSTANCE/api/v1/issues/<issueId>" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Projects

Apps under test.

List projects

GET /api/v1/projects · scope projects:read

Response 200: ProjectPage. Newest first.

Errors: 400, 401, 403, 429.

curl "$QAITAI_INSTANCE/api/v1/projects" \
  -H "Authorization: Bearer $QAITAI_API_KEY"

Schemas

Error

ErrorCode

"invalid_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "run_rejected" | "payload_too_large" | "rate_limited" | "internal_error" | "unavailable"

Run

RunStatus

"queued" | "running" | "passed" | "failed" | "flaky" | "cancelled" | "errored"

CreateRunRequest

RunPage

RunDetail

Worker

IssueSummary

Severity

"critical" | "high" | "medium" | "low"

SuitePage

Suite

CreateSuiteRequest

RunSuiteRequest

IssuePage

Issue

ProjectPage

Project