Reference

API reference

REST endpoints for the dashboard. All review endpoints require a valid Supabase JWT in the Authorization header.

Base URL

https://your-backend.onrender.com

Authentication

Dashboard endpoints expect a Supabase access token in the Authorization header:

http
GET /reviews HTTP/1.1
Host: codexa-backend.onrender.com
Authorization: Bearer <supabase_access_token>

The token is verified server-side via Supabase JWKS (RS256/ES256) — falling back to HS256 if your project uses a shared JWT secret. Invalid or missing tokens return 401.

⚠️ Webhook auth is different

The /webhooks/github endpoint uses HMAC-SHA256 verified against GITHUB_WEBHOOK_SECRET — not Supabase JWT.

Health

GET/

Service liveness probe. Returns service name and status.

GET/healthz

Readiness probe with provider configuration flags.

Reviews

GET/reviews

List recent reviews scoped to the signed-in user. Query params: limit (1-200), repo, status (pending/completed/failed).

GET/reviews/{id}

Full review record including the findings JSON array. Returns 404 if the review isn't owned by the requesting user.

GET/reviews/repos

Distinct repository names the user has reviews for. Used to populate the dashboard filter dropdown.

GET/reviews/stats

Aggregate counters: total reviews, completed reviews, total findings, average duration.

Example response — GET /reviews/{id}

json
{
  "id": "9f3a4e21-...",
  "repo": "techymk/codexa-test",
  "pr_number": 12,
  "pr_url": "https://github.com/techymk/codexa-test/pull/12",
  "pr_title": "Add user lookup helpers",
  "installation_id": 127619686,
  "provider": "gemini-2.0-flash",
  "status": "completed",
  "summary": "Solid setup overall. Two issues to fix before merge.",
  "findings": [
    {
      "file": "auth/jwt.py",
      "line": 24,
      "severity": "error",
      "message": "App crashes silently if SECRET_KEY isn't set.",
      "suggestion": "Fail fast at startup with an explicit assertion."
    }
  ],
  "findings_count": 1,
  "duration_ms": 8123,
  "error": null,
  "created_at": "2026-04-28T20:31:14Z"
}

Settings

GET/settings/repos/{owner}/{repo}

Get per-repo settings. Returns defaults if no row exists.

PUT/settings/repos/{owner}/{repo}

Upsert per-repo settings. Body: skip_paths, min_severity, extra_prompt, enabled.

Settings request body

json
{
  "skip_paths": ["package-lock.json", "*.lock", "migrations/**"],
  "min_severity": "warn",
  "extra_prompt": "We use SQLAlchemy 2.x. Flag legacy Query API usage.",
  "enabled": true
}

Webhooks

POST/webhooks/github

GitHub webhook receiver. HMAC-verified. Processes pull_request events asynchronously.

Error responses

All errors return JSON with a detail field:

json
{ "detail": "missing bearer token" }

Status codes:

401 — missing or invalid JWT (dashboard); invalid HMAC (webhook)
403 — JWT valid but the resource isn't yours
404 — review/setting not found
500 — backend or Supabase error (check Render logs)