Agents

Register the agents you govern and toggle whether they are told they are monitored.

Method	Path	Scope	Summary
GET	/agents/	read	List Agents
POST	/agents/	events:write	Register Agent
GET	/agents/{agent_id}	read	Get Agent
PATCH	/agents/{agent_id}/monitoring	events:write	Set Monitoring State

Try it

curl -sf -X POST "$VIGIL_URL/agents/" -H "Authorization: Bearer $VIGIL_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id":"docs-api","name":"Docs API"}' > /dev/null || true
curl -sf -H "Authorization: Bearer $VIGIL_KEY" "$VIGIL_URL/agents/docs-api"

Routes

GET /agents/

List Agents. Scope: read.

Active agents in the org. kind narrows to one kind; include_inactive=true (admin) adds retired agents.

Parameter	In	Required	Type	Notes
kind	query	no	production, sandbox, system | null
include_inactive	query	no	boolean

Response 200:

[
  {
    "id": 0,
    "org_id": 0,
    "agent_id": "string",
    "name": "string",
    "description": "string | null",
    "registered_at": "2026-09-08T00:00:00Z",
    "is_active": true,
    "kind": "string",
    "public": true,
    "public_links": "string | null",
    "currently_monitored": true,
    "monitoring_toggled_at": "2026-09-08T00:00:00Z | null"
  }
]

POST /agents/

Register Agent. Scope: events:write.

Request body:

{
  "agent_id": "string",
  "name": "string",
  "description": "string | null",
  "kind": "production | sandbox | system"
}

Field	Type	Required	Notes
agent_id	string	yes
name	string	yes
description	string | null	no
kind	production, sandbox, system	no

Response 200:

{
  "id": 0,
  "org_id": 0,
  "agent_id": "string",
  "name": "string",
  "description": "string | null",
  "registered_at": "2026-09-08T00:00:00Z",
  "is_active": true,
  "kind": "string",
  "public": true,
  "public_links": "string | null",
  "currently_monitored": true,
  "monitoring_toggled_at": "2026-09-08T00:00:00Z | null"
}

GET /agents/{agent_id}

Get Agent. Scope: read.

Parameter	In	Required	Type	Notes
agent_id	path	yes	string

Response 200:

{
  "id": 0,
  "org_id": 0,
  "agent_id": "string",
  "name": "string",
  "description": "string | null",
  "registered_at": "2026-09-08T00:00:00Z",
  "is_active": true,
  "kind": "string",
  "public": true,
  "public_links": "string | null",
  "currently_monitored": true,
  "monitoring_toggled_at": "2026-09-08T00:00:00Z | null"
}

PATCH /agents/{agent_id}/monitoring

Set Monitoring State. Scope: events:write.

Toggle monitoring state. Used by alignment faking detector.

Parameter	In	Required	Type	Notes
agent_id	path	yes	string

Request body:

{
  "monitored": true
}

Field	Type	Required	Notes
monitored	boolean	yes

Response 200:

{
  "id": 0,
  "org_id": 0,
  "agent_id": "string",
  "name": "string",
  "description": "string | null",
  "registered_at": "2026-09-08T00:00:00Z",
  "is_active": true,
  "kind": "string",
  "public": true,
  "public_links": "string | null",
  "currently_monitored": true,
  "monitoring_toggled_at": "2026-09-08T00:00:00Z | null"
}

Generated from openapi.json (VIGIL 0.2.0). Scopes follow the router dependencies in VIGIL_SPEC.md section 4.2.