REST API reference

Base URL and auth

All endpoints live under https://www.qlens.dev/api/v1/. Authenticate with an API key in the X-API-Key header:

curl https://www.qlens.dev/api/v1/auto-fix-metrics \
  -H "X-API-Key: qlens_..."

Create or rotate keys at /dashboard/keys (Pro+ plans). The plain key is shown once at creation; we only store the SHA-256 hash.

Rate limits

• 60 requests per rolling 60 seconds, per API key. Bursts above that return 429.
• Every response includes X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets).
• The ingest endpoint (POST /api/v1/test-runs) has a separate, higher limit suitable for CI.

Endpoints

Ingest a test run

POST /api/v1/test-runs — used by the official reporters. Documented separately on /docs/ci-ingest.

List auto-fixes

curl "https://www.qlens.dev/api/v1/auto-fixes?repo=owner/name&limit=20" \
  -H "X-API-Key: qlens_..."

Returns the recent auto-fix proposals for a repo — open / merged / rejected / skipped — plus confidence and PR URLs.

Get auto-fix metrics

curl "https://www.qlens.dev/api/v1/auto-fix-metrics?repo=owner/name" \
  -H "X-API-Key: qlens_..."

Aggregate counts over the last 30 days: proposals, opens, merges, average confidence, time-to-merge. The exact data the dashboard renders.

Errors

Standard JSON envelope on errors:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "invalid_api_key",
  "message": "API key not recognized or revoked."
}

Error codes you might see:

• 401 — missing or invalid X-API-Key.
• 403 — key valid but plan doesn't cover this endpoint (e.g. free plan calling a paid-only resource).
• 404 — repo not connected, or no data for the requested window.
• 429 — rate limit. Honour Retry-After.
• 5xx — retry with exponential backoff.

OpenAPI spec

Machine-readable schema: /api/v1/openapi.json. Drop it into Postman, Insomnia, or your client generator of choice.

Versioning

We version the API surface in the URL (/api/v1/). Breaking changes ship in a new version (/api/v2/) with at least 90 days of overlap. Additive, non-breaking changes ship under v1 without notice — adding a new field, a new endpoint, or a new query parameter.