> ## 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. # Vigolium API Reference, Agent > AI agent API with query, autopilot, swarm, and audit run modes, SSE streaming, session history, and OpenAI-compatible chat. ## 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. ```bash theme={null} # 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):** ```json theme={null} { "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. **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:TOKEN@github.com/...`), 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):** ```bash theme={null} 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):** ```bash theme={null} 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:** ```bash theme={null} 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):** ```json theme={null} { "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: 1. **Normalize**: Parse and normalize inputs (native, no AI) 2. **Auth**: Browser-based login (native, optional, requires `--browser-auth` + `--browser`) 3. **Source Analysis**: AI agents extract routes, auth flows, and extensions from source code *(conditional, requires `source`)* 4. **Code Audit**: AI security code audit *(conditional, requires `code_audit: true`)* 5. **Discovery**: Content discovery and spidering *(conditional, requires `discover` flag)* 6. **Plan**: Master agent analyzes targets, selects modules, generates quick checks and extensions 7. **Extension**: Validate, merge, and write JS extensions to disk (native) 8. **Scan**: Execute scanner modules with agent-selected filters and extensions (native) 9. **Triage**: AI agent reviews findings, confirms or marks as false positive *(optional, requires `triage: true`)* 10. **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 | 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"`) | | `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:** ```bash theme={null} # 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):** ```json theme={null} { "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:** ```bash theme={null} # 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 | ```bash theme={null} # 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. ```bash theme={null} curl -s http://localhost:9002/api/agent/status/list | jq . ``` ```json theme={null} [ { "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. ```bash theme={null} curl -s -X POST \ http://localhost:9002/api/agent/scans/agt-661f9511-f3ac-52e5-b827-557766551111/cancel \ -H "Authorization: Bearer my-secret-key" | jq . ``` ```json theme={null} { "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 | ```bash theme={null} 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). | ```bash theme={null} # 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. ```bash theme={null} curl -s http://localhost:9002/api/agent/sessions/agt-550e8400-.../artifacts | jq . ``` ```json theme={null} { "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/{name}, 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). | ```bash theme={null} 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 | ```bash theme={null} curl -s -X POST http://localhost:9002/api/agent/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "model": "vigolium-olium", "messages": [ { "role": "user", "content": "What are common JWT vulnerabilities?" } ] }' | jq . ``` ```python theme={null} from openai import OpenAI client = OpenAI( base_url="http://localhost:9002/api/agent", api_key="", ) response = client.chat.completions.create( model="vigolium-olium", messages=[{"role": "user", "content": "Explain CSRF attacks"}], ) ``` See [Agent Mode](/agentic-scan/agent-mode) for full agent documentation.