HTTP API
smrititantra serve (needs the [server] extra) runs a FastAPI service over
one Smrititantra instance — one process per tenant. FastAPI's own generated
docs are always live at /docs (Swagger UI) and /openapi.json; this page
is the map of what's there.
Auth
Every /v1/* route resolves a Principal from Authorization: Bearer
<key>. With no SMRITITANTRA_AUTH_TOKEN set and no API keys issued yet,
the service starts in open dev mode — every request gets a full-capability
principal with no token needed (a startup warning says so). Issue real keys
with smrititantra keys issue --org <tenant> before exposing a service.
| Route |
Purpose |
GET /healthz |
liveness: store reachability, served snapshot + age, channels, scheduler |
GET /metrics |
Prometheus-format counters/latencies |
GET /console |
the built-in operator console (recall, search, reviews, gaps, trace, snapshots, health, graph tabs) |
GET /v1/whoami |
the resolved principal for the presented token |
Recall & reads
| Route |
Purpose |
POST /v1/recall |
ask a question, get a grounded Pack |
POST /v1/recall/trace |
the same, with the scoring/routing breakdown |
GET /v1/refs/{ref} |
fetch one ref's content (ACL-trimmed) |
POST /v1/refs/batch |
fetch several refs at once (silently trims what the caller can't see) |
POST /v1/refs/grep |
full-text grep over visible content |
GET /v1/search |
hybrid search over concepts and assets |
GET /v1/assets / GET /v1/assets/{asset_ref} |
browse registered assets |
GET /v1/datasets/{dataset_id} |
fetch a materialized dataset |
Subjects (P4 personalization)
| Route |
Purpose |
GET /v1/subjects/{subject}/snapshot |
a subject's personalization state |
POST /v1/subjects/{subject}/recall |
recall on behalf of a subject |
POST /v1/subjects/{subject}/remember |
record a P4 item |
DELETE /v1/subjects/{subject}/memory |
erase a subject's personalization |
Gaps & reviews (the curation loop)
| Route |
Purpose |
GET /v1/gaps |
open knowledge gaps |
POST /v1/gaps/{gap_id}/answer |
answer a gap (routes via the write router) |
POST /v1/gaps/{gap_id}/decline |
decline a gap (decays answerability) |
GET /v1/reviews |
the curation queue |
POST /v1/reviews/{review_id}/accept / reject |
resolve a review |
Authoring & ingest
| Route |
Purpose |
POST /v1/concepts |
author a concept |
PATCH /v1/concepts/{ref} |
revise a concept |
GET /v1/concepts/{ref}/history |
a concept's revision history |
POST /v1/concepts/{ref}/rollback |
roll back to a prior revision |
POST /v1/sources/{name}/sync |
sync one source |
POST /v1/sources/{name}/mine-workload |
mine one source's query log |
POST /v1/imports/{kind} |
run a semantic importer (e.g. dbt) |
GET /v1/coverage |
the evidenced missing-concepts backlog |
GET /v1/bindings/stale |
the drift remap queue |
POST /v1/bindings/{binding_id}/verify |
prove a binding against its source |
Observability & feedback
| Route |
Purpose |
POST /v1/observe |
record an observed candidate |
POST /v1/feedback |
record recall feedback |
POST /v1/execute |
run a query through the execution edge (allowlist-gated) |
Graph
| Route |
Purpose |
POST /v1/graph/query |
traverse from a ref |
GET /v1/graph/lineage |
upstream lineage for a ref |
GET /v1/graph/impact |
downstream impact for a ref |
Learning & snapshots
| Route |
Purpose |
POST /v1/learning/consolidate |
rebuild derived views + routes, gated |
POST /v1/learning/evaluate |
score a snapshot against a golden set |
POST /v1/snapshots/compile |
compile a new snapshot |
POST /v1/snapshots/{version}/publish |
flip a version live (replay-gated) |
GET /v1/snapshots |
list registered snapshots |
POST /v1/snapshots/{version}/pin |
force a version live (the kill switch) |
Config
| Route |
Purpose |
GET /v1/config / PUT /v1/config |
read/write the tenant vocabulary config |