API Reference
The Alexandria EE HTTP API is implemented in Go (api-go/). It uses the chi router, JWT-based authentication, RBAC with super-admin bypass, and forwards orchestration calls to the Rust orchestrator over gRPC.
Base URL
https://<your-host>:<port>
Default port for self-managed deploys is 8080.
Authentication
All authenticated endpoints expect a Bearer JWT in the Authorization header:
Authorization: Bearer <access-token>
Three token classes:
| Class | Issued by | Lifetime | Where accepted |
|---|---|---|---|
| Access token | POST /auth/login (or federation callback) | 15 min (default) | All user routes |
| Refresh token | POST /auth/login | 30 days (default) | POST /auth/refresh only |
| Agent token | POST /v1/agent-token | 1 hour (default) | /v1/agent/* routes only |
See Auth for the full flow including refresh, logout, and WebAuthn.
Permission model
Every authenticated request is gated by a three-layer intersection:
effective_tools = agent.allowed_tools ∩ user.allowed_tools ∩ server.ceiling
Per-tenant deployments apply a tenant ceiling before this intersection. super_admin bypasses intersection entirely.
The intersection is computed and baked into the agent JWT at mint time, so revoking a permission requires either bumping the user's token_version (invalidates all live access tokens) or letting the agent JWT expire.
See the Permission Model for the full algorithm and edge cases.
OpenAPI spec
The full machine-readable spec is at /openapi.yaml. It covers:
- 162 HTTP operations
- 34 component schemas
- All security schemes, status codes, and request/response shapes
Use it with Swagger UI, Redoc, Postman, or generated client SDKs.
Sections
| Section | Covers |
|---|---|
| Auth | Login, refresh, logout, setup, agent-token, WebAuthn |
| Federation | OIDC, SAML, CLI device-code flow |
| Agents | Agent CRUD, tool grants, revocation, approval-required tools |
| Query | POST /v1/query, POST /v1/stream (SSE), triggers |
| OpenAI | GET /v1/models (agents), GET /v1/backends, POST /v1/chat/completions, POST /v1/embeddings |
| MCP | JSON-RPC 2.0 dispatch, agent-scoped dispatch, server management |
| Chats | Chat session CRUD |
| Sessions | Token / login session inspection and revocation |
| Permissions | Permission and plan request workflow |
| Tenants | Multi-tenant CRUD and ceiling management |
| LLM | LLM backend CRUD, deploy, ping, logs, sync |
| Admin | Users, audit, license, diagnostics, notifications, telemetry, changesets, workflows, groups, roles, skills, health, metrics |
| SCIM | SCIM 2.0 user and group provisioning |
| Ingest | Tool-facing ingest endpoints (tool JWT required) |
Conventions
- All endpoints return JSON unless explicitly noted (
/v1/streamis SSE,/admin/audit/exportis NDJSON). - Error responses use
{"error": "<code>", "message": "<human-readable>"}. - Times are ISO-8601 UTC (
2026-05-14T18:00:00Z). - Pagination uses
?limit=N&cursor=<opaque>where applicable. - All mutating operations are audited; see Compliance for the audit-chain guarantees.