curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "on prem retrieval",
"namespaces": ["my-documents"],
"top_k": 5
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "product documentation #department:engineering",
"namespaces": ["my-documents"],
"top_k": 5
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "machine learning #department:engineering #semantic",
"namespaces": ["my-documents"],
"top_k": 10,
"kiosk_mode": true,
"threshold": 0.15
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": [0.1, 0.2, 0.3, 0.4, 0.5],
"namespaces": ["my-embeddings"],
"top_k": 5
}'
{
"results": [
{
"id": "a1b2c3d4e5f67890_chunk_0",
"namespace": "my-documents",
"score": 0.566222,
"label": "High Relevance",
"metadata": {
"file_id": "a1b2c3d4e5f67890",
"filename": "document.pdf",
"department": "engineering",
"summary_chunk_id": "a1b2c3d4e5f67890_summary_0",
"summary_text": "This batch summary covers the main topics in document.pdf..."
},
"text": "Sample document content about product features and architecture..."
}
],
"execution_time": 0.108234,
"timings": {
"parse_validate": 0.0,
"prepare_vector": 0.107252,
"fetch_data": 0.0,
"calculate_distance": 0.000336,
"select_candidates": 0.0,
"calculate_scores": 0.000072,
"reorder": 0.0,
"format_response": 0.0,
"total": 0.108234
}
}
{
"results": [],
"execution_time": 0.040776,
"timings": {
"parse_validate": 0.0,
"prepare_vector": 0.040736,
"fetch_data": 0.0,
"calculate_distance": 0.000033,
"select_candidates": 0.0,
"calculate_scores": 0.0,
"reorder": 0.0,
"format_response": 0.0,
"total": 0.040776
}
}
{
"status": "error",
"message": "query is required"
}
Search
Search
Semantic search across one or more namespaces using a text or vector query.
POST
/
search
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "on prem retrieval",
"namespaces": ["my-documents"],
"top_k": 5
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "product documentation #department:engineering",
"namespaces": ["my-documents"],
"top_k": 5
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "machine learning #department:engineering #semantic",
"namespaces": ["my-documents"],
"top_k": 10,
"kiosk_mode": true,
"threshold": 0.15
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": [0.1, 0.2, 0.3, 0.4, 0.5],
"namespaces": ["my-embeddings"],
"top_k": 5
}'
{
"results": [
{
"id": "a1b2c3d4e5f67890_chunk_0",
"namespace": "my-documents",
"score": 0.566222,
"label": "High Relevance",
"metadata": {
"file_id": "a1b2c3d4e5f67890",
"filename": "document.pdf",
"department": "engineering",
"summary_chunk_id": "a1b2c3d4e5f67890_summary_0",
"summary_text": "This batch summary covers the main topics in document.pdf..."
},
"text": "Sample document content about product features and architecture..."
}
],
"execution_time": 0.108234,
"timings": {
"parse_validate": 0.0,
"prepare_vector": 0.107252,
"fetch_data": 0.0,
"calculate_distance": 0.000336,
"select_candidates": 0.0,
"calculate_scores": 0.000072,
"reorder": 0.0,
"format_response": 0.0,
"total": 0.108234
}
}
{
"results": [],
"execution_time": 0.040776,
"timings": {
"parse_validate": 0.0,
"prepare_vector": 0.040736,
"fetch_data": 0.0,
"calculate_distance": 0.000033,
"select_candidates": 0.0,
"calculate_scores": 0.0,
"reorder": 0.0,
"format_response": 0.0,
"total": 0.040776
}
}
{
"status": "error",
"message": "query is required"
}
Overview
Search stored items by semantic similarity and return ranked results with scores and relevance labels.- Text query — query string is embedded via your configured provider; search text namespaces
- Vector query — pass a numeric array; search vector namespaces (length must match each namespace’s
vector_dimension)
#key:value and #keyword syntax at the end of the query (same as cloud Moorcheh).
Search errors return
"status": "error" (not "failure") with HTTP 400.Headers
Body
Text string or array of numbers. For text queries, include metadata and keyword filters using
#key:value and #keyword syntax at the end of the query.Non-empty list of namespace names to search. Each namespace must exist and match the query type (text vs vector).
When
true, threshold is required and results below the threshold are filtered out.Advanced filtering
Metadata filters
Use#key:value at the end of the query to filter by stored metadata:
#department:engineering— items wheredepartmentequalsengineering(case-insensitive)#category:tech— items wherecategoryequalstech
Keyword filters
Use#keyword (no colon) to require that word in the result text:
#important— result text must containimportant#python— result text must containpython
Combined example
authentication #category:security #important
authentication, filters metadata category=security, then keeps only hits whose text contains important.
- Filters must be placed at the end of your query
- Use hyphens instead of spaces in filter values (e.g.
#author:john-doe) - Vector queries do not support
#filters (text queries only)
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "on prem retrieval",
"namespaces": ["my-documents"],
"top_k": 5
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "product documentation #department:engineering",
"namespaces": ["my-documents"],
"top_k": 5
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": "machine learning #department:engineering #semantic",
"namespaces": ["my-documents"],
"top_k": 10,
"kiosk_mode": true,
"threshold": 0.15
}'
curl -X POST "http://localhost:8080/search" \
-H "Content-Type: application/json" \
-d '{
"query": [0.1, 0.2, 0.3, 0.4, 0.5],
"namespaces": ["my-embeddings"],
"top_k": 5
}'
For vector search, the
query array length must match vector_dimension for each namespace (for example 5 or 768 depending on how the namespace was created).Response fields
Ranked search hits, highest score first. Empty array when nothing matches (including strict metadata or keyword filters).
Metadata stored with the item. For the top relevant content chunk, may include
summary_chunk_id (bare id) and summary_text (batch summary fetched automatically). Uploaded file chunks also include file_id, filename, source, etc.{
"results": [
{
"id": "a1b2c3d4e5f67890_chunk_0",
"namespace": "my-documents",
"score": 0.566222,
"label": "High Relevance",
"metadata": {
"file_id": "a1b2c3d4e5f67890",
"filename": "document.pdf",
"department": "engineering",
"summary_chunk_id": "a1b2c3d4e5f67890_summary_0",
"summary_text": "This batch summary covers the main topics in document.pdf..."
},
"text": "Sample document content about product features and architecture..."
}
],
"execution_time": 0.108234,
"timings": {
"parse_validate": 0.0,
"prepare_vector": 0.107252,
"fetch_data": 0.0,
"calculate_distance": 0.000336,
"select_candidates": 0.0,
"calculate_scores": 0.000072,
"reorder": 0.0,
"format_response": 0.0,
"total": 0.108234
}
}
{
"results": [],
"execution_time": 0.040776,
"timings": {
"parse_validate": 0.0,
"prepare_vector": 0.040736,
"fetch_data": 0.0,
"calculate_distance": 0.000033,
"select_candidates": 0.0,
"calculate_scores": 0.0,
"reorder": 0.0,
"format_response": 0.0,
"total": 0.040776
}
}
{
"status": "error",
"message": "query is required"
}
Relevance labels
| Score range | Label |
|---|---|
| ≥ 0.894 | Close Match |
| ≥ 0.632 | Very High Relevance |
| ≥ 0.447 | High Relevance |
| ≥ 0.316 | Good Relevance |
| ≥ 0.224 | Low Relevance |
| ≥ 0.1 | Very Low Relevance |
| < 0.1 | Irrelevant |
Summary enrichment
For the top search hit (or the second hit when the first is a summary chunk), the API fetches the linked batch summary and addssummary_text to that result’s metadata. Only one result per search is enriched. /answer uses the same behavior for RAG context.
Important notes
- Text search requires your configured embedding provider (Ollama, OpenAI, or Cohere)
- You cannot search text namespaces with a vector query or vice versa
#key:valuemetadata filters are case-insensitive; keyword filters match substrings in result text- With
kiosk_mode: true, setthreshold(0–1) to control minimum relevance
Related
Was this page helpful?