# API Surface

**Last Updated:** 2026-02-01
**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` | `/api-docs/openapi.json` | OpenAPI 3.1 spec | ✅ Implemented |
| `GET` | `/swagger-ui` | Interactive API docs | ✅ 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](./storage.md) - KV layout and write path
- [Lens](./lens.md) - Read-time resolution strategies
- [API Documentation Pattern](../patterns/api-documentation.md) - Toolchain details