API Overview

The AEGIS API provides programmatic access to the platform’s compliance intelligence, agent execution, knowledge graph, and filing management capabilities. All API traffic is routed through a single Go-based API gateway.

Base URL

All API requests are made to the gateway at:

http://localhost:8000/api/v1

In production, replace localhost:8000 with your deployment’s domain.

Request Format

• All request and response bodies use JSON (Content-Type: application/json).
• File uploads (CSV import) use multipart/form-data.
• SSE streaming endpoints return text/event-stream.

Authentication

Every request (except POST /api/v1/auth/token and health checks) must include a JWT, supplied either as:

• Authorization header: Authorization: Bearer <token>
• Cookie: the aegis_token cookie set at login (used by browser SSE clients)

Obtain a token by posting email + password to POST /api/v1/auth/token. See Authentication for the full auth flow.

Versioning

The API uses URL-based versioning with the /api/v1 prefix. All current endpoints live under v1. When breaking changes are introduced, a new version prefix (e.g., /api/v2) will be added while v1 remains available during a deprecation period.

Rate Limiting

The gateway enforces a rate limit of 600 requests per minute (burst 100) per authenticated identity. Exceeding this limit returns 429 Too Many Requests. See Rate Limiting for details and retry strategies.

Common Patterns

Pagination

List endpoints that return large result sets support pagination:

Paginated responses include:

{
  "data": [...],
  "total": 127,
  "page": 1,
  "page_size": 20
}

Sorting

Many list endpoints accept sorting parameters:

Filtering

List endpoints accept query parameters for filtering. Filters are combined with AND logic. Common filter parameters include status, entity_id, tenant_id, and endpoint-specific fields.

Tenant Scoping

Most endpoints accept a tenant_id query parameter (defaults to "default" in local development). In production, tenant scoping is derived from the authenticated user’s JWT claims.

Service Architecture

Every public request goes to the gateway under the /api/v1 prefix; the gateway strips the prefix, applies auth + rate limiting, and reverse-proxies to the backend microservices. The frontend calls these same /api/v1/* paths same-origin — there is no per-service public URL.

The memory-service (8002) and sandbox-runner (unix socket) have no public gateway routes — they are reached service-to-service only. A few internal routes are deliberately not exposed: /auth/resolve, the KG raw-Cypher /query, and /rules/evaluate all return 404 at the gateway even though the backends implement them.

Health Check

The gateway exposes its own health endpoint that does not require authentication:

curl http://localhost:8000/health

{
  "status": "ok",
  "service": "api-gateway"
}

CORS

The gateway sets CORS headers on requests whose Origin matches its allowlist. The allowlist comes from the CORS_ALLOW_ORIGINS environment variable (comma-separated), defaulting to * for local development. When a specific allowlist is configured, only exactly-listed origins are reflected back (with Vary: Origin) and unknown origins receive no Access-Control-Allow-Origin header.

Preflight OPTIONS requests are handled automatically by the gateway and return 200 OK. The gateway strips any CORS headers the backends set, so it is the single source of truth for CORS. Restrict CORS_ALLOW_ORIGINS to your real front-end origins in production.

Next Steps

• Authentication — set up email/password login and the JWT token flow
• Rate Limiting — understand request limits
• Errors — error response format and status codes
• SSE Events — real-time streaming event types
• Endpoint Reference — detailed endpoint documentation