Skip to main content

​
What is Server Mode

Vigolium can run as a persistent REST API server, accepting traffic ingestion, scan triggers, and agent runs via HTTP endpoints. Server mode is useful for team workflows where multiple users share a scanning backend, CI/CD integration where automated pipelines submit traffic and retrieve findings, and building custom tooling on top of Vigolium’s API.

​
Starting the Server

# Start with an API key
export VIGOLIUM_API_KEY=my-secret-key
vigolium server

# Custom host and port
export VIGOLIUM_API_KEY=my-secret-key
vigolium server --host 127.0.0.1 --service-port 9002

# With an upstream proxy for outgoing scanner traffic
export VIGOLIUM_API_KEY=my-secret-key
vigolium server --proxy http://corporate-proxy:8080

# Without authentication (development only)
vigolium server -A
The server listens on 0.0.0.0:9002 by default.

​
Authentication

All API requests except the public meta endpoints (/, /health, /metrics, /server-info, /swagger/*, and POST /api/auth/login) require a Bearer token: 
Authorization: Bearer my-secret-key
API key resolution order: VIGOLIUM_API_KEY env var > server.auth_api_key in config file (~/.vigolium/vigolium-configs.yaml).

​
CORS Configuration

The server’s CORS behavior is controlled by cors_allowed_origins in ~/.vigolium/vigolium-configs.yaml: 
server:
  cors_allowed_origins: reflect-origin
ValueBehavior
reflect-origin (default)Echoes the requesting Origin header back. Allows credentials.
*Allows all origins without credentials (standard wildcard).
(empty string)Disables CORS middleware entirely.
https://app.example.com, https://admin.example.comComma-separated allowlist. Allows credentials.

​
Project Scoping

All server operations are scoped to a project via the X-Project-UUID request header. If omitted, the default project is used. 
curl -X POST http://localhost:9002/api/ingest-http \
  -H "Authorization: Bearer my-secret-key" \
  -H "X-Project-UUID: a1b2c3d4-..." \
  -H "Content-Type: application/json" \
  -d '{"input_mode": "url", "content": "https://example.com"}'
All queries (findings, HTTP records, stats, scans) return data scoped to the project specified in the header. See Projects for the full multi-tenancy reference.

​
API Endpoint Overview

A condensed view — see the API References index for the full surface.
MethodPathDescription
GET/Static UI (no auth required)
GET/healthHealth check (no auth required)
GET/metricsPrometheus metrics (no auth required)
GET/swagger/*Swagger UI and OpenAPI spec (no auth required)
GET/server-infoServer status (no auth required)
POST/api/auth/loginFile-based login → bearer token
GET/api/infoApp info / build metadata
GET/api/user/infoCurrent user
GET/api/projectsList projects
GET/api/modulesList available scanner modules
GET/api/http-recordsQuery stored HTTP records
GET/api/findingsQuery scan findings
PATCH/api/findings/:id/statusUpdate finding status (open/triaged/closed)
POST/api/ingest-httpIngest HTTP traffic into the database
POST/api/importBulk import scans/records/findings
GET/api/statsAggregated scan statistics
GET/api/oast-interactionsList OAST callbacks
GET, POST/api/scopeView/update scope configuration
GET, POST/api/configView/update server configuration
POST/api/scans/runTrigger a background scan
POST/api/scan-urlScan a single URL
POST/api/scan-requestScan a single raw request
POST/api/scan-recordsScan specific record UUIDs
POST/api/scan-all-recordsScan filtered records
GET/api/scansList scans
GET/api/scans/:uuidScan status
GET/api/scans/:uuid/logsScan logs (SSE supported)
POST/api/scans/:uuid/stopCancel a running scan
POST/api/scans/:uuid/pausePause a scan
POST/api/scans/:uuid/resumeResume a scan
POST/api/scans/:uuid/updateAdjust scan parameters mid-run
GET/api/scan/statusLatest scan status (legacy/global)
POST/api/agent/run/querySingle-shot agent prompt execution
POST/api/agent/run/autopilotAutonomous AI-driven scanning session
POST/api/agent/run/swarmAI-guided multi-phase vulnerability scan
POST/api/agent/run/auditAudit/piolium driver dispatcher (driver: auto|both|audit|piolium)
GET/api/agent/status/listList agent runs
GET/api/agent/status/:idGet agent run status (includes full result when completed)
GET/api/agent/sessionsPaginated session history
GET/api/agent/sessions/:id/logsTail or read runtime.log (SSE supported)
GET/api/agent/sessions/:id/artifacts[/:filename]Browse / fetch agent session artifacts
POST/api/agent/chat/completionsOpenAI-compatible chat completions
POST/api/storage/upload-sourceUpload source archive to cloud storage
POST/api/storage/presignPre-signed upload/download URLs
GET/api/storage/source/:keyDownload a stored source archive
GET/api/diagnosticsSystem readiness check
GET/api/db/tablesList database tables
GET, POST/api/db/tables/:name/recordsGeneric table browser (read / queries)
GET/api/extensionsList loaded extensions
PUT, POST/api/extensions/:nameUpload / enable extension

​
Scan Management via API

After ingesting HTTP records, trigger a vulnerability scan via the API.

​
Trigger a Scan

curl -s -X POST http://localhost:9002/api/scans/run \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .
Force re-scan with specific modules: 
curl -s -X POST http://localhost:9002/api/scans/run \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "force": true,
    "enable_modules": ["xss-scanner", "sqli-error-based"]
  }' | jq .
Returns 202 Accepted with a scan_uuid on success, 409 Conflict if a scan is already running.

​
Check Scan Status

# Latest scan, legacy/global endpoint
curl -s http://localhost:9002/api/scan/status \
  -H "Authorization: Bearer my-secret-key" | jq .

# Specific scan
curl -s http://localhost:9002/api/scans/SCAN-UUID \
  -H "Authorization: Bearer my-secret-key" | jq .

​
Cancel a Running Scan

curl -s -X POST http://localhost:9002/api/scans/SCAN-UUID/stop \
  -H "Authorization: Bearer my-secret-key" | jq .
See the API Reference for full request/response details.

​
Running AI Agents via API

The server exposes agent endpoints that mirror the vigolium agent CLI subcommands (query, autopilot, swarm, audit). The audit dispatcher accepts driver: "auto"|"both"|"audit"|"piolium" to drive the embedded vigolium-audit harness and/or piolium. Concurrency is bounded by a global heavy/light semaphore plus a per-project heavy cap; new heavy runs return 409 Conflict when the cap is reached. Set "stream": true for real-time SSE output (multi-driver audit streams add a driver field per chunk). For full details on agent modes, prompt templates, and API request/response schemas, see the Agent Mode documentation and the Agent API Reference.