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.
All paths below are relative to /api (canonical) or /v1 (alias — both work identically).
Health
File: app/api/routers/health.py
These endpoints don't require authentication. Use them for load balancer health checks, smoke tests, and deployment verification.
| Method | Path | Description |
|---|---|---|
GET |
/healthz |
Liveness check. Returns 200 if the process is alive. |
GET |
/readyz |
Readiness check. Returns 200 when dependencies (Postgres, S3, SQS) are reachable. Returns 503 if any dependency is unavailable. |
Auth
File: app/api/routers/auth.py
| Method | Path | Description |
|---|---|---|
GET |
/auth/config |
Return the active auth provider and Cognito config. No auth required. Used by the frontend on startup. |
POST |
/auth/login |
Exchange credentials for access and refresh tokens. Body: {email, password}. Local dev only. |
POST |
/auth/refresh |
Exchange a refresh token for a new access token. Body: {refresh_token}. |
POST |
/auth/logout |
Invalidate the current session. |
GET |
/auth/me |
Return the current user's profile and groups. |
Users
File: app/api/routers/users.py
| Method | Path | Description |
|---|---|---|
POST |
/users/invitations |
Invite a user (Cognito admin operation). Requires operator or root role. |
API Keys
File: app/api/routers/api_keys.py
API keys are long-lived credentials for programmatic access (prefixed with vk_).
| Method | Path | Description |
|---|---|---|
GET |
/api-keys |
List all API keys for the current user. |
POST |
/api-keys |
Create a new API key. The key value is only returned once at creation time. |
POST |
/api-keys/:key_id/revoke |
Revoke and delete an API key. |
Projects
File: app/api/routers/projects.py
Projects are workspace containers. The project-level endpoints return rollup views across all repositories.
| Method | Path | Description |
|---|---|---|
POST |
/projects |
Create a new project. Body: {name, description}. |
GET |
/projects |
List all projects for the current user. |
GET |
/projects/:project_id |
Get a project by ID. |
PATCH |
/projects/:project_id |
Update project name or description. |
DELETE |
/projects/:project_id |
Delete a project. Returns 409 if repositories remain. |
GET |
/projects/:project_id/repositories |
List all repositories in this project. |
POST |
/projects/:project_id/repositories |
Add a repository (git URL). |
POST |
/projects/:project_id/repositories/github |
Add a repository from GitHub App. |
GET |
/projects/:project_id/scans |
List all scans across all repositories in this project. |
GET |
/projects/:project_id/findings |
List all findings across all repositories in this project. |
GET |
/projects/:project_id/findings-rollup |
Daily finding counts rollup for charting. |
GET |
/projects/:project_id/scan-activity |
Scan activity summary for the project. |
Repositories
File: app/api/routers/repositories.py
This is the largest router. It covers the full repository workflow including many legacy-compatible aliases.
Repository management
| Method | Path | Description |
|---|---|---|
POST |
/repositories |
Create a repository. |
POST |
/repositories/github |
Create a repository from GitHub App. |
POST |
/repositories/upload-zip |
Upload a zip archive and create a repository. |
POST |
/repositories/resolve-git-url |
Validate a git URL (check accessibility). |
GET |
/repositories |
List all repositories for the current user. |
GET |
/repositories/overview |
Repository overviews with scan/finding counts. |
GET |
/repositories/:repo_id |
Get repository details including ingest state. |
DELETE |
/repositories/:repo_id |
Delete a repository and all its scans and findings. |
Source and scope
| Method | Path | Description |
|---|---|---|
GET |
/repositories/:repo_id/tree |
List files in the repository snapshot. |
GET |
/repositories/:repo_id/source |
Read a specific file from the snapshot. |
POST |
/repositories/:repo_id/source/download-url |
Generate a presigned URL to download the source archive. |
PATCH |
/repositories/:repo_id/default-scope |
Set the default include-path scope for new scans. |
GET |
/repositories/:repo_id/special-threat-modeling |
Get the custom threat modeling configuration. |
PUT |
/repositories/:repo_id/special-threat-modeling |
Set a custom threat modeling configuration. |
Ingest control
| Method | Path | Description |
|---|---|---|
POST |
/repositories/:repo_id/cancel-ingest |
Cancel a running ingest job. |
POST |
/repositories/:repo_id/retry-ingest |
Retry a failed ingest job. |
Scans (via repository prefix)
| Method | Path | Description |
|---|---|---|
GET |
/repositories/:repo_id/scans |
List all scans for this repository. |
POST |
/repositories/:repo_id/scans |
Start a new scan. Body: optional scan configuration. Returns 202. |
GET |
/repositories/:repo_id/events |
List domain events for the repository's active scan. |
Findings (via repository prefix)
| Method | Path | Description |
|---|---|---|
GET |
/repositories/:repo_id/findings |
List all findings for this repository. |
GET |
/repositories/scans/:scan_id/findings |
List findings for a specific scan (alias). |
Scan detail (via repository prefix — aliases to /scans routes)
| Method | Path | Description |
|---|---|---|
GET |
/repositories/scans/:scan_id |
Scan detail (alias). |
GET |
/repositories/live |
Active scan live detail for current user. |
GET |
/repositories/live-usage |
Billing usage for currently running scan. |
GET |
/repositories/activity |
Activity feed across recent scans. |
GET |
/repositories/worker-components |
Worker component status for running scan. |
Scans
File: app/api/routers/scans.py
Canonical scan routes. Prefer these over the /repositories/ scan aliases for new integrations.
| Method | Path | Description |
|---|---|---|
POST |
/scans |
Create a scan. Body: {repository_id, options, include_paths, bug_classes, ...}. Returns 202. |
GET |
/scans/:scan_id/live |
Live scan detail including state, progress, and recent events. |
GET |
/scans/:scan_id/live-usage |
Billing usage for a running scan (tokens, cost). |
GET |
/scans/:scan_id/activity |
Activity feed for the scan (operator-readable). |
GET |
/scans/:scan_id/worker-components |
Per-component worker status for the scan. |
POST |
/scans/:scan_id/pause |
Pause a running scan between stages. |
POST |
/scans/:scan_id/resume |
Resume a paused scan. |
POST |
/scans/:scan_id/cancel |
Cancel a running or queued scan. |
POST |
/scans/:scan_id/retry |
Retry a failed scan. |
Findings
File: app/api/routers/findings.py
Canonical finding routes. Prefer these for new integrations.
| Method | Path | Description |
|---|---|---|
GET |
/findings/scans/:scan_id |
List all findings for a specific scan. Supports ?severity=, ?status= filters. |
GET |
/findings/scans/:scan_id/:finding_id |
Get a specific finding with full detail. |
POST |
/findings/scans/:scan_id/:finding_id/triage |
Update triage status. Body: {status: "confirmed"|"dismissed"|"triaging"|...}. |
POST |
/findings/scans/:scan_id/:finding_id/remove |
Mark a finding as removed / false positive. |
GET |
/findings/repositories/:repo_id |
All findings for a repository across all scans. |
GET |
/findings/projects/:project_id |
All findings across all repositories in a project. |
GET |
/findings/:finding_id |
Global finding lookup by ID. |
Artifacts
File: app/api/routers/artifacts.py
| Method | Path | Description |
|---|---|---|
GET |
/artifacts/scans/:scan_id |
List all artifacts for a scan. |
GET |
/artifacts/scans/:scan_id/debug |
List debug-only artifacts (operator access). |
GET |
/artifacts/scans/:scan_id/activity-log |
The structured activity log artifact content. |
GET |
/artifacts/scans/:scan_id/worker-components-log |
The worker components log artifact content. |
GET |
/artifacts/scans/:scan_id/generated-threat-model |
The generated threat model Markdown content. |
POST |
/artifacts/:artifact_id/download-url |
Generate a presigned S3 download URL for an artifact. |
Billing
File: app/api/routers/billing.py
| Method | Path | Description |
|---|---|---|
GET |
/billing/summary |
User billing summary (balance, usage, spend limit). |
GET |
/billing/config |
Billing configuration (enabled features, currency). |
GET |
/billing/transactions |
Ledger entries (charges and credits). |
GET |
/billing/promotions |
Active promotional entitlements for the user. |
POST |
/billing/promotions/redeem |
Redeem a promotional code. Body: {code}. |
GET |
/billing/promotions/applications |
Promotion code applications and usage history. |
GET |
/billing/spend-limit |
Get the user's current monthly spend limit. |
PUT |
/billing/spend-limit |
Update the monthly spend limit. |
GET |
/billing/auto-reload |
Get auto-reload configuration. |
PUT |
/billing/auto-reload |
Update auto-reload settings. |
POST |
/billing/top-ups/payment-intent |
Create a Stripe payment intent for a top-up. |
POST |
/billing/top-ups/payment-intent/:id/sync |
Sync status of an in-flight payment intent. |
POST |
/billing/payment-method/setup-intent |
Create a Stripe setup intent for saving a payment method. |
POST |
/billing/webhook |
Stripe webhook endpoint (receives payment events). |
POST |
/billing/policy/scan-eligibility |
Internal: check billing eligibility before scan creation. |
POST |
/billing/policy/scan-settlement |
Internal: settle billing after scan completion. |
GET |
/billing/admin/promotions/campaigns |
List all promotion campaigns (root only). |
POST |
/billing/admin/promotions/campaigns |
Create a promotion campaign (root only). |
GET/PATCH |
/billing/admin/promotions/campaigns/:id |
Get or update a campaign (root only). |
POST |
/billing/admin/promotions/campaigns/:id/codes |
Generate codes for a campaign (root only). |
POST |
/billing/admin/promotions/campaigns/:id/codes/assign-user |
Assign a code to a specific user (root only). |
GET |
/billing/admin/promotions/campaigns/:id/codes |
List codes for a campaign (root only). |
GET |
/billing/admin/promotions/campaigns/:id/activity |
Redemption activity for a campaign (root only). |
POST |
/billing/admin/promotions/codes/:code_id/revoke |
Revoke a promotion code (root only). |
GET |
/billing/admin/promotions/entitlements |
List all entitlements (root only). |
POST |
/billing/admin/promotions/entitlements/:id/revoke |
Revoke an entitlement (root only). |
GET |
/billing/admin/promotions/audit-events |
Audit log for promotion events (root only). |
GitHub
File: app/api/routers/github.py
| Method | Path | Description |
|---|---|---|
GET |
/github/install-url |
Get the GitHub App installation URL for the current user. |
POST |
/github/install-url |
Same via POST (for form submissions). |
POST |
/github/complete-installation |
Complete a GitHub App OAuth installation flow. |
GET |
/github/connections |
List GitHub App connections for the current user. |
DELETE |
/github/connections/:connection_id |
Remove a GitHub App connection. |
GET |
/github/connections/:connection_id/repositories |
List accessible repositories for a connection. |
GET |
/github/connections/:connection_id/branches |
List branches for a specific repository. |
GET |
/github/connections/:connection_id/pull-requests |
List open pull requests for a repository. |
Git Uploads
File: app/api/routers/git_upload.py
Git uploads allow programmatic code submission via git push.
| Method | Path | Description |
|---|---|---|
POST |
/git-uploads |
Create a temporary git remote. Returns a push URL. |
GET |
/git-uploads/:upload_id |
Check the status of a git upload. |
POST |
/git-uploads/:upload_id/mark-pushed |
Signal that the push is complete. |
POST |
/git-uploads/:upload_id/complete |
Finalize the upload and trigger ingest. |
Operations
File: app/api/routers/operations.py
These endpoints expose operational state. They require operator or root role.
| Method | Path | Description |
|---|---|---|
GET |
/ops/limits |
Return current quota settings. |
POST |
/ops/limits/evaluate |
Evaluate whether an operation would be within limits. |
POST |
/ops/workers/heartbeat |
Worker process heartbeat registration. |
GET |
/ops/workers |
Return worker heartbeat registry. |
POST |
/ops/cleanup |
Trigger cleanup of stale artifacts. |
POST |
/ops/maintenance |
Trigger maintenance tasks. |
Sessions (legacy)
File: app/api/routers/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 |
/sessions |
Create a new session. |
GET |
/sessions/:session_id/state |
Get session status. |
PUT |
/sessions/:session_id/archive/parts/:index |
Upload a part of a multipart archive. |
POST |
/sessions/:session_id/archive/complete |
Finalize the multipart archive upload. |
POST |
/sessions/:session_id/analyze |
Trigger analysis on the uploaded archive. Returns 202. |
GET |
/sessions/:session_id/events |
List session events. |