Skip to main content
POST
https://api.moorcheh.ai
/
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.1
  }'

{
  "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 results to return (default: 10)
​
threshold
number
Minimum score threshold (0-1, required when kiosk_mode is true)
​
kiosk_mode
boolean
Enable kiosk mode filtering (requires threshold parameter)

​
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.1
  }'

{
  "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:

Close Match

≥0.8 - Near-exact semantic match

Very High

≥0.4 - Strong semantic similarity

High

≥0.2 - Strong semantic connection

Good

≥0.1 - Moderate relevance

Low

≥0.05 - Weak but detectable

Very Low

≥0.01 - Minimal connection

​
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