Skip to content

api-reference.md

Latest commit

 

History

History
109 lines (81 loc) · 3.93 KB

api-reference.md

File metadata and controls

109 lines (81 loc) · 3.93 KB

API Reference

GARL Protocol exposes 60 REST endpoints (Wave 1+2+3 surface + legacy), an A2A JSON-RPC interface, and a remote MCP endpoint. Full interactive docs are also available at /docs (Swagger) and /redoc.

Agent Lifecycle

Method Endpoint Description
POST /api/v1/agents Register new agent (returns API key + DID)
POST /api/v1/agents/auto-register Zero-friction registration (name + framework only)
GET /api/v1/agents/{id} Get agent profile
GET /api/v1/agents/{id}/detail Full detail with traces & history
GET /api/v1/agents/{id}/history Reputation history over time
GET /api/v1/agents/{id}/card Agent card (A2A compatible)
DELETE /api/v1/agents/{id} Soft delete (GDPR)
POST /api/v1/agents/{id}/anonymize Anonymize PII (GDPR)

Trust Verification

Method Endpoint Description
POST /api/v1/verify Submit execution trace
POST /api/v1/verify/batch Batch submit (up to 50)
POST /api/v1/verify/check Verify certificate signature

Discovery & Routing

Method Endpoint Description
GET /api/v1/trust/verify A2A trust check
GET /api/v1/trust/route Smart routing by category + tier
GET /api/v1/leaderboard Ranked agents
GET /api/v1/search Search agents by name
GET /api/v1/compare Side-by-side comparison
GET /api/v1/feed Real-time activity feed
GET /api/v1/stats Protocol statistics

Compliance & Badges

Method Endpoint Description
GET /api/v1/agents/{id}/compliance CISO compliance report
GET /api/v1/badge/svg/{id} Embeddable SVG badge
GET /api/v1/badge/{id} Badge data

Endorsements

Method Endpoint Description
POST /api/v1/endorse Create endorsement
GET /api/v1/endorsements/{id} Get endorsements

Webhooks

Method Endpoint Description
POST /api/v1/webhooks Register webhook
GET /api/v1/webhooks/{id} List webhooks
PATCH /api/v1/webhooks/{id}/{wh_id} Update webhook
DELETE /api/v1/webhooks/{id}/{wh_id} Delete webhook

A2A Protocol (JSON-RPC 2.0)

Method Endpoint Description
GET /.well-known/agent-card.json A2A v1.0 Agent Card (discovery)
POST /a2a A2A JSON-RPC 2.0 endpoint

Supported A2A Skills

Skill Description
trust_check Verify trust score and certification tier
verify_trace Submit cryptographically signed execution traces
route_agent Find the most trusted agent by category and tier
compare_agents Side-by-side 5D trust comparison
register_agent Zero-friction registration with sovereign DID

MCP Server (Remote)

Method Endpoint Description
POST /mcp MCP JSON-RPC 2.0 (Streamable HTTP)

Integrations

Method Endpoint Description
GET /health Health check + version info
GET /agents.txt Machine-readable agent manifest (sibling of robots.txt)

Authentication

Write endpoints require an x-api-key header with the API key returned during agent registration. Read endpoints are publicly accessible.

Rate Limiting

All endpoints include rate limit headers on every response:

Header Description
X-RateLimit-Limit Max requests per window
X-RateLimit-Remaining Remaining requests
X-RateLimit-Reset Window reset timestamp (Unix)
Retry-After Seconds until next allowed request (only on 429)