Documentation Index
Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The agent API provides three run modes that mirror the vigolium agent CLI subcommands, plus session history and status endpoints:
| Endpoint | CLI Equivalent | Description |
|---|
POST /api/agent/run/query | vigolium agent query | Single-shot prompt execution |
POST /api/agent/run/autopilot | vigolium agent autopilot | Autonomous AI-driven scanning session |
POST /api/agent/run/swarm | vigolium agent swarm | AI-guided multi-phase vulnerability swarm |
GET /api/agent/status/list | — | List runs with in-memory status |
GET /api/agent/status/:id | — | Get run status by ID |
GET /api/agent/sessions | vigolium agent sessions | Paginated session history from DB |
GET /api/agent/sessions/:id | — | Full session detail with debug fields |
GET /api/agent/sessions/:id/logs | — | Raw runtime.log (plain text or SSE tail) |
GET /api/agent/sessions/:id/artifacts | — | List session artifact files |
GET /api/agent/sessions/:id/artifacts/{name} | — | Read a specific artifact (10 MiB default cap) |
POST /api/agent/chat/completions | — | OpenAI-compatible chat completions |
server.agent_heavy_max / server.agent_light_max) — exceeding the cap returns 429 Too Many Requests after server.agent_queue_timeout.
Provider overrides are CLI-only. The server resolves the olium provider once from agent.olium.* in vigolium-configs.yaml and reuses it across requests. There is no per-request provider/model field — to switch providers on a server-side workload, edit the YAML and reload.
POST /api/agent/run/query — Single-Shot Agent Run
Starts an AI agent run with a prompt template, file, or inline prompt. Returns 202 Accepted (async) or an SSE stream when stream: true.
Request body:
| Field | Type | Required | Description |
|---|
agent | string | No | Optional descriptive label persisted to the run record (provider is server-side from agent.olium.*) |
prompt_template | string | No* | Name of a prompt template (from ~/.vigolium/prompts/) |
prompt_file | string | No* | Path to a prompt file on disk |
prompt | string | No* | Inline prompt text |
source | string | No | Path to source code for context. Legacy alias: repo_path. |
files | string[] | No | Specific files to include as context |
append | string | No | Additional text appended to the prompt |
instruction | string | No | Custom instruction appended to the prompt |
source_label | string | No | Source label for findings ingested from agent output |
scan_uuid | string | No | Link results to a specific scan UUID |
stream | bool | No | If true, returns an SSE stream instead of 202 async response |
prompt_template, prompt_file, or prompt is required.
# Run with a prompt template
curl -s -X POST http://localhost:9002/api/agent/run/query \
-H "Content-Type: application/json" \
-d '{
"prompt_template": "security-code-review",
"source": "/home/user/src/my-app"
}' | jq .
# Run with an inline prompt
curl -s -X POST http://localhost:9002/api/agent/run/query \
-H "Content-Type: application/json" \
-d '{
"prompt": "Analyze the authentication flow for vulnerabilities",
"source": "/home/user/src/my-app",
"files": ["src/auth/login.py", "src/auth/session.py"]
}' | jq .
{
"agentic_scan_uuid": "agt-550e8400-e29b-41d4-a716-446655440000",
"status": "running",
"message": "query run started"
}
POST /api/agent/run/autopilot — Autonomous Scanning Session
Launches an AI agent that autonomously discovers, scans, and triages vulnerabilities using vigolium CLI commands. When source is provided, archon-audit runs first, native context and planning artifacts are prepared, and then the autonomous operator session starts.
Request body:
| Field | Type | Required | Description |
|---|
prompt | string | No | Natural language scan prompt (parsed into target/source/focus when explicit fields are empty) |
intensity | string | No | Scan intensity preset: "quick", "balanced" (default), or "deep". Bundles max_commands, timeout, archon_mode, and browser settings |
target | string | No* | Target URL to scan (derived from input if not set) |
input | string | No | Raw input (curl, raw HTTP, Burp XML, URL) — target extracted automatically |
agent | string | No | Optional descriptive label persisted to the run record |
source | string | No | Path to source code, git URL (with optional OAuth token), or archive file (.zip, .tar.gz, .tgz, .tar.bz2, .tar.xz). Legacy alias: repo_path. |
files | string[] | No | Specific files to include (relative to source). Auto-populated from diff when not set |
diff | string | No | Focus on changed code: GitHub PR URL (github.com/.../pull/123), git ref range (main...branch), or HEAD~N |
last_commits | int | No | Focus on last N commits (shorthand for diff: "HEAD~N") |
focus | string | No | Focus area hint (e.g. "API injection", "auth bypass") |
instruction | string | No | Custom instruction appended to the prompt |
timeout | string | No | Go duration string (default "6h") |
max_commands | int | No | Max LLM turns the agent can take (default 100) |
token_budget | int | No | Cap on cumulative input+output tokens (0 = no cap) |
browser | bool | No | Enable agent-browser for browser-based interactions |
credentials | string | No | Credentials for auth preflight (e.g. "admin/admin123") |
auth_required | bool | No | Require auth/session preparation before the operator starts |
requires_browser | bool | No | Require browser-assisted auth instead of HTTP-only preflight |
browser_start_url | string | No | Explicit browser/login start URL |
focus_routes | string[] | No | Protected/browser-focused routes to prioritize |
dry_run | bool | No | Render the prompt without executing the agent |
stream | bool | No | If true, returns an SSE stream |
scan_uuid | string | No | Link results to a specific scan UUID |
project_uuid | string | No | Scope results to a project (falls back to X-Project-UUID header) |
archon_mode | string | No | Archon audit mode: "lite" (default, 3-phase), "balanced" (6-phase), "deep" (10-phase), "mock" |
no_archon | bool | No | Disable automatic archon-audit (enabled by default when source is set) |
archon | string | No | DEPRECATED — use no_archon + archon_mode instead. Legacy values: "lite", "balanced", "deep", "off" |
upload_results | bool | No | Upload session bundle to cloud storage on completion (requires storage config) |
target, input, source, diff, or prompt is required.
Source resolution: The source field accepts local paths, git URLs (HTTPS or SSH), git URLs with embedded OAuth tokens (https://oauth2:[email protected]/...), and archive files. Git repos are cloned with --depth 1 and archives are extracted into the session directory. OAuth tokens are stripped from logs.
Diff resolution: When diff is set, the changed file list auto-populates files and the patch content is included in the agent prompt. For PR URLs without source, the repo is auto-cloned. GitHub PRs use the GitHub REST API directly (no gh CLI required). The GITHUB_TOKEN env var is used as a fallback.
Quick scan (CI/PR review):
curl -s -X POST http://localhost:9002/api/agent/run/autopilot \
-H "Content-Type: application/json" \
-d '{
"target": "http://localhost:3000",
"source": "/home/user/src/my-app",
"intensity": "quick",
"diff": "https://github.com/org/repo/pull/42"
}' | jq .
curl -s -X POST http://localhost:9002/api/agent/run/autopilot \
-H "Content-Type: application/json" \
-d '{
"target": "http://localhost:3000",
"source": "/home/user/src/my-app",
"focus": "authentication bypass",
"stream": true
}'
curl -s -X POST http://localhost:9002/api/agent/run/autopilot \
-H "Content-Type: application/json" \
-d '{
"target": "http://localhost:3000",
"source": "/home/user/src/my-app",
"intensity": "deep",
"instruction": "Test all API endpoints. Focus on IDOR, auth bypass, and injection.",
"stream": true
}'
{
"agentic_scan_uuid": "agt-550e8400-e29b-41d4-a716-446655440000",
"status": "running",
"message": "autopilot run started"
}
POST /api/agent/run/swarm — AI-Guided Vulnerability Swarm
Launches an AI-guided multi-phase vulnerability swarm. The master agent analyzes inputs, selects scanner modules, generates custom JS extensions, executes scans, and optionally triages results. The swarm phases are:
- Normalize — Parse and normalize inputs (native, no AI)
- Auth — Browser-based login (native, optional, requires
--browser-auth + --browser)
- Source Analysis — AI agents extract routes, auth flows, and extensions from source code (conditional, requires
source)
- Code Audit — AI security code audit (conditional, requires
code_audit: true)
- Discovery — Content discovery and spidering (conditional, requires
discover flag)
- Plan — Master agent analyzes targets, selects modules, generates quick checks and extensions
- Extension — Validate, merge, and write JS extensions to disk (native)
- Scan — Execute scanner modules with agent-selected filters and extensions (native)
- Triage — AI agent reviews findings, confirms or marks as false positive (optional, requires
triage: true)
- Rescan — Targeted re-scanning based on triage follow-ups (conditional, triggered by triage)
AI agents are called at phases 3, 4, 6, and 9. When inputs exceed master_batch_size records, the master agent runs in parallel batches (default 5 records per batch) with plan merging.
Request body — Inputs:
| Field | Type | Required | Description |
|---|
prompt | string | No | Natural language scan prompt |
intensity | string | No | "quick", "balanced" (default), "deep" — bundles discover, triage, code_audit, max_iterations, archon, concurrency, and duration settings |
input | string | No* | Single input (URL, curl command, raw HTTP, Burp XML, or record UUID) |
inputs | string[] | No* | Multiple inputs |
target | string | No | Target URL (alias for input when given alone) |
record_uuid | string | No | HTTP record UUID from the database |
http_request_base64 | string | No* | Base64-encoded raw HTTP request |
http_response_base64 | string | No | Base64-encoded raw HTTP response (attached to the request above) |
url | string | No | URL hint for parsing the base64 request |
input, inputs, target, record_uuid, http_request_base64, source, diff, or prompt is required.
Source analysis:
| Field | Type | Required | Description |
|---|
source | string | No | Path to source code, git URL, or archive file. Legacy alias: source_path. |
files | string[] | No | Specific source files to include (relative to source) |
diff | string | No | Focus on changed code: PR URL, git ref range, or HEAD~N |
last_commits | int | No | Focus on last N commits |
source_analysis_only | bool | No | Run only the source analysis phase and exit |
| Field | Type | Required | Description |
|---|
vuln_type | string | No | Vulnerability type focus (e.g. "sqli", "xss") |
focus | string | No | Broad focus area hint |
instruction | string | No | Custom instruction appended to agent prompts |
module_names | string[] | No | Explicit module IDs to use |
only_phase | string | No | Isolate a single phase |
skip_phases | string[] | No | Skip specific phases |
start_from | string | No | Resume from a specific phase |
max_iterations | int | No | Max triage→rescan rounds (default depends on intensity) |
discover | bool | No | Run discovery+spidering before master agent planning |
code_audit | bool | No | Enable AI security code audit phase (requires source) |
triage | bool | No | Enable AI triage and rescan phases |
force_extensions | bool | No | Force extension agent to run even when the master returned no extensions |
profile | string | No | Scanning profile name (e.g. "light", "thorough") |
archon | string | No | Background archon-audit: "lite", "balanced", "deep", "mock", "off". Requires source. |
| Field | Type | Required | Description |
|---|
batch_concurrency | int | No | Max parallel master agent batches (0 = auto) |
max_master_retries | int | No | Max master agent retries on parse failure (default 3) |
sa_max_concurrency | int | No | Max parallel source analysis sub-agents (default 3) |
max_plan_records | int | No | Max records sent to plan agent (0 = default 10) |
master_batch_size | int | No | Max records per master agent batch (0 = default 5) |
probe_concurrency | int | No | Max parallel probe requests (0 = default 10) |
probe_timeout | string | No | Per-request probe timeout as Go duration |
max_probe_body | int | No | Max response body size in bytes during probing (0 = default 2 MB) |
| Field | Type | Required | Description |
|---|
agent | string | No | Optional descriptive label |
dry_run | bool | No | Render prompts without executing agents |
show_prompt | bool | No | Include rendered prompts in output |
stream | bool | No | If true, returns an SSE stream with phase events |
timeout | string | No | Go duration string (default "15m") |
project_uuid | string | No | Scope results to a project |
scan_uuid | string | No | Link results to a specific scan UUID |
upload_results | bool | No | Upload session bundle to cloud storage on completion |
# Swarm a single URL
curl -s -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-d '{
"input": "https://example.com/api/search?q=test"
}' | jq .
# Swarm a curl command (auto-detected)
curl -s -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-d '{
"input": "curl -X POST -H '\''Content-Type: application/json'\'' -d '\''{\"user\":\"admin\"}'\'' https://example.com/api/login"
}' | jq .
# Source-aware with code audit + discovery — full pipeline
curl -s -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-d '{
"input": "https://example.com",
"source": "/home/user/src/my-app",
"discover": true,
"code_audit": true,
"triage": true,
"instruction": "Focus on business logic flaws in the payment flow",
"profile": "thorough"
}' | jq .
# Source-aware with background archon-audit
curl -s -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-d '{
"input": "https://example.com",
"source": "/home/user/src/my-app",
"discover": true,
"archon": "lite"
}' | jq .
# Diff-focused on a GitHub PR
curl -s -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-d '{
"input": "http://localhost:3000",
"source": "/home/user/src/my-app",
"diff": "https://github.com/org/repo/pull/42"
}' | jq .
# SSE streaming with project scoping
curl -N -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-H "X-Project-UUID: proj-123" \
-d '{
"input": "https://example.com",
"stream": true,
"timeout": "30m",
"intensity": "deep"
}'
{
"agentic_scan_uuid": "agt-550e8400-e29b-41d4-a716-446655440000",
"status": "running",
"message": "swarm run started"
}
Natural Language Prompts
The autopilot and swarm endpoints accept a prompt field for natural language scan requests. When prompt is provided and no explicit input fields are set (target, input, source), the prompt is parsed by an AI intent extractor that returns structured parameters.
The intent extractor recognizes: target URLs, source code paths, vulnerability focus areas, custom instructions, discovery mode, code audit mode, and archon audit level.
| Intent Field | Maps To (Autopilot) | Maps To (Swarm) | Description |
|---|
target | target | input | Target URL |
source_path | source | source | Filesystem path to source code |
focus | focus | focus | Vulnerability focus area |
instruction | instruction | instruction | Remaining guidance |
discover | — | discover | Inferred when both target and source are present |
code_audit | — | code_audit | Inferred when source-only (no target) |
archon | archon_mode | archon | "lite", "balanced", or "deep" when audit agent is mentioned |
# Swarm with a natural language prompt
curl -s -X POST http://localhost:9002/api/agent/run/swarm \
-H "Content-Type: application/json" \
-d '{
"prompt": "scan source at ~/src/VAmPI on localhost:3005 with audit agent"
}' | jq .
# Dry run — preview extracted intent without launching a scan
curl -s -X POST http://localhost:9002/api/agent/run/autopilot \
-H "Content-Type: application/json" \
-d '{
"prompt": "scan VAmPI source at ~/src/VAmPI on localhost:3005 with full audit agent",
"dry_run": true
}' | jq .
Explicit fields always take precedence. If you pass both prompt and target/input/source, the prompt is ignored.
SSE Streaming
All run endpoints support "stream": true, which returns a text/event-stream response. Each event is a JSON object on a data: line.
| Type | Description | Modes |
|---|
chunk | Incremental text output from the agent | All |
phase | Phase transition (includes phase field) | Swarm only |
done | Final event with the complete result object | All |
error | Agent run failed; includes error message | All |
data: {"type":"phase","phase":"native-normalize"}
data: {"type":"phase","phase":"plan"}
data: {"type":"chunk","text":"Analyzing targets for attack strategy..."}
data: {"type":"phase","phase":"native-extension"}
data: {"type":"phase","phase":"native-scan"}
data: {"type":"phase","phase":"triage"}
data: {"type":"done","swarm_result":{"total_findings":5,"confirmed":3,"false_positives":2,"iterations":2,"severity_counts":{"high":2,"medium":3}}}
GET /api/agent/status/list — List Agent Runs
Returns all agent runs with their current status.
curl -s http://localhost:9002/api/agent/status/list | jq .
[
{
"agentic_scan_uuid": "agt-550e8400-e29b-41d4-a716-446655440000",
"mode": "query",
"status": "completed",
"agent_name": "olium",
"template_id": "security-code-review",
"finding_count": 3,
"saved_count": 3,
"completed_at": "2026-04-01T15:10:00Z"
},
{
"agentic_scan_uuid": "agt-661f9511-f3ac-52e5-b827-557766551111",
"mode": "swarm",
"status": "running",
"current_phase": "native-scan",
"phases_run": ["native-normalize", "plan", "native-extension"]
}
]
GET /api/agent/status/:id — Agent Run Status
| Field | Type | Description |
|---|
agentic_scan_uuid | string | Unique run identifier |
mode | string | "query", "autopilot", or "swarm" |
status | string | "running", "completed", or "failed" |
agent_name | string | Agent label recorded for the run |
template_id | string | Prompt template ID (query mode) |
finding_count | int | Number of findings produced |
record_count | int | Number of HTTP records produced (query/autopilot) |
saved_count | int | Number of records saved to DB (query/autopilot) |
error | string | Error message (failed runs only) |
completed_at | string | ISO 8601 completion timestamp |
result | object | Full agent result (query/autopilot, completed runs) |
current_phase | string | Currently executing phase (swarm, running) |
phases_run | string[] | Completed phases (swarm) |
swarm_result | object | Full swarm result (swarm, completed runs) |
GET /api/agent/sessions — List Agent Sessions
Paginated list of agent sessions from the database. Unlike /api/agent/status/list (which includes in-memory running state), this returns persisted historical sessions with structured metadata — but without large debug fields (prompt_sent, agent_raw_output, etc.) to keep responses lightweight.
| Parameter | Type | Default | Description |
|---|
mode | string | — | Filter by mode: query, autopilot, swarm |
limit | int | 50 | Page size (max 500) |
offset | int | 0 | Offset for pagination |
curl -s 'http://localhost:9002/api/agent/sessions?mode=swarm&limit=10' | jq .
GET /api/agent/sessions/:id — Agent Session Detail
Full detail of a single agent session, including large debug fields: prompt_sent, agent_raw_output, attack_plan, triage_result, result_json.
| Field | Type | Description |
|---|
input_raw | string | Raw input provided to the agent run |
module_names | string[] | Scanner modules used or selected |
source_path | string | Source code path used for the run |
source_type | string | How source was provided: local, git-url, or gcs |
session_id | string | Session ID (for autopilot resume) |
prompt_sent | string | Full prompt text sent to the agent |
agent_raw_output | string | Complete raw output from the agent |
attack_plan | string | JSON attack plan (swarm mode) |
triage_result | string | JSON triage result (swarm mode) |
result_json | string | Full result object as JSON |
GET /api/agent/sessions/:id/logs — Session Console Logs
Returns the raw runtime.log file for a session — the same live console stream the CLI user sees. ANSI colors are preserved by default so browser terminal emulators (xterm.js, etc.) render it exactly like the CLI. Works while the run is in progress and after it finishes.
Two modes, selected via the Accept header:
- Plain text (default):
text/plain; charset=utf-8 dump of the entire runtime.log at request time.
- Server-Sent Events (
Accept: text/event-stream): tails the file and emits each new byte range as a chunk event. Exits with a done event when the run reaches a terminal status, the client disconnects, or a 2-hour safety backstop fires.
| Query param | Type | Description |
|---|
strip | bool | If truthy (1, true, yes), strip ANSI escape sequences server-side. Default: false (preserve ANSI). |
# Plain text dump
curl -s http://localhost:9002/api/agent/sessions/agt-550e8400-.../logs
# Live tail via SSE
curl -N -H 'Accept: text/event-stream' \
http://localhost:9002/api/agent/sessions/agt-550e8400-.../logs
GET /api/agent/sessions/:id/artifacts — List Session Artifacts
Returns a recursive list of files inside the session directory, capped at 500 entries. Useful for browsing generated extensions, archon output, plan/checkpoint files.
curl -s http://localhost:9002/api/agent/sessions/agt-550e8400-.../artifacts | jq .
{
"files": [
{"path": "swarm-plan.json", "size": 2048},
{"path": "extensions/sqli-custom.js", "size": 1024},
{"path": "archon-audit/findings/p8-001.md", "size": 4096}
]
}
GET /api/agent/sessions/:id/artifacts/ — Read Artifact
Read a specific artifact file. Wildcard supports nesting (e.g. archon-audit/state.json).
| Query param | Type | Description |
|---|
max_bytes | int | Override per-request size cap (default 10 MiB, hard cap 100 MiB). |
curl -s 'http://localhost:9002/api/agent/sessions/agt-550e8400-.../artifacts/swarm-plan.json' | jq .
POST /api/agent/chat/completions — OpenAI-Compatible Chat Completions
Accepts an OpenAI-compatible Chat Completions request and returns an OpenAI-compatible response. This allows any OpenAI-compatible client to use the in-process olium engine by changing the base URL.
The model field is currently informational — every request is dispatched through the olium engine using the provider configured under agent.olium.* in vigolium-configs.yaml.
This endpoint is synchronous — it blocks until the agent completes. It shares the concurrency lock with the run endpoints (returns 409 Conflict if an agent is already running).
| Field | Type | Required | Description |
|---|
model | string | Yes | Required by the OpenAI schema; value is informational |
messages | array | Yes | Array of {role, content} message objects |
curl -s -X POST http://localhost:9002/api/agent/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <api-key>" \
-d '{
"model": "vigolium-olium",
"messages": [
{ "role": "user", "content": "What are common JWT vulnerabilities?" }
]
}' | jq .
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:9002/api/agent",
api_key="<api-key>",
)
response = client.chat.completions.create(
model="vigolium-olium",
messages=[{"role": "user", "content": "Explain CSRF attacks"}],
)
