Local API
The service exposes a JSON API on the loopback interface. The dashboard, tray app, hooks and CLI all use it, and so can your own scripts.
On this page
Basics#
- Address
http://127.0.0.1:47823, loopback only. Never reachable from the network.- Format
- JSON, camelCase, ISO-8601 UTC timestamps
- Version
/api/v1- Authentication
- Header
X-Vardhold-Token - Cross-site requests
- Rejected: foreign
HostandOriginheaders get403
Roles#
There are two tokens, both replaced every time the service starts.
| Token | Who has it | May |
|---|---|---|
| User | The tray app and the dashboard it hosts | Read everything, and make anything stricter |
| Admin | %ProgramData%\Vardhold\admin.token, readable only by SYSTEM and Administrators | Everything |
A call that would loosen protection with the user token returns 403 with "elevationRequired": true. These calls need the admin token: allowing an approval, lowering the mode, releasing the kill switch, trusting or unblocking an agent, resuming processes, removing proxy protection from an MCP server, and changing the policy or settings.
Endpoints#
| Area | Endpoints |
|---|---|
| Health and status | GET /health (no token) · GET /status · PUT /mode · GET /stats/activity |
| Agents | GET /agents · GET /agents/{id} · PUT /agents/{id}/trust · PUT /agents/{id}/network · POST /agents/{id}/suspend, /resume, /terminate |
| Kill switch | POST /killswitch with engage, release or terminate |
| MCP servers | GET /mcp · PUT /mcp/{id}/proxy · POST /mcp/rescan |
| Events and alerts | GET /events (filter by agent, action, verdict, severity, source, text and time) · GET /events/{id} · GET /alerts · PUT /alerts/{id} |
| Approvals | GET /approvals · POST /approvals/{id} with allow_once, allow_always or deny |
| Policy | GET /policy · POST /policy/validate · POST /policy/dry-run · PUT /policy · GET /policy/history · GET /policy/history/{version} |
| Settings | GET /settings · PUT /settings · POST /settings/test-export |
| Evidence | POST /integrity/verify · GET /export |
| Live stream | GET /stream, Server-Sent Events |
All paths are under /api/v1. Pilot customers receive the full reference with every type and field.
Live events#
GET /api/v1/stream is a Server-Sent Events stream. Because browsers cannot send headers to an event stream, it also accepts ?token=.
| Event | Sent when |
|---|---|
hello | On connect, with the current status |
event | Every agent event |
alert | Every alert |
approval | An approval is created or changes state |
agent | An agent is discovered, exits, or its trust or network state changes |
status | The mode or kill switch changes, and every 10 seconds |
Example#
List open alerts from an elevated PowerShell prompt:
$h = @{ 'X-Vardhold-Token' = (Get-Content "$env:ProgramData\Vardhold\admin.token") }
Invoke-RestMethod "http://127.0.0.1:47823/api/v1/alerts?status=open" -Headers $h |
Select-Object ts, severity, agentName, title