API Reference

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

Base URLs

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

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/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"debug@example.com","password":"vega-debug-password"}'

The response contains access_token and refresh_token.

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	`/v1/healthz`, `/v1/readyz`	Liveness and readiness checks
Auth	`/v1/auth/`	Login, refresh, logout, current user
API keys	`/v1/api-keys/`	Programmatic API key management
Projects	`/v1/projects/`	Workspace project CRUD and rollup views
Repositories	`/v1/repositories/`	Repositories, scans, findings, events
Git uploads	`/v1/git-uploads/`	Temporary git-push remotes
Billing	`/v1/billing/`	Usage and cost summaries
Operations	`/v1/ops/`	Limits, worker state, cleanup
Sessions (legacy)	`/v1/sessions/`	Old upload/analyze flow

Quick examples

Check health:

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

Get current user:

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

List projects:

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