Endpoint Groups
This page lists all API endpoints grouped by domain. For full request/response schemas, see the interactive OpenAPI docs at http://localhost:8000/docs when the backend is running.
Health
File: app/api/health.py
These endpoints don't require authentication. Use them for load balancer health checks, smoke tests, and deployment verification.
| Method | Path | Description |
|---|---|---|
GET |
/v1/healthz |
Liveness check. Returns 200 if the process is alive. |
GET |
/v1/readyz |
Readiness check. Returns 200 when dependencies (Postgres, S3, SQS) are reachable. Returns 503 if any dependency is unavailable. |
Auth
File: app/api/auth.py
| Method | Path | Description |
|---|---|---|
POST |
/v1/auth/login |
Exchange credentials for access and refresh tokens. Body: {email, password}. |
POST |
/v1/auth/refresh |
Exchange a refresh token for a new access token. Body: {refresh_token}. |
POST |
/v1/auth/logout |
Invalidate the current session. |
GET |
/v1/auth/me |
Return the current user's profile. Good for testing that a token is valid. |
API Keys
File: app/api/api_keys.py
API keys are long-lived credentials for programmatic access. They work exactly like Bearer tokens.
| Method | Path | Description |
|---|---|---|
GET |
/v1/api-keys/ |
List all API keys for the current user. |
POST |
/v1/api-keys/ |
Create a new API key. The key value is only returned once at creation time. |
DELETE |
/v1/api-keys/:key_id |
Revoke and delete an API key. |
Projects
File: app/api/projects.py
Projects are workspace containers. The project-level endpoints return rollup views across all repositories.
| Method | Path | Description |
|---|---|---|
GET |
/v1/projects/ |
List all projects for the current user. |
POST |
/v1/projects/ |
Create a new project. Body: {name, description}. |
GET |
/v1/projects/:project_id |
Get a project by ID, including repository count and scan rollup. |
PUT |
/v1/projects/:project_id |
Update project name or description. |
DELETE |
/v1/projects/:project_id |
Delete a project and all its repositories, scans, and findings. |
GET |
/v1/projects/:project_id/scans |
List all scans across all repositories in this project. |
GET |
/v1/projects/:project_id/findings |
List all findings across all repositories in this project. |
GET |
/v1/projects/:project_id/events |
List all events across all scans in this project. |
Repositories
File: app/api/repositories.py
This is the most feature-rich group. It covers the full repository workflow from adding source code to reviewing findings.
Repository management
| Method | Path | Description |
|---|---|---|
GET |
/v1/repositories/:repo_id |
Get repository details including ingest status. |
PUT |
/v1/repositories/:repo_id |
Update repository metadata. |
DELETE |
/v1/repositories/:repo_id |
Delete a repository and all its scans and findings. |
POST |
/v1/projects/:project_id/repositories |
Add a repository to a project. Body: {name, source_type, source_url} or include upload. |
GET |
/v1/projects/:project_id/repositories |
List all repositories in a project. |
Source and threat profile
| Method | Path | Description |
|---|---|---|
GET |
/v1/repositories/:repo_id/source-tree |
List files in the repository snapshot. |
GET |
/v1/repositories/:repo_id/source-files/:path |
Read a specific file from the snapshot. |
GET |
/v1/repositories/:repo_id/threat-profile |
Get the current threat profile. |
PUT |
/v1/repositories/:repo_id/threat-profile |
Create or update the threat profile. |
Scans
| Method | Path | Description |
|---|---|---|
GET |
/v1/repositories/:repo_id/scans |
List all scans for this repository. |
POST |
/v1/repositories/:repo_id/scans |
Start a new scan. Body: optional scan configuration. |
GET |
/v1/repositories/:repo_id/scans/:scan_id |
Get scan details including status and artifact references. |
DELETE |
/v1/repositories/:repo_id/scans/:scan_id |
Cancel a running or queued scan. |
Events
| Method | Path | Description |
|---|---|---|
GET |
/v1/repositories/:repo_id/scans/:scan_id/events |
List events for a specific scan. Poll this for live progress. |
Findings
| Method | Path | Description |
|---|---|---|
GET |
/v1/repositories/:repo_id/findings |
List all findings for this repository. Supports ?severity=, ?status=, ?scan_id= filters. |
GET |
/v1/repositories/:repo_id/findings/:finding_id |
Get a specific finding with full detail. |
PUT |
/v1/repositories/:repo_id/findings/:finding_id |
Update finding status (open, confirmed, dismissed). |
Git Uploads
File: app/api/git_upload.py
Git uploads allow programmatic code submission via git push rather than a URL or file upload.
| Method | Path | Description |
|---|---|---|
POST |
/v1/git-uploads/ |
Create a temporary git remote. Returns a URL to push to. |
GET |
/v1/git-uploads/:upload_id |
Check the status of a git upload. |
DELETE |
/v1/git-uploads/:upload_id |
Delete a git upload remote. |
Billing
File: app/api/billing.py
| Method | Path | Description |
|---|---|---|
GET |
/v1/billing/summary |
Return usage summary and cost breakdown. |
Operations
File: app/api/hardening.py
These endpoints expose operational state. They require elevated group membership.
| Method | Path | Description |
|---|---|---|
GET |
/v1/ops/limits |
Return current quota settings. |
GET |
/v1/ops/workers |
Return worker heartbeat registry. |
POST |
/v1/ops/cleanup |
Trigger cleanup of stale artifacts. |
Sessions (legacy)
File: app/api/sessions.py
Legacy path
The sessions API is the older upload/analyze workflow. New code should use the project/repository flow above. These endpoints are preserved for backward compatibility.
| Method | Path | Description |
|---|---|---|
POST |
/v1/sessions/ |
Create a new session with an uploaded archive. |
GET |
/v1/sessions/:session_id |
Get session status. |
POST |
/v1/sessions/:session_id/analyze |
Trigger analysis on the uploaded archive. |
GET |
/v1/sessions/:session_id/events |
List session events. |