Vigolium API Reference, Overview

Base URL, authentication, project scoping, health checks, and common endpoints for the Vigolium API server.

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 server.enable_metrics config key (on by default; there is no CLI flag for it).

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.

PATCH was missing from the preflight allowlist before v0.4.2, so a browser client could never reach PATCH /api/findings/:id/status — i.e. could never mark a finding triaged.

---

Response Headers

Every response carries the server banner and its companion author header:

Server: Vigolium v0.4.5
X-Author: j3ssie

X-Vigolium-Bridge-Source additionally appears on /api/http-records when a Burp/Caido bridge answered, naming the vendor.

---

Request Body Limits

Request bodies are capped per route. Since v0.4.2 a chunked body is capped at limit + 1 bytes and drained before the 413 is returned, rather than being read to completion — previously a chunked upload could grow the heap to the framework’s 512 MB ceiling on a route whose own limit was 4 MB. --debug logging no longer buffers streamed uploads into memory on the large-upload routes either.

---

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, or a missing storage object)
409	Conflict (scan or agent already running)
413	Payload too large (per-route body limit exceeded)
500	Internal server error
503	Database not available

v0.4.2: storage downloads used to answer a missing object with a truncated stream instead of a JSON 404 — a client saw a short file, not an error. They now return the standard error shape, and the storage read endpoints are reachable in --view-only mode.