Agents API

List agents

GET /api/agents

Returns a paginated list of registered agent controllers.

Auth: Required. Global admins see all agents; realm members see agents in their realms.

Query parameters

Parameter	Type	Description
q	string	Search by agent name or DID
online	boolean	Filter to online/offline agents
realm	string	Filter by realm ID or slug
capabilities	string	Comma-separated capabilities — returns agents that have all listed
page	integer	Page number (default: 1)
pageSize	integer	Items per page (default: 20)
sortBy	string	name, registeredAt, lastSeen
sortDir	string	asc or desc

Response

{
  "agents": [
    {
      "id": "did:vaultys:z6Mkf9x3TQ...",
      "name": "analyst-gpt4",
      "capabilities": ["api_call", "file_access"],
      "llmProvider": "openai",
      "llmModel": "gpt-4o",
      "isOnline": true,
      "registeredAt": "2026-04-01T10:00:00Z",
      "lastSeen": "2026-05-15T08:59:00Z",
      "realm": {
        "id": "realm_eng",
        "name": "Engineering",
        "slug": "eng",
        "color": "#3b82f6"
      }
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1,
  "online": 9
}

---

Get agent

GET /api/agents/:id

Auth: Required.

Returns full details for a single agent including its current policy.

Response

{
  "id": "did:vaultys:z6Mkf9x3TQ...",
  "name": "analyst-gpt4",
  "capabilities": ["api_call", "file_access"],
  "llmProvider": "openai",
  "llmModel": "gpt-4o",
  "llmSystemPrompt": "You are a financial analyst...",
  "isOnline": true,
  "registeredAt": "2026-04-01T10:00:00Z",
  "lastSeen": "2026-05-15T08:59:00Z",
  "publicKey": "z6Mkf9x3TQ...",
  "realm": {
    "id": "realm_eng",
    "name": "Engineering",
    "slug": "eng",
    "color": "#3b82f6"
  }
}

---

Register agent

POST /api/agents/register

Registers a new agent controller. In most cases agents register automatically via the WebSocket channel when they first connect. This HTTP endpoint is provided for programmatic registration.

Auth: Optional.

Request body

{
  "name": "my-new-agent",
  "version": "1.0.0",
  "capabilities": ["api_call", "file_access"],
  "publicKey": "z6Mkf9..."
}

Response 201 Created

{
  "agentId": "did:vaultys:z6Mkf9...",
  "message": "Agent registered. Awaiting admin approval."
}

---

Registration approval

New agent registrations require admin approval before the agent becomes active.

List pending registrations

GET /api/registrations

Auth: Global admin only.

{
  "registrations": [
    {
      "id": "reg_01HZ...",
      "name": "my-new-agent",
      "publicKey": "z6Mkf9...",
      "requestedCapabilities": ["api_call", "file_access"],
      "requestedAt": "2026-05-15T09:00:00Z"
    }
  ],
  "availableCapabilities": [
    "file_access",
    "internet_access",
    "browser_control",
    "api_call",
    "mail_send",
    "code_execution",
    "system_command",
    "agent_communication"
  ]
}

Approve a registration

POST /api/registrations/:id/approve

Auth: Global admin only.

{
  "capabilities": ["api_call", "file_access"]
}

You can grant a subset of the requested capabilities.

Response 200 OK:

{
  "success": true,
  "agentId": "did:vaultys:z6Mkf9..."
}

Reject a registration

POST /api/registrations/:id/reject

Auth: Global admin only.

{
  "reason": "This agent requires additional security review."
}

Response 200 OK:

{ "success": true }