You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page summarizes every REST endpoint exposed by OsWL. For interactive documentation with request/response schemas, use Swagger UI in the local profile (http://localhost:8080/swagger-ui.html). Swagger is disabled in prod.
Authentication
Session (Web UI)
Browser-based requests use Spring Security cookie sessions. Login via POST /login.
API Key (CLI)
CLI endpoints require:
Authorization: Bearer oswl_<api_key>
CLI Scan Submitter Credentials
POST /api/scan additionally requires submitterEmail and submitterPassword in the JSON body to authenticate the submitter. Successful ingests are recorded in the audit log (SCAN.INGEST) with the submitter email — not in a dedicated scan-result column.
Auth Endpoints
Method
Path
Description
GET
/login
Login page
POST
/login
Submit credentials
GET
/login/otp-verify
OTP verification page
POST
/login/otp-verify
Submit OTP code
POST
/login/otp-resend
Re-send OTP email
GET
/setup
Setup wizard page (first boot only)
POST
/setup
Submit setup wizard form
Projects
Method
Path
Permission
Description
GET
/projects
PROJECT_VIEW
Projects dashboard
GET
/projects/list
PROJECT_VIEW
Projects list (JSON)
DELETE
/projects/{id}
PROJECT_DELETE
Soft-delete project
POST
/projects/{id}/restore
PROJECT_RESTORE
Restore from trash
DELETE
/projects/{id}/permanent
PROJECT_PERMANENT_DELETE
Permanently delete
DELETE
/projects/trash/all
PROJECT_PERMANENT_DELETE
Empty trash
DELETE
/projects/trash/selected
PROJECT_PERMANENT_DELETE
Delete selected trash
POST
/projects/trash/restore-selected
PROJECT_RESTORE
Bulk restore
GET
/projects/cards
PROJECT_VIEW
Project card HTML fragment (dashboard)
GET
/projects/scan-status/stream?ids=
PROJECT_VIEW
SSE — scan-update when listed projects finish scanning
POST
/projects
PROJECT_CREATE
Create project (JSON)
PATCH
/api/projects/{id}/deployment-profile
PROJECT_UPDATE
Set AI deployment profile for CVE triage ({ "deploymentProfile" })
Quick Import
Requires PROJECT_CREATE (or System Admin). Session auth.
Method
Path
Description
GET
/projects/quick-import
Quick Import page
GET
/api/quick-import/connections
List VCS connections for the current user
GET
/api/quick-import/repos?provider=
List repositories from a provider (GITHUB, GITLAB, BITBUCKET)
POST
/api/quick-import/start
Enqueue a new import job ({ "repoUrl", "branch" } → { "jobId" })
POST
/api/quick-import/job/{jobId}/cancel
Cancel a queued or running job (404 when unknown or already finished)
GET
/api/quick-import/jobs
List all jobs for the current user (queued, running, recent)
GET
/api/quick-import/job/{jobId}
Poll one job (QuickImportJobStatus)
GET
/api/quick-import/job/{jobId}/stream
SSE — event job-update with JSON status (fallback: poll)
Job phases:QUEUED → CLONING → PARSING → SCANNING → ENRICHING → DONE | FAILED.
Up to two imports run concurrently (oswl.quick-import.max-concurrent); additional jobs wait in a FIFO queue (queuePosition).
During ENRICHING, responses include percent, subPhase (CVE, LICENSE, POSTURE, TREND, DIFF), detailLines, and aiPreviews.
GitHub OAuth / PAT
Method
Path
Description
POST
/api/github/connect
Connect a GitHub PAT
DELETE
/api/github/disconnect
Remove GitHub connection
GET
/api/github/status
Connection status
GET
/api/github/accounts
List authenticated accounts
GET
/api/github/repos
List accessible repositories
GET
/api/github/branches
List branches for a repo
GET
/api/github/branches/by-project
List branches for a project's linked repo (?projectId= — used by the Apply Patch modal)
GET
/api/github/branch-updated-at
Last commit date for a branch
DELETE
/api/github/accounts/{login}
Remove a specific account
CLI Scan
Method
Path
Auth
Description
POST
/api/auth
API key
Validate API key (legacy)
GET
/api/scan/ping
API key
Connectivity and key validity check
GET
/api/scan/manifest-rules
API key
Manifest file collection rules (same as /scripts/manifest-rules.json)
POST
/api/scan/parse
API key
Parse a manifest zip archive (CLI step 1)
POST
/api/scan
API key + credentials
Submit a dependency scan (CLI step 2)
GET
/api/scan/{scanId}/status
Session
Poll scan status
Security Center
Method
Path
Permission
Description
GET
/projects/{id}/security-center
SECURITY_CENTER_VIEW
Security Center page
PATCH
/projects/{id}/security-center/bulk-status
SECURITY_CENTER_UPDATE_STATUS
Bulk CVE status update
GET
/projects/{id}/security-center/export
SECURITY_CENTER_EXPORT
Download the CVE list as CSV (?scanId=, ?format=csv)
Active provider + enrichment preferences (temperature, limits, deployment default, …)
PUT
/api/settings/ai
SETTINGS_AI_MANAGE
Upsert provider credentials and/or preferences
PUT
/api/settings/ai/deactivate
SETTINGS_AI_MANAGE
Deactivate active provider (optional preference body)
PUT
/api/settings/ai/activate/{provider}
SETTINGS_AI_MANAGE
Switch active provider
POST
/api/settings/ai/test-connection
SETTINGS_AI_MANAGE
Test provider connectivity (no persist)
GET
/api/settings/ai/prompts
SETTINGS_AI_MANAGE
Editable prompt templates + overrides
POST
/api/settings/ai/golden-test
SETTINGS_AI_MANAGE
Run built-in prompt regression fixtures
GET
/api/settings/ai/usage
SETTINGS_AI_MANAGE
AI usage stats — today's calls/tokens/estimated cost, daily cap, and the last 7 days, read from the daily aggregate table
GET
/api/settings/ai/usage/events
SETTINGS_AI_MANAGE
Recent AI call events, newest first (?page=, ?size=, default size 10). Only the last 100 events are retained (FIFO), so at most 10 pages exist
GET
/api/settings/ai/embedded
SETTINGS_AI_MANAGE
Embedded AI status (running, external, binaryFound, activeModel, fallbackUsed, lastError, availableModels, modelsDir, baseUrl, and while a default-model download is in flight: downloading, downloadedBytes, downloadTotalBytes)
POST
/api/settings/ai/embedded/start?model=
SETTINGS_AI_MANAGE
Start the llama.cpp sidecar (optional model file name; auto-fallback across candidates, 400 with reason on failure). On a fresh install with no .gguf present, downloads the Apache-2.0 Qwen3-1.7B model in the background instead and returns immediately (downloading: true) — poll GET .../embedded for progress
POST
/api/settings/ai/embedded/stop
SETTINGS_AI_MANAGE
Stop the sidecar and deactivate the LOCAL provider
PUT
/api/settings/ai/embedded/config
SETTINGS_AI_MANAGE
Save folder/model overrides { "dir", "model" } (null keeps current, blank clears; 400 if dir missing)
Providers: OPENAI, ANTHROPIC, GEMINI, LOCAL. The embedded endpoints manage the built-in llama.cpp LOCAL provider — see Embedded AI.
License Policy
Method
Path
Permission
Description
GET
/api/settings/license-policy
LICENSE_POLICY_MANAGE
List SPDX policy entries
PUT
/api/settings/license-policy/{spdxId}
LICENSE_POLICY_MANAGE
Update status for one license
VCS Connections
Method
Path
Permission
Description
GET
/api/settings/vcs
SETTINGS_VCS_MANAGE
List connections
POST
/api/settings/vcs
SETTINGS_VCS_MANAGE
Add connection
DELETE
/api/settings/vcs/{id}
SETTINGS_VCS_MANAGE
Remove connection
Cache (enrichment policy)
Controls how long library CVE/license data from deps.dev and OSV is reused between scans.
Method
Path
Permission
Description
GET
/api/settings/cache
SETTINGS_CACHE_MANAGE
List cache keys (DEPS_DEV, OSV_VULN) with TTL and last-cleared metadata
PUT
/api/settings/cache
SETTINGS_CACHE_MANAGE
Update TTL for one key (cacheKey, ttlSeconds)
POST
/api/settings/cache/clear?cacheKey=…
SETTINGS_CACHE_MANAGE
Mark cache cleared — libraries fetched before that time are re-fetched on the next enrichment
TTL semantics (Settings → Cache UI maps to DEPS_DEV TTL used by enrichment):
UI mode
ttlSeconds
Behaviour
Always Refresh
1
Re-fetch every library on every scan
Custom TTL
N (seconds)
Re-fetch when libraries.fetched_at is older than N
Permanent Cache
very large (e.g. 50 years)
Fetch each library only once
Note: The former /api/settings/external endpoints and external_api_settings table were removed. Cache is managed solely via /api/settings/cache.