Search document chunks

Server URLloading...

POST

/api/v1/search

Send

Authorization

Header

Body

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.

Header Parameters

Response Body

curl -X POST "https://example.com/api/v1/search" \  -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": {        "b64_content": "string"      },      "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": [        {          "page_number": 0,          "x": 0,          "y": 0,          "width": 0,          "height": 0,          "unit": "string",          "origin": "string"        }      ],      "relations": [        {}      ]    }  ],  "warnings": [    {      "code": "string",      "reason": null    }  ],  "explain": {}}