stemedb/ai-lookup/services/api.md

API Surface

Last Updated: 2026-02-19 Confidence: High

Summary

Episteme exposes an HTTP API via axum with auto-generated OpenAPI 3.1 documentation. The API is a thin layer that wires HTTP handlers to existing library crates (QueryEngine, Ingestor, VoteStore). Documentation is generated from the same Rust types used for serialization via utoipa derive macros.

Key Facts:

• Framework: axum with utoipa-axum for OpenAPI integration
• Crate: stemedb-api
• DTO layer converts between internal rkyv types and public serde JSON types
• OpenAPI 3.1 spec auto-generated at /api-doc/openapi.json
• Interactive docs via Swagger UI at /swagger-ui (dev mode)
• gRPC deferred; HTTP/JSON is the initial interface

File Pointers:

• crates/stemedb-api/src/lib.rs - App builder and OpenApiRouter
• crates/stemedb-api/src/dto.rs - Request/Response types (serde + ToSchema)
• crates/stemedb-api/src/handlers/ - Route handlers

Endpoints

Method	Path	Description	Status
POST	/v1/assert	Submit signed assertion, writes to WAL	✅ Implemented
POST	/v1/epoch	Create new epoch (paradigm) with content-addressed ID	✅ Implemented
POST	/v1/vote	High-throughput vote submission	✅ Implemented
GET	/v1/query	Resolve assertions via Lens	✅ Implemented
GET	/v1/skeptic	Conflict analysis (Trust but Verify)	✅ Implemented
GET	/v1/health	Service health check	✅ Implemented
GET	/v1/audit/queries	List query audit trail	✅ Implemented
GET	/v1/audit/query/{id}	Get specific query audit	✅ Implemented
GET	/v1/trace	Trace assertion lineage	✅ Implemented
GET	/v1/meter/quota	Check remaining quota	✅ Implemented
POST	/v1/meter/quota/limit	Set custom quota limit (admin)	✅ Implemented
GET	/v1/admin/circuit-breaker/{agent_id}	Get circuit breaker status	✅ Implemented
POST	/v1/admin/circuit-breaker/reset	Manually reset a circuit	✅ Implemented
GET	/v1/admin/circuit-breakers/tripped	List all Open/HalfOpen circuits	✅ Implemented
GET	/metrics	Prometheus metrics (Phase 8B)	✅ Implemented
GET	/api-docs/openapi.json	OpenAPI 3.1 spec	✅ Implemented
GET	/swagger-ui	Interactive API docs	✅ Implemented
POST	/v1/sources	Register source with metadata and optional content	✅ Implemented
GET	/v1/sources/{hash}	Get source record by hash (includes content)	✅ Implemented
PATCH	/v1/sources/{hash}/status	Update source status (deprecate/quarantine)	✅ Implemented
GET	/v1/sources	List/search sources (content stripped for performance)	✅ Implemented

Cluster Gateway Endpoints (stemedb-cluster)

Method	Path	Description	Status
POST	/v1/assert	Routed assertion to shard leader	✅ Implemented
GET	/v1/query	Routed query to shard replica	✅ Implemented
POST	/v1/vote	Routed vote to shard leader	✅ Implemented
GET	/v1/health	Gateway health check	✅ Implemented
GET	/v1/cluster/status	Cluster and node status	✅ Implemented
GET	/v1/shards/{shard_id}	Shard descriptor details	✅ Implemented
GET	/v1/route	Test subject routing	✅ Implemented
GET	/v1/admin/cluster	Cluster status (alias)	✅ Implemented
GET	/v1/admin/ranges	All shard/range assignments	✅ Implemented
POST	/v1/admin/sync	Force anti-entropy sync	✅ Implemented
GET	/metrics	Prometheus metrics (Phase 8B)	✅ Implemented

DRY Type Pipeline

stemedb-core types (rkyv)       ← Internal storage format
    |
    | impl From<> / Into<>
    v
stemedb-api DTOs (serde + ToSchema)  ← Public API contract
    |
    | utoipa derive macros
    v
OpenAPI 3.1 JSON                ← Auto-generated spec
    |
    | Widdershins (CI)
    v
Slate markdown                  ← Published docs

Related Topics

• Storage - KV layout and write path
• Lens - Read-time resolution strategies
• Observability - Prometheus metrics and admin endpoints
• API Documentation Pattern - Toolchain details