Search API

Search documents in your collections using hybrid retrieval.

Search Documents

POST

/api/v1/search/query

Search documents in a collection using hybrid retrieval (dense + sparse vectors). Returns ranked results. The search mode and reranking settings are determined by the collection's configuration.

Request Body

collection

required

string—Collection name to search

query

required

string—Search query text (max 1000 characters)

limit

optional

integer—Max results to return (default 10, max 30)

filters

optional

object | null—Metadata filters on indexed fields

include_metadata

optional

boolean—Include metadata in results (default true)

include_images

optional

boolean—Fetch and include figure images as base64 in metadata.figures[].image_data (default false, adds latency)

Response Fields

results

required

array—Array of search results with id, text, and metadata

queryId

required

string—Unique query identifier. Use to re-fetch the same results for free within 7 days via GET /api/v1/search/results/{queryId}

latencyMs

required

integer—Search latency in milliseconds

Re-fetch Results

Every search response includes a queryId. Use it to retrieve the same results again without being charged, for up to 7 days after the original search. The request must use the same API key.

GET

/api/v1/search/results/{queryId}

Response

Identical to the original search response, with latencyMs: 0. Includes X-Cache: hit and X-Cache-Expires headers.

Errors

404

optional

Not Found—Query ID not found or belongs to a different API key

410

optional

Gone—Cached result has expired (past 7-day window)

Filtering

Use the filters parameter to narrow search results by metadata fields. Two formats are supported and auto-detected based on the top-level keys.

Operators

Operator	Description	Example value
`eq`	Equals	`"research"`
`ne`	Not equals	`"deleted"`
`in`	Matches any in list	`["tech", "science"]`
`not_in`	Excludes values in list	`["spam", "junk"]`
`gt`	Greater than	`2020`
`gte`	Greater than or equal	`2020`
`lt`	Less than	`2025`
`lte`	Less than or equal	`2025`
`between`	Range (inclusive)	`[2020, 2025]`

Simple format

Key-value pairs where each key is a metadata field. Supports exact match, lists, ranges, and negation.

Structured DSL

Boolean combinators (and, or, not) with explicit field conditions. Supports arbitrary nesting.

Date filtering

ISO date strings (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS) are automatically detected and used for datetime range queries.

Request

Response