API Reference
The HTTP routes the Vectorless engine serves.
The engine serves a versioned HTTP API under /v1, and a ConnectRPC surface
for health, documents and query. The tables below are the multi-tenant server binary
(cmd/server), which production ran. The engine repository also carries an
openapi.yaml
that predates some of these routes.
Documents
| Method | Path | Purpose |
|---|---|---|
POST | /v1/documents | Ingest a document (multipart upload or URL). Asynchronous: returns 202 with the document id. |
GET | /v1/documents | List documents |
GET | /v1/documents/{id} | Status and live ingest progress |
DELETE | /v1/documents/{id} | Delete a document and its stored files |
GET | /v1/documents/{id}/tree | The section tree |
GET | /v1/documents/{id}/structure | The structure with page spans |
GET | /v1/documents/{id}/llms.txt | The contents as an llms.txt file |
GET | /v1/documents/{id}/text | Plain text |
GET | /v1/documents/{id}/source | The original bytes |
GET | /v1/documents/{id}/pages | Page sizes, for drawing pincites |
GET | /v1/documents/{id}/pages/{n}/image | One page as an image (144 dpi) |
GET | /v1/sections/{id} | One section with its content |
Retrieval and answers
| Method | Path | Purpose |
|---|---|---|
POST | /v1/query | Evidence for a question: pages verbatim, then sections |
POST | /v1/query/stream | The same, streamed one event per navigation stage |
POST | /v1/query/multi · /v1/query/multi/stream | Across several documents |
POST | /v1/answer | Retrieve, answer and pincite in one round trip |
POST | /v1/answer/treewalk | Answer with the generative page walk (treewalk) |
POST | /v1/answer/store | One answer across a store of documents, with per-document citations |
GET | /v1/health · /v1/version | Liveness and build |
POST /v1/replay (return a stored answer by its trace_token) is served by the
standalone engine binary (cmd/engine). At the production commit the server
binary records traces but does not register the route.
Strategy names
Responses report the Jev navigation strategy as navigate. A per-request
strategy override accepts navigate too. In engine configuration the same
strategy is judgewalk.
Authentication and model keys
A server started with auth.mode: api_key expects Authorization: Bearer <key>.
A local engine (--local) needs none.
The answer step can use the caller's own model key, sent per request and never logged or stored:
| Header | |
|---|---|
X-LLM-Api-Key | The key |
X-LLM-Provider | anthropic, openai or gemini (optional) |
X-LLM-Model | Model name (optional) |
X-LLM-Base-Url | Gateway URL (optional) |
The Jev key is server configuration (TYPESAFE_API_KEY), not a request header.
Typed clients
The SDKs wrap ingest, documents, sections and query. /v1/answer,
page images and replay have no SDK method yet.