Skip to content

API Reference

AEGIS exposes an HTTP API gateway on port 8600. All routes require authentication.

Authentication

Every request must include a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

The API key is the value of AEGIS_API_KEY in your .env. Without a valid key, all routes return 401 Unauthorized.

Base URL

http://localhost:8600

Change the host/port with AEGIS_API_HOST and AEGIS_API_PORT in .env. When running in Docker Compose, the default is the same — port 8600 is published by the container.

Core endpoints

Health

GET /health

Returns system health. Used by CI smoke tests and the Tauri connect screen.

Response: 

{
  "status": "ok",
  "version": "1.1.0",
  "phase": 12
}

Metrics

GET /metrics

Returns runtime metrics: request count, token usage, engine status, memory layer sizes.

No body. Returns JSON.

Chat

POST /chat
Content-Type: application/json

{
  "message": "What are my active goals?",
  "project_id": "default",
  "effort": "balanced",
  "engine": null,
  "stream": true
}

Fields: - message — the user message (required) - project_id — which project context to use (optional; defaults to "default") - effort — "quick" / "balanced" / "deep" / "max" (optional; defaults to "balanced") - engine — engine ID to force (optional; AEGIS auto-routes by default) - stream — true for Server-Sent Events streaming (default); false for a single JSON response

Streaming response (Server-Sent Events): 

data: {"type": "token", "content": "Your active"}
data: {"type": "token", "content": " goals are"}
data: {"type": "tool_call", "tool": "memory_recall", "result": {...}}
data: {"type": "done", "conversation_id": "abc123"}

Non-streaming response: 

{
  "reply": "Your active goals are ...",
  "conversation_id": "abc123",
  "tokens_used": 512,
  "engine": "anthropic/claude-sonnet-4-6"
}

Tools (slash commands)

POST /tools/{tool_name}
Content-Type: application/json

{ ... tool-specific payload ... }

Runs a tool deterministically — no LLM in the loop. The handler executes directly, same code path every time.

Example — add a memory: 

POST /tools/memory
Content-Type: application/json

{
  "content": "Alice prefers email over Slack",
  "category": "people",
  "project_id": "default"
}

Example — list tools: 

GET /tools

Returns a JSON list of all available tools with their names, descriptions, and parameter schemas.

Conversations

GET /conversations
List all conversations (paginated).

GET /conversations/{conversation_id}
Get a specific conversation including its full message history.

DELETE /conversations/{conversation_id}
Delete a conversation and its messages.

Memory

GET /memory
List memories. Supports query parameters: category, project_id, search.

POST /memory
Content-Type: application/json

{
  "content": "I prefer concise replies over long explanations",
  "category": "identity",
  "project_id": "default",
  "confidence": 0.9,
  "provenance": "user-stated"
}


PATCH /memory/{memory_id}
Update a memory's content, lifecycle, tags, or pin status.

DELETE /memory/{memory_id}
Delete a memory permanently.

Knowledge base

GET /knowledge/search?q=<query>&limit=10
Full-text search across the knowledge base (documents indexed from the vault).

POST /knowledge/ingest
Content-Type: application/json

{
  "text": "Document content...",
  "title": "My Document",
  "source": "manual",
  "tags": ["reference", "architecture"]
}

Error responses

All errors return standard HTTP status codes with a JSON body:

{
  "error": "engine_unavailable",
  "message": "No capable engine found for this request",
  "request_id": "req_abc123"
}

Common status codes: - 400 — Bad request (malformed JSON, missing required field) - 401 — Unauthorized (missing or invalid API key) - 404 — Not found - 503 — Service unavailable (engine layer or a required service is down)

Request tracing

Every response includes an X-Request-ID header. This ID appears in all log lines for that request — use it to correlate the API call with log output in the Logs panel or log file.

Rate limits

There are no built-in rate limits in the API gateway itself. Limits come from whichever AI engine you've configured (Anthropic, OpenAI, etc.). The daily token budget configured in .env / the Settings panel is the practical throttle for cloud engines.

OpenAPI / Swagger

A live API schema is available at:

http://localhost:8600/docs

This is the FastAPI auto-generated Swagger UI. All routes, schemas, and example payloads are documented there interactively.