QA Lens Docs

API Reference

QA Lens exposes a FastAPI application. The same API powers the React UI.

API Docs Page

Start the server:

qalens serve --db ./qalens.db

Open Swagger UI:

http://127.0.0.1:8080/api/docs

Use /api/docs as the single interactive API reference page. It includes endpoint groups, request models, response models, and a browser-based "Try it out" workflow.

Authentication

Authentication depends on server configuration.

Local default:

  • No API authentication.
  • Intended for localhost use only.

Token auth:

export QALENS_AUTH_TOKEN="strong-random-token"
qalens serve --db ./qalens.db

Requests:

curl -H "Authorization: Bearer strong-random-token" \
  http://127.0.0.1:8080/api/runs

GitHub OAuth auth is browser-oriented. Settings endpoints require admin access when auth is enabled.

Endpoint Groups

Health and Auth

MethodPathPurpose
GET/api/healthServer health and version.
GET/api/auth/statusCurrent auth mode and session status.
POST/auth/logoutEnd browser session.

Runs and Test Data

MethodPathPurpose
GET/api/runsList runs.
GET/api/runs/{run_id}Get one run.
GET/api/runs/{run_id}/testsGet tests for a run.
GET/api/runs/{run_id}/incidentsGet incidents affecting a run.

Common query parameter:

project=ProjectName

Example:

curl "http://127.0.0.1:8080/api/runs?project=ShopNow"

Analysis

MethodPathPurpose
GET/api/stabilityStability snapshot and pass-rate health.
GET/api/stability/flakyFlaky test data.
GET/api/stability/trendsTrend direction and history.
GET/api/failure-groupsFailure clusters and grouped incidents.
GET/api/riskRisk-ranked tests.
GET/api/owner-statsOwner-level statistics.
GET/api/decision-summaryAction Brief, executive summary, trend intelligence, and fix-first actions.

Example:

curl "http://127.0.0.1:8080/api/decision-summary?project=ShopNow"
MethodPathPurpose
POST/api/failure-groups/{fingerprint}/bug-linksAttach an external bug link to a failure group.
DELETE/api/failure-groups/{fingerprint}/bug-links/{link_id}Remove a bug link.

Evidence

MethodPathPurpose
GET/api/evidence/test/{canonical_name}Evidence for a canonical test.
GET/api/evidence/run/{run_id}Evidence for a run.

Evidence endpoints are useful for chat result workspaces and drill-down panels.

Comparison

MethodPathPurpose
GET/api/compare/historyHistory data for a target.
POST/api/compare/customCustom comparison request.
GET/api/compare/runsCompare runs.
GET/api/compare/facetsAvailable compare facets.
POST/api/compare/ownersCompare owners.
POST/api/compare/suitesCompare suites.
GET/api/compare/breakdownBreakdown-style comparison.

Chat and LLM

MethodPathPurpose
POST/api/askAsk a natural-language question.
GET/api/llm/infoCurrent LLM provider and model info.

Example:

curl -X POST "http://127.0.0.1:8080/api/ask" \
  -H "Content-Type: application/json" \
  -d '{"question":"What broke in the latest run?","project":null}'

The chat API may return:

  • answer
  • sources
  • follow_ups
  • result
  • uiHints

When result is present, the UI can open a structured workspace.

Settings

MethodPathPurpose
GET/api/settingsRuntime paths, LLM config, artifacts, and security settings.
PATCH/api/settings/llmUpdate editable LLM settings.

Settings endpoints require admin access when authentication is enabled.

Reports and Export

MethodPathPurpose
GET/api/report/exportExport deterministic HTML, Markdown, or JSON report.

Example:

curl "http://127.0.0.1:8080/api/report/export?format=html" \
  -o qalens-report.html

Supported formats:

html
markdown
md
json

UI Support

MethodPathPurpose
GET/api/homepage-cardsSuggested questions/cards for the UI.

API Stability

QA Lens is currently beta software. The CLI and documented product behavior should be treated as more stable than internal UI API response shapes.

For integrations:

  • Prefer CLI commands for CI workflows.
  • Use /api/report/export for generated artifacts.
  • Use /api/docs to inspect current request and response schemas.
  • Pin a QA Lens version when building API clients.
View source on GitHub