Vigolium API Reference, Overview - Vigolium Documentation

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:

Value	Behavior
`*`	Allow all origins
`reflect-origin`	Reflect the request’s `Origin` header (allows credentials)
`origin1,origin2`	Allow 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:

Code	Meaning
400	Bad request (invalid JSON, missing fields)
401	Unauthorized (missing or invalid Bearer token)
404	Not found (e.g. agent run ID not found)
409	Conflict (scan or agent already running)
500	Internal server error
503	Database not available

​Starting the Server

​Authentication

​Project Scoping

​GET /api/info, App Info

​GET /health, Health Check

​GET /server-info, Server Info

​GET /swagger/*, Swagger UI

​GET /metrics, Prometheus Metrics

​CORS

​Error Responses