API Reference

The Vega backend exposes a REST API under /api. All endpoints accept and return JSON. Most endpoints require an Authorization: Bearer <token> header.

URL prefix

The canonical prefix is /api. The /v1 prefix is also accepted as a backwards-compatibility alias — all routes work under either prefix. Locally, both http://localhost:8000/api/... and http://localhost:8000/v1/... work identically.

Base URLs

Environment	Base URL
Local development	`http://localhost:8000/api`
Dev AWS	`https://api.dev.vega.example.com/api`
Prod AWS	`https://api.vega.example.com/api`

Authentication

Include the access token on every protected request:

Authorization: Bearer <access_token>

Get an access token by logging in:

curl -s http://localhost:8000/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"debug@example.com","password":"vega-debug-password"}'

The response contains access_token and refresh_token. In production with Cognito, the frontend handles token acquisition directly from Cognito — the /api/auth/login endpoint is only for local development.

Error format

All errors return a consistent JSON envelope regardless of the error type:

{
  "schema_version": 1,
  "error": {
    "code": "not_found",
    "message": "Repository abc123 not found",
    "retryable": false,
    "details": {}
  }
}

Use code for programmatic branching. Use message for display. Check retryable before retrying on 5xx errors.

Endpoint groups

Group	Path prefix	What it covers
Health	`/api/healthz`, `/api/readyz`	Liveness and readiness checks
Auth	`/api/auth/`	Login, refresh, logout, current user, auth config
Users	`/api/users/`	User invitations (Cognito)
API keys	`/api/api-keys/`	Programmatic API key management
Projects	`/api/projects/`	Workspace project CRUD and rollup views
Repositories	`/api/repositories/`	Repository workflow, source, scans, findings (large router)
Scans	`/api/scans/`	Canonical scan detail and control routes
Findings	`/api/findings/`	Canonical finding routes across scans/repos/projects
Artifacts	`/api/artifacts/`	Scan artifact listing and download
Billing	`/api/billing/`	Balance, transactions, promotions, Stripe payments
GitHub	`/api/github/`	GitHub App integration
Git uploads	`/api/git-uploads/`	Temporary git-push remotes
Operations	`/api/ops/`	Limits, workers, cleanup
Sessions (legacy)	`/api/sessions/`	Old upload/analyze flow

Quick examples

Check health:

curl -s http://localhost:8000/api/healthz

Get current user:

curl -s http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

List projects:

curl -s http://localhost:8000/api/projects \
  -H "Authorization: Bearer $ACCESS_TOKEN"

List findings for a scan:

curl -s http://localhost:8000/api/findings/scans/$SCAN_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"