Documentation

API reference

app/api/v1/* — the endpoints a real external agent process uses to authenticate, report activity, ask for a decision, and poll an approval.

Authentication

Every request needs an API key, created from Developers → API Keys in the dashboard. Keys are organization-scoped — a request acts as the organization that created the key, and can only ever reference that organization’s agents, evaluations, and approvals.

text

Authorization: Bearer aegis_live_9f3a2b1c...

Endpoints

`POST /api/v1/events`

Reports an action your agent already took (does not ask permission — see /evaluate for that). Requires only agent, eventType, and action; everything else (resource, status, traceId, durationMs, model, provider, cost, metadata) is optional. Returns 201 with the created event’s id and trace id.

`POST /api/v1/evaluate`

Asks whether an agent may perform an action. The response shape depends on the decision:

json

POST /api/v1/evaluate

{
  "agent": "finance-agent",
  "action": "refund.issue",
  "resource": "payment",
  "context": { "amount": 1250, "currency": "USD" }
}

json

{
  "decision": "REQUIRE_APPROVAL",
  "evaluationId": "eval_...",
  "approvalRequestId": "apr_...",
  "traceId": "trace_456"
}

If the decision is REQUIRE_APPROVAL, the approval request and its audit event already exist by the time this responds. A BLOCK response includes a human-readable reason.

`GET /api/v1/approvals/:id`

Polls an approval request’s current status: PENDING, APPROVED, REJECTED, EXPIRED, or CANCELLED. There is no push/webhook mechanism for this yet — poll until status is no longer PENDING (the SDK’s waitForApproval() does this for you).

`POST /api/v1/agents/register`

Optional convenience so a brand-new agent doesn’t need a dashboard visit before its first event or evaluation. Idempotent by name — calling it again returns the same agent rather than creating a duplicate.

Errors

Every error response has the same shape:

json

{
  "error": { "code": "INVALID_REQUEST", "message": "The field `action` is required." }
}

Common codes: MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY (401); INSUFFICIENT_SCOPE (403); RATE_LIMITED (429); INVALID_REQUEST, PAYLOAD_TOO_LARGE (400/413); AGENT_NOT_FOUND, APPROVAL_NOT_FOUND (404); IDEMPOTENCY_KEY_CONFLICT (409); INTERNAL_ERROR (500, never leaks a stack trace).

Rate limiting

60 requests/minute per API key. A rate-limited response includes a Retry-After header, plus x-ratelimit-limit and x-ratelimit-remaining.

Idempotency

Pass an Idempotency-Key header on /events, /evaluate, or /agents/register to make a retry safe — the same key with an equivalent body replays the original response instead of creating a duplicate. The same key with a different body is rejected as a caller error.

Key format

Keys look like aegis_live_<secret>. Only a hash of the key is ever stored — the full value is shown exactly once, at creation, and can’t be retrieved again. Never ship an API key to a browser.