Skip to main content
POST
/
v1
/
search
curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": "machine learning algorithms",
    "namespaces": ["my-documents", "research-papers"],
    "top_k": 10,
    "kiosk_mode": true,
    "threshold": 0.15
  }'

{
  "results": [
    {
      "id": "doc-123",
      "score": 0.856432,
      "label": "Close Match",
      "text": "Machine learning algorithms are computational methods that enable systems to automatically learn and improve from experience.",
      "metadata": {
        "title": "Introduction to ML",
        "category": "education",
        "tags": ["machine-learning", "algorithms"]
      }
    },
    {
      "id": "doc-456",
      "score": 0.234567,
      "label": "High Relevance",
      "text": "Deep learning is a subset of machine learning that uses neural networks with multiple layers.",
      "metadata": {
        "author": "John Doe",
        "published": "2024-01-15"
      }
    }
  ],
    "execution_time": 0.451749005,
    "timings": {
        "authorize": 0.267880763,
        "parseValidate": 0.000720582,
        "validateNamespace": 0.01685079,
        "prepareVector": 0.00002464,
        "fetchData": 0.037917629,
        "earlyFilter": 0.000636537,
        "calculateDistance": 0.000419438,
        "selectCandidates": 0.000078646,
        "fetchTopCandidates": 0.000044636,
        "applyMetadataFilter": 0.00002322,
        "calculateScores": 0.001484341,
        "reorderFilter": 0.000140464,
        "formatResponse": 0.000139094,
        "total": 0.451749005
    },
    "optimization_info": {
        "fetch_strategy": "single_phase_with_early_filtering",
        "initial_fetch": "complete_data_with_early_filtering",
        "complete_fetch": "no_additional_fetch_needed"
    }
}

​
Overview

The Search API allows you to perform advanced semantic searches across one or multiple namespaces using text queries or vector embeddings. The API uses ITS (Information Theoretic Similarity) scoring to provide highly accurate relevance rankings with human-readable labels.
The Search API supports both text and vector namespaces, with automatic embedding generation for text queries and advanced binarization techniques for optimal performance.

​
Authentication

​
x-api-key
string
required
Your API key for authentication
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
query
string | array
required
Search query text or vector array. For text queries, you can include metadata and keyword filters using #key:value and #keyword syntax.
​
namespaces
array
required
Array of namespace names to search in. All namespaces must be of the same type (text or vector).
​
top_k
number
Number of top relevant chunks for your query across given namespaces. Default is 10.
​
kiosk_mode
boolean
Enable kiosk mode to filter chunks below certain relevance. When kiosk mode is on, threshold is required.
​
threshold
number
Minimum relevance score threshold (0-1) to filter out chunks below this relevance level. Required when kiosk_mode is true.

​
Advanced Filtering

​
Metadata Filters

Use #key:value format to filter by document metadata:
  • #category:tech - Find documents with category = “tech”
  • #priority:high - Find high-priority documents
  • #author:john - Find documents by author “john”

​
Keyword Filters

Use #keyword format to search within text content:
  • #important - Find documents containing “important”
  • #urgent - Find documents containing “urgent”

​
Combined Filters

Combine semantic search with multiple filters:
  • authentication #category:security #important - Security docs about authentication containing “important”
Filters must be placed at the END of your query. Use hyphens instead of spaces in filter values.
curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": "machine learning algorithms",
    "namespaces": ["my-documents", "research-papers"],
    "top_k": 10,
    "kiosk_mode": true,
    "threshold": 0.15
  }'

{
  "results": [
    {
      "id": "doc-123",
      "score": 0.856432,
      "label": "Close Match",
      "text": "Machine learning algorithms are computational methods that enable systems to automatically learn and improve from experience.",
      "metadata": {
        "title": "Introduction to ML",
        "category": "education",
        "tags": ["machine-learning", "algorithms"]
      }
    },
    {
      "id": "doc-456",
      "score": 0.234567,
      "label": "High Relevance",
      "text": "Deep learning is a subset of machine learning that uses neural networks with multiple layers.",
      "metadata": {
        "author": "John Doe",
        "published": "2024-01-15"
      }
    }
  ],
    "execution_time": 0.451749005,
    "timings": {
        "authorize": 0.267880763,
        "parseValidate": 0.000720582,
        "validateNamespace": 0.01685079,
        "prepareVector": 0.00002464,
        "fetchData": 0.037917629,
        "earlyFilter": 0.000636537,
        "calculateDistance": 0.000419438,
        "selectCandidates": 0.000078646,
        "fetchTopCandidates": 0.000044636,
        "applyMetadataFilter": 0.00002322,
        "calculateScores": 0.001484341,
        "reorderFilter": 0.000140464,
        "formatResponse": 0.000139094,
        "total": 0.451749005
    },
    "optimization_info": {
        "fetch_strategy": "single_phase_with_early_filtering",
        "initial_fetch": "complete_data_with_early_filtering",
        "complete_fetch": "no_additional_fetch_needed"
    }
}

​
ITS Scoring System

Results are scored using Information Theoretic Similarity (ITS), providing nuanced relevance measurements:
LabelScore RangeDescription
Close Matchscore ≥ 0.894Near-perfect relevance to the query
Very High Relevance0.632 ≤ score < 0.894Strongly related content
High Relevance0.447 ≤ score < 0.632Significantly related content
Good Relevance0.316 ≤ score < 0.447Moderately related content
Low Relevance0.224 ≤ score < 0.316Minimally related content
Very Low Relevance0.1 ≤ score < 0.224Barely related content
Irrelevantscore < 0.1No meaningful relation to the query

​
Response Fields

​
Search Results

​
results
array
Array of search results ordered by ITS score (descending)
​
results[].id
string
Unique identifier for the document
​
results[].score
number
ITS (Information Theoretic Similarity) score between 0 and 1
​
results[].label
string
Human-readable relevance label based on ITS score
​
results[].text
string
Original text content (only for text namespaces)
​
results[].metadata
object
Additional metadata associated with the document

​
Performance Information

​
execution_time
number
Total time taken to process the search in seconds
​
timings
object
Detailed timing breakdown for each search phase
​
optimization_info
object
Information about the search optimization strategy used

​
Use Cases

  • Document Retrieval: Find relevant documents across knowledge bases
  • Content Discovery: Explore related content with semantic understanding
  • Customer Support: Find relevant answers from support documentation
  • Research & Analysis: Search through research papers and technical documents
  • E-commerce: Product similarity and recommendation engines
  • Filtered Search: Combine semantic search with metadata and keyword filters