Skip to main content
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,
    "metadata": { "team": "ai" }
  }'

{
  "results": [
    {
      "id": "doc-1",
      "score": 0.566222,
      "label": "High Relevance",
      "metadata": { "team": "ai" },
      "text": "Get items test document"
    }
  ],
  "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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Search stored items by semantic similarity and return ranked results with scores and relevance labels.
  • Text query — query string is embedded via Ollama; search text namespaces
  • Vector query — pass a numeric array; search vector namespaces (length must match each namespace’s vector_dimension)
Search errors return "status": "error" (not "failure") with HTTP 400.

​
Headers

​
Content-Type
string
required
Must be application/json

​
Body

​
query
string | array
required
Text string or array of numbers. Text queries are embedded with Ollama. Vector queries must be non-empty and match namespace dimension.
​
namespaces
array
required
Non-empty list of namespace names to search. Each namespace must exist and match the query type (text vs vector).
​
top_k
number
default:"10"
Maximum number of results to return. Clamped to 1–100. Default is 10 if omitted.
​
threshold
number
default:"0"
Minimum score threshold (0–1). Used when kiosk_mode is true.
​
metadata
object
Optional metadata filter. Only items whose metadata matches all key/value pairs exactly are considered.
​
kiosk_mode
boolean
default:"false"
When true, threshold is required and results below the threshold are filtered out.
curl -X POST "http://localhost:8080/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "on prem retrieval",
    "namespaces": ["my-documents"],
    "top_k": 5,
    "metadata": { "team": "ai" }
  }'
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

​
results
array
Ranked search hits, highest score first. Empty array when nothing matches (including strict metadata filters).
​
results[].id
string
Item id in the namespace.
​
results[].score
number
Similarity score between 0 and 1, rounded to 6 decimal places.
​
results[].label
string
Human-readable relevance label derived from the score (see table below).
​
results[].metadata
object
Metadata stored with the item.
​
results[].text
string
Document text for text namespace hits. Empty string "" for vector namespace hits.
​
execution_time
number
Total request time in seconds.
​
timings
object
Detailed timing breakdown for each search phase, in seconds.
​
status
string
"error" on validation or search failures (HTTP 400).
​
message
string
Error description when the request fails.
{
  "results": [
    {
      "id": "doc-1",
      "score": 0.566222,
      "label": "High Relevance",
      "metadata": { "team": "ai" },
      "text": "Get items test document"
    }
  ],
  "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
  }
}

​
Relevance labels

Score rangeLabel
≥ 0.894Close Match
≥ 0.632Very High Relevance
≥ 0.447High Relevance
≥ 0.316Good Relevance
≥ 0.224Low Relevance
≥ 0.1Very Low Relevance
< 0.1Irrelevant

​
Important Notes

  • Text search requires Ollama to be running (embeddings)
  • You cannot search text namespaces with a vector query or vice versa
  • metadata filter uses exact key/value matching — typos or extra keys in stored metadata will exclude items
  • With kiosk_mode: true, set threshold (0–1) to control minimum relevance

​
Next Steps