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.

An unknown X-Project-UUID returns 404 as of v0.5.3. It used to create the project on the spot, so a typo in a header quietly started a second, empty engagement that every subsequent request then wrote into — and the caller saw a healthy 200 with no data. Create projects explicitly with POST /api/projects.

---

Response Versions

Added in v0.5.3. Every response carries a Vigolium-Api-Version header naming the body shape it used, and a client picks one with any of (first match wins):

1. ?api_version=2 (or 1)
2. Vigolium-Api-Version: 2 request header
3. Accept: application/vnd.vigolium.v2+json (or …v1+json)

Without one, the server uses server.api_version_default — 1 in this release, so nothing changes for an existing client until it opts in. An unknown version is 400 unsupported_api_version. Server-sent event streams are never wrapped.

v1 is the historical shape, extended only additively. The paginated lists (/api/findings, /api/http-records, /api/scans, /api/oast-interactions, /api/agent/sessions) gain schema_version and command; other list endpoints keep their own shapes.

{"schema_version": 1, "command": "finding", "project_uuid": "...",
 "data": [ ... ], "total": 150, "limit": 50, "offset": 0, "has_more": true}

v2 is the CLI’s -j envelope — the same document vigolium finding -j prints, so one parser serves both surfaces. Every list endpoint answers it, including /api/modules, /api/extensions, /api/projects, /api/config and /api/db/tables/…:

{"schema_version": 2, "command": "finding", "kind": "read", "ok": true,
 "route": "GET /api/findings", "project_uuid": "...", "project_scoped": true,
 "total": 150, "offset": 0, "limit": 50, "has_more": true,
 "items": [ ... ], "generated_at": "2026-10-10T08:00:00.000Z",
 "generated_at_ms": 1791590400000}

v1 errors gained error_code in the same release, drawn from the same closed vocabulary the CLI uses (vigolium schema error), and unknown routes now return JSON rather than an HTML 404 — so a client never has to parse markup to find out it called the wrong path.

---

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": "127.0.0.1:9002",
  "proxy_addr": "",
  "queue_depth": 0,
  "total_records": 1234,
  "total_findings": 42,
  "license_spdx": "MIT",
  "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.