Base URL & Authentication
Base URL: http://localhost:4000/api
# Two authentication methods:
# 1. API Key (recommended for SDK/automation)
curl -H "X-API-Key: ag_prod_your_key_here" ...
# 2. Clerk JWT (used by the dashboard)
curl -H "Authorization: Bearer <clerk_jwt>" ...All endpoints require authentication. API Keys are prefixed with ag_prod_ (live) or ag_test_ (test). Generate keys from Settings → API Keys.
Response Format
Success (single item)
{ "data": { "id": "uuid", ... } }Success (list)
{ "data": [...], "meta": { "total": 42 } }Error
{ "error": { "code": "VALIDATION_ERROR", "message": "...", "fields": { ... } } }Agents
Traces
Policies
Access Grants
Webhooks
Rate Limits
| Route Group | Limit | Window |
|---|---|---|
| Control plane (agents, policies, etc.) | 100 requests | per minute |
| Trace ingestion | 1000 requests | per minute |
When rate limited, the API returns 429 Too Many Requests with a Retry-After header. The frontend API client and SDKs handle retries automatically with exponential backoff.