Search API

Search across your indexed documents using the public Search API.

Search documents

Endpoint

POST /v1/docs/search

GET /v1/docs/search

Both forms accept the same parameters; the GET form takes them as query string parameters and is convenient for browser-based clients.

Request body (POST)

{
  "query": "How do I configure the database?",
  "collection": "00000000-0000-0000-0000-000000000abc",
  "limit": 10,
  "min_score": 0.5,
  "highlight": true,
  "filters": {
    "section": "guides",
    "version": "v2",
    "tags": ["engineering"],
    "doc_types": ["page"],
    "language": "en",
    "date_after": "2024-01-01",
    "date_before": "2024-12-31"
  }
}

Parameters

Parameter	Type	Required	Description
query	string	Yes	Search query
collection	UUID	No	Single collection to search. If omitted, the API key's default accessible collection is used. To span all collections the key permits, create the key with allow_all_collections=true.
limit	number	No	Max results (default 10, max 100)
offset	number	No	Pagination offset
min_score	number	No	Minimum relevance score threshold (0–1). Results below this are filtered out. Defaults to the configured server default (typically 0.5).
highlight	boolean	No	Return <mark>-wrapped query-term highlights in result snippets
filters	object	No	Narrow results by metadata (see below)

Filters object

Field	Type	Description
section	string	Match a single docs section
version	string	Match a single docs version
tags	string[]	Match any of the listed tags
doc_types	string[]	Match any of the listed document types
language	string	Match a single language code
date_after	string (YYYY-MM-DD)	Only documents created/updated on or after this date
date_before	string (YYYY-MM-DD)	Only documents created/updated on or before this date

Example usage

cURL

curl -X POST https://your-domain.com/v1/docs/search \
  -H "X-ZenSearch-Key: zsk_pk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database configuration",
    "limit": 5
  }'

JavaScript

const results = await client.search({
  query: 'database configuration',
  collection: '00000000-0000-0000-0000-000000000abc',
  limit: 5,
});

Python

results = client.search(
    query="database configuration",
    collection="00000000-0000-0000-0000-000000000abc",
    limit=5,
)

Minimum score filtering

Filter out low-relevance results using min_score:

{
  "query": "database setup",
  "min_score": 0.7
}

The min_score parameter accepts values from 0 to 1:

• 0.5 (typical default): Balanced filtering, removes results below 50% relevance
• 0.7: Strict filtering, only high-quality matches
• 0.3: Lenient filtering, includes more results
• 0: No filtering, returns all results

Error responses

Code	Description
400	Invalid request parameters
401	API key missing or invalid
402	Billing query limit exceeded
403	API key does not have access to the requested collection
429	Rate limit exceeded

Faceted search

Faceted search and facet enumeration are exposed through the dashboard API only — they are not available on the public /v1/... API key surface.

Next steps

• Chat API - Conversational search
• Authentication - API key setup