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 100 requests per minute 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

The gateway reverse-proxies requests to 8 backend microservices:

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 adds CORS headers to all responses, allowing browser-based clients from any origin:

Preflight OPTIONS requests are handled automatically by the gateway and return 200 OK.

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