Registry API¶

The Registry API provides a CISO-level aggregated view of all agents across the organization. The registry consolidates agent status, connector usage, policy coverage, drift events, and compliance posture into a single endpoint designed for security leadership dashboards and organizational risk assessment.

All data is scoped to the authenticated user's organization via Row-Level Security.

Get Agent Registry¶

Retrieves an aggregated overview of all agents with status, risk, and compliance metrics.

Method: GET
Path: /v1/registry
Required Role: Any authenticated user

Query Parameters¶

Parameter	Type	Required	Description
`status`	`string`	No	Filter agents by status: `active`, `inactive`, `suspended`, `error`.

Example¶

curl -X GET "https://api.arxsec.io/v1/registry" \
  -H "Authorization: Bearer {token}"

Response¶

{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "triage-agent",
      "description": "Automated SOC triage agent for CrowdStrike detections",
      "status": "active",
      "runtime": "docker",
      "version": 3,
      "owner_id": "user-uuid",
      "connector_count": 2,
      "policy_count": 4,
      "audit_action_count": 1247,
      "drift_event_count": 1,
      "compliance_package_count": 3,
      "last_activity": "2026-04-10T16:30:00Z",
      "created_at": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 5,
  "summary": {
    "total_agents": 5,
    "status_breakdown": {
      "active": 3,
      "inactive": 1,
      "suspended": 1,
      "error": 0
    },
    "total_drift_events": 4,
    "agents_without_policies": 1,
    "agents_without_compliance": 2
  }
}

Response Fields¶

Each agent entry includes the following aggregated metrics:

Field	Type	Description
`connector_count`	`integer`	Number of connector configurations bound to the agent.
`policy_count`	`integer`	Number of policy rules governing the agent.
`audit_action_count`	`integer`	Total audit log entries for the agent.
`drift_event_count`	`integer`	Number of behavioral drift events detected.
`compliance_package_count`	`integer`	Number of compliance packages generated.
`last_activity`	`string`	Timestamp of the most recent audit log entry.

The summary object provides organization-wide aggregates for dashboard display, including the count of agents without policies (potential governance gaps) and agents without compliance packages (outstanding evidence generation).