Vigolium API Reference, Agent - Vigolium Documentation

Overview

The agent API provides four 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
`POST /api/agent/run/audit`	`vigolium agent audit`	Source-audit dispatcher (vigolium-audit and/or piolium)
`GET /api/agent/status/list`	,	List runs with in-memory status
`GET /api/agent/status/:id`	,	Get run status by ID
`POST /api/agent/scans/:uuid/cancel`	,	Cancel an in-flight agent run
`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

Concurrency is bounded by two pools (server.agent_heavy_max for autopilot/swarm/audit, server.agent_light_max for query and chat completions) plus a per-project heavy cap. New heavy runs return 409 Conflict once the cap is hit; light runs queue until server.agent_queue_timeout elapses and then return 429 Too Many Requests.

Server-default provider, BYOK per request. The server resolves the olium provider from agent.olium.* in vigolium-configs.yaml (which keeps prompt caches stable across requests), but every agent run endpoint also accepts per-request BYOK credentials. Provide any subset of api_key, oauth_token, oauth_cred_file, or oauth_cred_json on the same request to override per call. The audit dispatcher additionally accepts audit_auth and piolium_auth objects to apply different credentials to each driver.

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

* At least one of 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 .

Response (202):

{
  "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, vigolium-audit runs first, native context and planning artifacts are prepared, and then the autonomous operator session starts.

The HTTP schema intentionally keeps structured focus, instruction, browser, and credential fields. v0.3.1 CLI preparation/debugging flags such as --resume, --prior-context, --knowledge-base, --burp-bridge-url, --session-dir, and --transcript are not fields on this endpoint.

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`, `audit_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. Intensity preset overrides default: quick=`150`, balanced=`500`, deep=`1500`
`browser`	bool	No	Enable agent-browser for browser-based interactions
`credentials`	string	No	Credentials for auth preflight (e.g. `"admin/admin123"`)
`credential_sets`	object[]	No	Multiple credential sets keyed by role/persona
`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)
`audit_mode`	string	No	Vigolium-audit mode: `"lite"` (default, 3-phase), `"balanced"` (9-phase), `"deep"` (12-phase), `"mock"`
`no_audit`	bool	No	Disable automatic vigolium-audit (enabled by default when `source` is set)
`audit`	string	No	Shorthand for `audit_mode`/`no_audit`: `"lite"`, `"balanced"`, `"deep"`, `"mock"`, or `"off"`
`piolium`	string	No	Run a piolium audit in parallel with the autopilot prep. Same value set as `audit`
`triage`	bool	No	Enable an AI triage pass over the autopilot’s findings on completion
`upload_results`	bool	No	Upload session bundle to cloud storage on completion (requires `storage` config)
`api_key`	string	No	BYOK API key for this request (overrides server config)
`oauth_token`	string	No	BYOK OAuth token for this request
`oauth_cred_file`	string	No	Path to an OAuth credential JSON file readable by the server
`oauth_cred_json`	string	No	Inline OAuth credential JSON

* At least one of 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 .

Balanced scan (default):

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
  }'

Deep scan:

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
  }'

Response (202):

{
  "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; the API uses auth: true, and browser tooling is enabled by the intensity/config path)
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`, `audit`, concurrency, and duration settings
`input`	string	No*	Single input (URL, curl command, raw HTTP, Burp XML)
`inputs`	string[]	No*	Multiple inputs
`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

* At least one of input, inputs, 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

Scanning parameters:

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	Start a new run at a specific phase, marking earlier phases complete
`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"`)
`audit`	string	No	Background vigolium-audit: `"lite"`, `"balanced"`, `"deep"`, `"mock"`, `"off"`. Requires `source`.
`piolium`	string	No	Background piolium audit (run in parallel with vigolium-audit). Same value set as `audit`.
`auth`	object	No	Per-host auth configuration (browser-driven login + token rules)
`auth_required`	bool	No	Require auth/session preparation before the master agent starts
`requires_browser`	bool	No	Require browser-assisted auth
`browser_start_url`	string	No	Explicit browser/login start URL
`focus_routes`	string[]	No	Protected/browser-focused routes to prioritize
`credentials`	string	No	Credentials for auth preflight (e.g. `"admin/admin123"`)
`credential_sets`	object[]	No	Multiple credential sets keyed by role/persona

Concurrency tuning:

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)

Output / scoping:

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 `"12h"`)
`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

Examples:

# 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 vigolium-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,
    "audit": "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"
  }'

Response (202):

{
  "agentic_scan_uuid": "agt-550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "message": "swarm run started"
}

POST /api/agent/run/audit, Source-Audit Driver Dispatcher

Launches a multi-phase source-code audit driven by the embedded vigolium-audit harness and/or the standalone piolium harness against a single source tree under one AgenticScan. Per-driver child rows hang off the parent run; the dispatcher runs a project-wide findings dedup pass once its drivers exit. Request body, core fields:

Field	Type	Required	Description
`source`	string	Yes	Path to source code, git URL (HTTPS or SSH), or archive file. Legacy alias: `repo_path`.
`driver`	string	No	`"auto"` (default — run audit; fall back to piolium only if `claude`/`codex` CLI is missing), `"both"` (run audit then piolium unconditionally), `"audit"`, or `"piolium"`
`mode`	string	No	Harness mode — see `--list-modes` on `vigolium agent audit` / `vigolium agent audit`. Under `auto`/`both`, restricted to shared modes (`lite`, `balanced`, `deep`, `revisit`, `confirm`, `merge`).
`modes`	string[]	No	Chain modes back-to-back (e.g. `["deep","confirm"]`). Audit runs the chain natively in one subprocess; piolium chains via sequential runs collapsed into one aggregated child row.
`intensity`	string	No	`"quick"` → `lite`, `"balanced"` → `balanced`, `"deep"` → chain `[deep, confirm]`
`agent`	string	No	Audit-leg agent selector: `"claude"` or `"codex"`. Layered on top of `provider`.
`provider`	string	No	Olium provider name (e.g. `anthropic-api-key`). Resolves the audit-leg agent and forwards BYOK auth (`anthropic-` → claude, `openai-` → codex).
`commit_depth`	int	No	Shallow-clone depth (0 = full history)
`interactive`	bool	No	Drop into the audit harness interactively (audit-only). Skips NDJSON streaming and findings auto-import.
`no_stream`	bool	No	Disable streaming progress to the client
`no_dedup`	bool	No	Skip the post-pass project-wide findings dedup
`no_preflight`	bool	No	Skip per-driver preflight checks
`upload_results`	bool	No	Upload session bundle on completion (requires `storage` config)
`stream`	bool	No	If `true`, returns an SSE stream with `driver`/`chunk`/`phase`/`done`/`error` events
`timeout`	string	No	Go duration string
`project_uuid`	string	No	Scope results to a project
`scan_uuid`	string	No	Link results to a specific scan UUID

Per-driver BYOK overrides apply different credentials to each leg under auto/both:

Field	Type	Description
`audit_auth`	object	`{api_key, oauth_token, oauth_cred_file, oauth_cred_json}` applied to the vigolium-audit leg
`piolium_auth`	object	Same shape, applied to the piolium leg

Piolium-specific flags:

Field	Type	Description
`pi_provider`	string	Override Pi’s provider for the piolium leg
`pi_model`	string	Override Pi’s model for the piolium leg
`plm_*`	varied	Pass-through flags to piolium’s session config

Examples:

# Default: auto — vigolium-audit, fall back to piolium if the CLI is missing
curl -s -X POST http://localhost:9002/api/agent/run/audit \
  -H "Content-Type: application/json" \
  -d '{"source": "/home/user/src/my-app"}' | jq .

# Both drivers, deep intensity (expands to mode chain [deep, confirm])
curl -s -X POST http://localhost:9002/api/agent/run/audit \
  -H "Content-Type: application/json" \
  -d '{
    "source": "/home/user/src/my-app",
    "driver": "both",
    "intensity": "deep"
  }' | jq .

# Per-driver BYOK
curl -s -X POST http://localhost:9002/api/agent/run/audit \
  -H "Content-Type: application/json" \
  -d '{
    "source": "/home/user/src/my-app",
    "driver": "both",
    "audit_auth":   {"api_key": "sk-ant-..."},
    "piolium_auth": {"api_key": "sk-..."}
  }' | jq .

# Streamed multi-driver run (SSE)
curl -N -X POST http://localhost:9002/api/agent/run/audit \
  -H "Content-Type: application/json" \
  -d '{
    "source": "/home/user/src/my-app",
    "driver": "both",
    "stream": true
  }'

SSE events for audit: Each chunk event includes a driver field ("audit" or "piolium"). The dispatcher brackets each driver’s stream with driver_start and driver_end events so a UI can group log lines by driver. The done event arrives once after both drivers (and the dedup pass) finish.

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 vigolium-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)
`audit`	`audit_mode`	`audit`	`"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 (audit adds a `driver` field)	All
`phase`	Phase transition (includes `phase` field)	Swarm, audit
`driver_start`	Multi-driver dispatcher began streaming a driver	Audit (multi-driver)
`driver_end`	Multi-driver dispatcher finished streaming a driver	Audit (multi-driver)
`done`	Final event with the complete result object	All
`error`	Agent run failed; includes `error` message	All

Example SSE stream (swarm):

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"`, `"swarm"`, `"audit"`, or `"pipeline"`
`status`	string	`"running"`, `"completed"`, `"failed"`, or `"cancelled"`
`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)

POST /api/agent/scans/:uuid/cancel, Cancel an Agent Run

Aborts an in-flight agent run (autopilot, swarm, query, or audit) by cancelling its context. The run unwinds and its finalization records the terminal cancelled status. This is the endpoint the workbench UI’s “Cancel run” button calls.

curl -s -X POST \
  http://localhost:9002/api/agent/scans/agt-661f9511-f3ac-52e5-b827-557766551111/cancel \
  -H "Authorization: Bearer my-secret-key" | jq .

{
  "agentic_scan_uuid": "agt-661f9511-f3ac-52e5-b827-557766551111",
  "status": "cancelling",
  "message": "cancellation requested"
}

Returns 404 with {"error": "run not found or already finished"} when no run with that UUID is currently running in this process (already finished, never started, or unknown). Cancellation only targets runs executing in the server process that receives the request.

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`, `audit`
`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, vigolium-audit output, plan/checkpoint files.

curl -s http://localhost:9002/api/agent/sessions/agt-550e8400-.../artifacts | jq .

{
  "agentic_scan_uuid": "agt-550e8400-e29b-41d4-a716-446655440000",
  "session_dir": "/home/user/.vigolium/agent-sessions/agt-550e8400-...",
  "artifacts": [
    {"name": "swarm-plan.json", "size": 2048, "modified_at": "2026-05-21T10:01:00Z", "kind": "file"},
    {"name": "extensions/sqli-custom.js", "size": 1024, "modified_at": "2026-05-21T10:02:00Z", "kind": "file"},
    {"name": "vigolium-audit/findings/p8-001.md", "size": 4096, "modified_at": "2026-05-21T10:03:00Z", "kind": "file"}
  ],
  "truncated": false
}

GET /api/agent/sessions/:id/artifacts/, Read Artifact

Read a specific artifact file. Wildcard supports nesting (e.g. vigolium-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"}],
)

See Agent Mode for full agent documentation.

​Overview

​POST /api/agent/run/query, Single-Shot Agent Run

​POST /api/agent/run/autopilot, Autonomous Scanning Session

​POST /api/agent/run/swarm, AI-Guided Vulnerability Swarm

​POST /api/agent/run/audit, Source-Audit Driver Dispatcher

​Natural Language Prompts

​SSE Streaming

​GET /api/agent/status/list, List Agent Runs

​GET /api/agent/status/:id, Agent Run Status

​POST /api/agent/scans/:uuid/cancel, Cancel an Agent Run

​GET /api/agent/sessions, List Agent Sessions

​GET /api/agent/sessions/:id, Agent Session Detail

​GET /api/agent/sessions/:id/logs, Session Console Logs

​GET /api/agent/sessions/:id/artifacts, List Session Artifacts

​GET /api/agent/sessions/:id/artifacts/, Read Artifact

​POST /api/agent/chat/completions, OpenAI-Compatible Chat Completions

Overview

POST /api/agent/run/query, Single-Shot Agent Run

POST /api/agent/run/autopilot, Autonomous Scanning Session

POST /api/agent/run/swarm, AI-Guided Vulnerability Swarm

POST /api/agent/run/audit, Source-Audit Driver Dispatcher

Natural Language Prompts

SSE Streaming

GET /api/agent/status/list, List Agent Runs

GET /api/agent/status/:id, Agent Run Status

POST /api/agent/scans/:uuid/cancel, Cancel an Agent Run

GET /api/agent/sessions, List Agent Sessions

GET /api/agent/sessions/:id, Agent Session Detail

GET /api/agent/sessions/:id/logs, Session Console Logs

GET /api/agent/sessions/:id/artifacts, List Session Artifacts

GET /api/agent/sessions/:id/artifacts/, Read Artifact

POST /api/agent/chat/completions, OpenAI-Compatible Chat Completions