Answers API Reference

Two calls: load a document, then ask a question. Everything below is checked against the live handler (premiumQueryCore), not written from memory — field names, response shape, and the endpoint table all match what the API actually sends back today. The single most reliable source, if this page ever drifts, is the API’s own catalog:

GET https://api.voxell.ai/v1/answers/help

No auth required, no cost, returns the full endpoint list live from the running server. This page is the narrative version of that catalog — read it for the how and why, trust /v1/answers/help for the definitive field list.

Auth

Every call except /v1/answers/help needs a bearer key:

Authorization: Bearer $VOXELL_KEY

Get one from dash.voxell.ai/signup — no card required, Turbo is free forever.

1. Ingest a document

POST /v1/answers/{corpus}/documents

The corpus is created on first upload — there’s no separate “create corpus” call. Body:

curl https://api.voxell.ai/v1/answers/runbooks/documents \
  -H "Authorization: Bearer $VOXELL_KEY" \
  -d '{ "name": "key-rotation.md", "text": "..." }'

Voxell chunks, embeds, and indexes it — nothing else to configure. Loading more than one document at a time? POST /v1/answers/{corpus}/batch takes {documents:[{text,name}]}, up to 256 at once.

2. Ask a question

POST /v1/answers/{corpus}/query

curl https://api.voxell.ai/v1/answers/runbooks/query \
  -H "Authorization: Bearer $VOXELL_KEY" \
  -d '{ "query": "How do we rotate the signing keys?", "mode": "answer" }'

The response — every field below is real, nothing trimmed:

{
  "mode": "answer",
  "query": "How do we rotate the signing keys?",
  "answer": "Rotate from the admin console under Keys → Rotate. The previous key stays valid for 24 hours while scheduled jobs re-authenticate.",
  "chunks": [
    {
      "vector_id": "vec_8f2a1c",
      "doc_id": "runbooks/key-rotation.md",
      "chunk_index": 7,
      "score": 0.91,
      "text": "To rotate a signing key: open Admin → Keys → Rotate. The previous key stays valid for 24h while…"
    }
  ],
  "retrieval": { "health": "healthy", "top_score": 0.91 }
}

answer is only present when mode: "answer". Ask with mode: "vectors" when your own model wants to write the answer from raw passages instead.

retrieval.health is "healthy", "weak", or "absent" — read off the top retrieval score, not the VQS composite. "weak"/"absent" responses carry a note explaining what’s missing; a "healthy" response doesn’t need one, so it’s omitted rather than sent empty. This is how you tell a bad answer from a bad corpus: a weak or absent retrieval means the documents don’t cover the question, not that the model got it wrong.

add_query_instruction

Optional, default false, honoured on the precision tier. true prepends a fixed retrieval instruction to the text embedded for this query only — the raw query still drives keyword matching and the answer itself. On a 70-question set of full-sentence questions it moved nDCG@10 from 0.757 to 0.784, and 5 of those 70 questions got worse. Short keyword queries aren’t characterized this way — the prefix is fixed length, so the shorter your query, the more of the embedded text it makes up. We never set this for you and never infer it. Measure it on your own corpus before you leave it on.

The rest of the catalog

Everything else GET /v1/answers/help documents, for when a document needs editing rather than just reading:

Corpus-quality scoring (VQS), per-passage grading, and what a weak score means for retrieval are covered on the VQS page — assess a corpus there before you decide what to fix.

Errors

Standard shape, no surprises: 401 missing/invalid key, 402 out of prepaid balance, 403 the tier isn’t enabled for your account (precision needs the Answers Max add-on), 404 corpus or document not found, 429 rate limited. Retry 429/5xx with backoff; don’t retry 4xx.