Ask a question over your documents
Ask a question over your documents
Retrieval-augmented generation: searches your indexed corpus, then generates an LLM answer grounded in the retrieved passages.
Modes:
stream=false(default): returns a single JSON response withresultsandanswer.stream=true: returns Server-Sent Events —event: sources(retrieved chunks),event: token(answer tokens),event: done(stream complete), orevent: error(generation failure).
Model: defaults to mistral-large-latest (flagship, best answer quality).
Pass model=isaac-ft5 for the lighter, faster Context212 fine-tune.
Company-specific custom models (custom-{company_id}-{uuid}) are also accepted.
Any other value returns 422.
Relevance scoring: relevance scoring always runs in scoring_and_filtering
mode — candidates are scored for relevance and only those above the quality
threshold are used as context. score equals the relevance score
(scores.relevance, 0–1). Results are returned in descending order of score.
If the scoring model is temporarily unavailable, score falls back to the
combined retrieval score (higher is better, no fixed upper bound) and
scores.relevance is null.
Scoping: same rules as /api/v1/search — use workspace_id and/or tag_id
to narrow results, or file_id to target specific files. file_id cannot be
combined with workspace_id or tag_id (422).
If the reranker is temporarily unavailable, results are returned in retrieval
order and each result item includes a warnings array. Each warning has a
code matching the degraded scores key (e.g. relevance) and a reason
classifying the failure: model_not_found, timeout, service_error, or
unknown. The warnings key is absent from result items when all pipeline
steps succeed.
Billing: 1 search-with-generation credit per request.
Authorization
bearerAuth Console session token (Authorization: Bearer <session>) or product API key (Authorization: Bearer <api-key> or x-api-key). Session tokens are validated via Better Auth get-session; API keys against the shared database.
In: header
Header Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request body (AskRequest).
Response Body
curl -X POST "https://example.com/api/v1/ask" \ -H "Content-Type: application/json" \ -d '{ "query": "string" }'{ "results": [ { "chunk_id": "55e808e1-8ddc-49f1-92c9-6bbdcdff1c83", "content": "string", "score": 0, "scores": { "text": 0, "vision": 0, "keyword": 0, "multivector": 0, "relevance": 0 }, "image": null, "source": { "file_id": 0, "filename": "string", "title": "string", "mime_type": "string", "size_bytes": 0, "page_start": 0, "page_end": 0, "total_pages": 0, "tags": [ { "id": 0, "name": "string" } ], "external_metadata": { "external_id": "string", "external_url": "string", "additional_metadata": {} } }, "workspace": { "id": 0, "name": "string" }, "bboxes": null, "warnings": null } ], "answer": "string"}API Errors
Error codes, response format, and troubleshooting for the Context212 API
Search document chunks POST
Search document chunks Embedding → vector search → optional relevance scoring, returning ranked chunks with provenance. No LLM generation is performed. Billing: 1 retrieval credit per request. **Relevance scoring (`relevance_scoring`):** controls the relevance scoring stage. - `scoring_and_filtering` (default): Score candidates for relevance and only return those above the quality threshold. - `scoring_only`: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. - `none`: Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit `relevance_scoring` for the default; send `none` to skip scoring. **Result ordering:** results are returned in descending order of `score`. With `scoring_and_filtering` or `scoring_only`, `score` equals the relevance score (`scores.relevance`, 0–1). With `none`, `score` is the combined retrieval score (higher is better, no fixed upper bound). If the scoring model is temporarily unavailable, results are returned in retrieval order and a `warnings` array is included. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent when all pipeline steps succeed. **Scoping:** use `workspace_id` and/or `tag_id` to narrow results, or `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id` (422). A 403 is returned when filters resolve to no authorized resources. When no filters are provided, search runs across all documents authorized for the API key. **Modes:** - `text` (default): hybrid text search - `vision`: VLM-embedded page image search **Images:** set `include_image=true` to receive a base64-encoded page image with each result. In text mode the image is fetched from the VisionChunk covering the chunk's start page (empty string if no vision index exists for that page). **Bounding boxes (PDF only):** set `include_bboxes=true` to append a `bboxes` array to each result, giving the merged rectangles of the chunk's text on the source PDF (raw PDF points, top-left origin with y extending downward) so you can overlay highlights without re-locating the chunk. One rectangle per logical group; a chunk spanning two pages produces at least one rectangle per page. Available for PDF documents in text mode only — returns an empty list for non-PDF, vision-mode, or pre-v2.2.1 chunks. When `include_bboxes=false` (default) the `bboxes` key is omitted.