Skip to main content
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

All endpoints registered after the auth middleware require a Bearer token when the server is started with the VIGOLIUM_API_KEY environment variable or server.auth_api_key config. This includes GET /, GET /health, GET /server-info, and all /api/* routes. 
curl -H "Authorization: Bearer my-secret-key" http://localhost:9002/api/stats
Public endpoints (no auth required): GET /swagger/*, GET /metrics.

​
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 / — App Info

Returns basic application metadata. 
curl -s http://localhost:9002/ | jq .

{
  "name": "vigolium",
  "version": "v0.0.1-alpha",
  "author": "@j3ssie",
  "docs": "https://docs.vigolium.io",
  "build_time": "2026-02-16T15: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.0.1-alpha",
  "author": "@j3ssie",
  "docs": "https://docs.vigolium.io",
  "build_time": "2026-02-16T15:22:43Z",
  "commit": "67bdce4",
  "uptime": "5m32s",
  "service_addr": "0.0.0.0:9002",
  "proxy_addr": "",
  "db_driver": "sqlite",
  "queue_depth": 0,
  "total_records": 1234,
  "total_findings": 42
}

​
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. No authentication required. Only available when the server is started with --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, OPTIONS. Allowed headers: Content-Type, Authorization.

​
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