Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt

Use this file to discover all available pages before exploring further.

Base URL: http://localhost:9002 (default)

​
Starting the Server

# No authentication (development)
vigolium server -A

# With API key
export VIGOLIUM_API_KEY="my-secret-key"
vigolium server -A

# Custom host/port
vigolium server -A --host 127.0.0.1 --service-port 8080

​
Authentication

/api/* routes require a Bearer token when the server is started with VIGOLIUM_API_KEY or server.auth_api_key set. 
curl -H "Authorization: Bearer my-secret-key" http://localhost:9002/api/stats
Public endpoints (no auth required): GET /, GET /health, GET /server-info, GET /swagger/*, GET /metrics, and POST /api/auth/login. Demo-only and view-only modes (cfg.DemoOnly / cfg.ViewOnly) further gate mutating routes; admin/operator/viewer roles enforced by RoleGuard middleware override the per-route checks.

​
Project Scoping

All API operations are scoped to a project via the X-Project-UUID request header. If the header is omitted, the default project (00000000-0000-0000-0000-000000000001) is used. 
# Scope requests to a specific project
curl -H "Authorization: Bearer my-secret-key" \
     -H "X-Project-UUID: a1b2c3d4-..." \
     http://localhost:9002/api/findings
This applies to all data endpoints: ingestion, findings, HTTP records, stats, scans, source repos, and OAST interactions. See Projects for the full multi-tenancy reference.

​
GET /api/info, App Info

Returns basic application metadata. (GET / serves the embedded static UI, not JSON.) 
curl -s http://localhost:9002/api/info | jq .

{
  "name": "vigolium",
  "version": "v0.1.8-alpha",
  "author": "vigolium",
  "docs": "https://docs.vigolium.com",
  "build_time": "2026-05-21T15:22:43Z",
  "commit": "67bdce4"
}

​
GET /health, Health Check

Returns server health status. 
curl -s http://localhost:9002/health | jq .

{
  "status": "healthy",
  "timestamp": "2026-02-16T15:30:00Z"
}

​
GET /server-info, Server Info

Returns detailed server information including uptime, database driver, queue depth, and record/finding totals. 
curl -s http://localhost:9002/server-info | jq .

{
  "name": "vigolium",
  "version": "v0.1.8-alpha",
  "author": "vigolium",
  "docs": "https://docs.vigolium.com",
  "build_time": "2026-05-21T15:22:43Z",
  "commit": "67bdce4",
  "uptime": "5m32s",
  "service_addr": "0.0.0.0:9002",
  "proxy_addr": "",
  "queue_depth": 0,
  "total_records": 1234,
  "total_findings": 42,
  "license_spdx": "AGPL-3.0",
  "source": "https://github.com/vigolium/vigolium"
}

​
GET /swagger/*, Swagger UI

Interactive API documentation. Open in a browser. 
http://localhost:9002/swagger/
The raw OpenAPI 3.0 spec is available at: 
curl -s http://localhost:9002/swagger/doc.json | jq .info

​
GET /metrics, Prometheus Metrics

Returns Prometheus-formatted metrics. The route is always registered and unauthenticated; the handler gates the response on the EnableMetrics server flag (CLI --enable-metrics / config server.enable_metrics). 
curl -s http://localhost:9002/metrics

​
CORS

CORS can be enabled via the cors_allowed_origins server config:
ValueBehavior
*Allow all origins
reflect-originReflect the request’s Origin header (allows credentials)
origin1,origin2Allow specific origins (comma-separated, allows credentials)
(empty/omitted)CORS disabled
Allowed methods: GET, POST, PUT, DELETE, PATCH, OPTIONS. Allowed headers: Content-Type, Authorization, X-Project-UUID, X-User-Email.

​
Error Responses

All errors follow a consistent format: 
{
  "error": "error message",
  "code": 400,
  "details": "optional additional details"
}
Common error codes:
CodeMeaning
400Bad request (invalid JSON, missing fields)
401Unauthorized (missing or invalid Bearer token)
404Not found (e.g. agent run ID not found)
409Conflict (scan or agent already running)
500Internal server error
503Database not available