Developers
One API call for the whole retrieval stack.
REST over JSON, an envelope that always tells you what failed, scoped API keys, and a typed SDK that is dependency-free. Everything the console does, the API does — because the console is just a client.
A real search call
Hybrid retrieval, reranked, filtered and permission-scoped.
One request does dense + keyword retrieval, RRF fusion, cross-encoder reranking, a metadata filter enforced on both halves, section expansion, and ACL scoping for the end user you name.
The response carries the ranked chunks, their scores, a pipeline block explaining exactly which stages ran, and model-aware relevance bands so a score can be labelled honestly rather than against a hardcoded threshold.
The surface
Every endpoint group.
| Group | Routes | What it does |
|---|---|---|
| Auth & API keys | POST /auth/*, /api-keys | Scoped keys (trv_…), JWT for the console, per-tenant rate limits with Retry-After. |
| Projects & connections | POST /projects, /connections | A project binds a vector store, embedder, reranker and LLM — or none of them on troveGEN-Z, where they are hosted. Credentials encrypted at rest, never returned. |
| Ingestion | POST /documents/{text,file,url,crawl} | Parse, OCR, chunk, embed, upsert. Streamable over SSE with real per-stage timings. |
| Sources & sync | POST /sources, /sources/:id/sync | S3, Azure Blob, Google Drive, OAuth2 HTTP, or a plain manifest. Deletions propagate. |
| Search | POST /projects/:id/search | Hybrid dense + BM25, RRF, MMR, rerank, metadata filters, ACL scoping, related-chunk expansion. |
| Knowledge graph | GET /entities, /graph, /communities | Entities, co-occurrence edges, typed relations, communities and k-hop traversal. |
| Evaluation | POST /eval-sets, /eval-runs | Golden sets, scored runs, A/B compare with per-question regressions. |
| Conversations | POST /ask with conversationId | Threaded history with citations stored as a snapshot, so a deleted chunk cannot break the thread. |
| Ask (optional) | POST /projects/:id/ask | Cited answers, validated citations, honest refusal, groundedness scoring, SSE streaming, agentic mode. |
| Usage & health | GET /usage, /health/ready | Live entitlements and metering; readiness fails when a hard dependency is down. |
TypeScript SDK
Typed, dependency-free.
Works in Node 18+ and browsers. Retries with Retry-After, an async iterator for streaming answers, and errors that carry both a code and the request id.
MCP server
Give an AI agent your corpus.
Exposes search, cited answers, exact table aggregates and document listing over the Model Context Protocol. Read-only unless you explicitly allow writes — and every call still runs through scopes, entitlements and ACLs.
Engineering details that matter
The parts you only notice when they're wrong.
Consistent envelope
Every response is {success, data} or {success, error:{code, message, details}}. Errors carry a machine-readable code, never a stack trace.
Request correlation
Every request gets an x-request-id, echoed back and stamped on every log line for that request — including deep inside the ingestion pipeline.
Rate limits you can react to
429 with Retry-After plus X-RateLimit-Limit and -Remaining. The per-tenant budget is admin-configurable.
Streaming that stops when you do
SSE for both ingestion stages and answer generation. Disconnect and generation aborts — you are not metered for tokens you never received.
Idempotent ingestion
Queued jobs carry a stable id, so a retry after a crash resolves to the existing document instead of duplicating vectors.
Deletion really deletes
A failed vector purge aborts the whole delete so it stays retryable, rather than removing bookkeeping and orphaning vectors in your store.
Read the full reference.
Every endpoint, grouped by module, with curl, JavaScript, Python and Go samples.