AIM API Reference
AIM provides 160 REST endpoints across 26 feature categories, covering complete agent identity management functionality.
Auto-Generated Documentation: View the complete OpenAPI/Swagger specification at/api/v1/swagger.yaml
The Swagger spec is the definitive source for all endpoints, request/response schemas, and authentication requirements.
Endpoint Overview
| Category | Endpoints | Description |
|---|---|---|
| Agent Management | 12 | CRUD, verification, credentials |
| MCP Server Management | 11 | CRUD, verification, capabilities |
| Trust Scoring | 6 | Score calculation, history |
| Security Monitoring | 9 | Threats, anomalies, alerts, dashboard |
| Analytics & Reporting | 2 | Usage stats, activity summary |
| User Management | 13 | Registration, roles, admin |
| Monitoring & Events | 9 | Verification events, stats |
| Capabilities | 3 | Grant, revoke, list |
| Organization Settings | 2 | Settings management |
| Security Features (NEW) | 2 | Violations, key vault |
| Other | 5 | Tags, webhooks, SDK |
Total: 160 endpoints (Community Edition)
Security Features (NEW)
Get Agent Violations
GET /api/v1/agents/:id/violationsDescription: Get capability violations for an agent (when agent attempts unauthorized actions).
Query Parameters:
limit(optional): Number of results (default: 10)offset(optional): Pagination offset (default: 0)
{
"violations": [
{
"id": "uuid",
"agent_id": "uuid",
"attempted_capability": "database.write",
"severity": "high",
"trust_score_impact": -5,
"is_blocked": true,
"source_ip": "192.168.1.100",
"created_at": "2025-10-21T14:30:00Z"
}
],
"total": 15
}Get Agent Key Vault
GET /api/v1/agents/:id/key-vaultDescription: Get agent's cryptographic key vault information (public key, expiration, rotation history).
{
"agent_id": "uuid",
"public_key": "MCowBQYDK2VwAyEA...",
"key_algorithm": "Ed25519",
"key_created_at": "2025-01-15T10:30:00Z",
"key_expires_at": "2026-01-15T10:30:00Z",
"rotation_count": 3,
"has_previous_public_key": true
}Analytics & Monitoring (NEW)
Get Activity Summary
GET /api/v1/analytics/activityDescription: Get activity summary for agents and MCP servers over a specified time period. Includes verification counts, attestation counts, and daily activity breakdowns.
Query Parameters:
days(optional): Number of days to include (default: 7, max: 365)
{
"period": {
"start_date": "2025-11-03T00:00:00Z",
"end_date": "2025-11-10T23:59:59Z",
"days": 7
},
"summary": {
"total_agents": 42,
"total_mcp_servers": 15,
"verification_count": 1250,
"attestation_count": 890,
"average_trust_score": 87.5
},
"activity_by_day": [
{
"date": "2025-11-10",
"verifications": 180,
"attestations": 125
}
],
"recent_activity": [
{
"timestamp": "2025-11-10T14:30:00Z",
"event_type": "agent_verification",
"agent_id": "uuid",
"details": "Agent verified successfully"
}
]
}Get Security Dashboard
GET /api/v1/security/dashboardDescription: Get comprehensive security dashboard with threat detection, anomaly detection, and security metrics.
{
"threat_detection": {
"active_threats": 3,
"severity_breakdown": {
"critical": 1,
"high": 2,
"medium": 5,
"low": 10
}
},
"anomaly_detection": {
"total_anomalies": 15,
"recent_anomalies": [
{
"agent_id": "uuid",
"anomaly_type": "unusual_verification_pattern",
"severity": "medium"
}
]
},
"security_metrics": {
"total_agents_monitored": 42,
"agents_with_violations": 5,
"compliance_score": 92.5
}
}List Security Alerts
GET /api/v1/security/alertsDescription: List security alerts with pagination support. Returns alerts with severity levels (critical, high, medium, low) and status tracking.
Query Parameters:
limit(optional): Number of results (default: 20)offset(optional): Pagination offset (default: 0)
{
"alerts": [
{
"id": "uuid",
"severity": "high",
"type": "unauthorized_capability_attempt",
"agent_id": "uuid",
"description": "Agent attempted unauthorized database access",
"status": "unacknowledged",
"created_at": "2025-11-10T14:30:00Z"
}
],
"pagination": {
"total": 50,
"limit": 20,
"offset": 0
},
"summary": {
"total_alerts": 50,
"unacknowledged_count": 15
}
}Complete Endpoint List
Interactive API Documentation
Once you've deployed AIM, access the auto-generated Swagger/OpenAPI documentation at:
http://your-aim-server:8080/api/v1/docsExample for local deployment: http://localhost:8080/api/v1/docs
Coming Soon: Hosted API documentation at api.opena2a.org/docs is currently in development. For now, please use your self-hosted AIM instance documentation.