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 /health) 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

MethodPathDescription
GET/App info (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, queue depth, record/finding counts
GET/api/modulesList available scanner modules
GET/api/http-recordsQuery stored HTTP records
GET/api/findingsQuery scan findings
POST/api/ingest-httpIngest HTTP traffic into the database
GET/api/statsAggregated scan statistics
GET/api/scopeView scope configuration
POST/api/scopeUpdate scope configuration
GET/api/configView server configuration
POST/api/configUpdate server configuration
POST/api/scanTrigger a background scan
GET/api/scan/statusCheck scan status
DELETE/api/scanCancel a running scan
GET/api/source-reposList source repos
POST/api/source-reposCreate a source repo
GET/api/source-repos/:idGet a source repo
PUT/api/source-repos/:idUpdate a source repo
DELETE/api/source-repos/:idDelete a source repo
POST/api/agent/run/querySingle-shot agent prompt execution
POST/api/agent/run/autopilotAutonomous AI-driven scanning session
POST/api/agent/run/pipelineMulti-phase scanning pipeline
GET/api/agent/status/listList agent runs
GET/api/agent/status/:idGet agent run status (includes full result when completed)

​
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/scan \
  -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/scan \
  -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 on success, 409 Conflict if a scan is already running.

​
Check Scan Status

curl -s http://localhost:9002/api/scan/status \
  -H "Authorization: Bearer my-secret-key" | jq .

​
Cancel a Running Scan

curl -s -X DELETE http://localhost:9002/api/scan \
  -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, pipeline). Only one agent run can be active at a time (returns 409 Conflict if busy). Set "stream": true for real-time SSE output. For full details on agent modes, prompt templates, and API request/response schemas, see the Agent Mode documentation and the Agent API Reference.