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
  }'

curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": "authentication #category:security",
    "namespaces": ["tech-docs", "security-guides"],
    "top_k": 15,
    "kiosk_mode": true,
    "threshold": 0.2
  }'

curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
    "namespaces": ["vector-embeddings"],
    "top_k": 5,
    "kiosk_mode": false
  }'

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 #category:research #published",
    "namespaces": ["research-papers", "academic-docs"],
    "top_k": 25,
    "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"
    }
}

{
  "status": "failure",
  "message": "Bad Request: query field is required"
}

{
  "status": "failure",
  "message": "Forbidden: Missing API Key information.",
  "timings": {
    "authorize": 0.001,
    "total": 0.002
  }
}

{
  "status": "failure",
  "message": "Forbidden"
}

{
  "status": "failure",
  "message": "Namespace 'my-namespace' not found"
}

{
  "status": "failure",
  "message": "API request limit reached for Professional plan (1000000 requests). Current usage: 1000000. Please upgrade your subscription for higher limits.",
  "current_usage": 1000000,
  "limit": 1000000
}

{
  "status": "failure",
  "message": "Internal Server Error processing search."
}

POST

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
  }'

curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": "authentication #category:security",
    "namespaces": ["tech-docs", "security-guides"],
    "top_k": 15,
    "kiosk_mode": true,
    "threshold": 0.2
  }'

curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
    "namespaces": ["vector-embeddings"],
    "top_k": 5,
    "kiosk_mode": false
  }'

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 #category:research #published",
    "namespaces": ["research-papers", "academic-docs"],
    "top_k": 25,
    "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"
    }
}

{
  "status": "failure",
  "message": "Bad Request: query field is required"
}

{
  "status": "failure",
  "message": "Forbidden: Missing API Key information.",
  "timings": {
    "authorize": 0.001,
    "total": 0.002
  }
}

{
  "status": "failure",
  "message": "Forbidden"
}

{
  "status": "failure",
  "message": "Namespace 'my-namespace' not found"
}

{
  "status": "failure",
  "message": "API request limit reached for Professional plan (1000000 requests). Current usage: 1000000. Please upgrade your subscription for higher limits.",
  "current_usage": 1000000,
  "limit": 1000000
}

{
  "status": "failure",
  "message": "Internal Server Error processing search."
}

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

string

required

Your API key for authentication

string

required

Must be application/json

Body Parameters

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.

array

required

Array of namespace names to search in. All namespaces must be of the same type (text or vector).

number

Number of top relevant chunks for your query across given namespaces. Default is 10.

boolean

Enable kiosk mode to filter chunks below certain relevance. When kiosk mode is on, threshold is required.

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
  }'

curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": "authentication #category:security",
    "namespaces": ["tech-docs", "security-guides"],
    "top_k": 15,
    "kiosk_mode": true,
    "threshold": 0.2
  }'

curl -X POST "https://api.moorcheh.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "query": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
    "namespaces": ["vector-embeddings"],
    "top_k": 5,
    "kiosk_mode": false
  }'

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 #category:research #published",
    "namespaces": ["research-papers", "academic-docs"],
    "top_k": 25,
    "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"
    }
}

{
  "status": "failure",
  "message": "Bad Request: query field is required"
}

{
  "status": "failure",
  "message": "Forbidden: Missing API Key information.",
  "timings": {
    "authorize": 0.001,
    "total": 0.002
  }
}

{
  "status": "failure",
  "message": "Forbidden"
}

{
  "status": "failure",
  "message": "Namespace 'my-namespace' not found"
}

{
  "status": "failure",
  "message": "API request limit reached for Professional plan (1000000 requests). Current usage: 1000000. Please upgrade your subscription for higher limits.",
  "current_usage": 1000000,
  "limit": 1000000
}

{
  "status": "failure",
  "message": "Internal Server Error processing search."
}

ITS Scoring System

Results are scored using Information Theoretic Similarity (ITS), providing nuanced relevance measurements:

Label	Score Range	Description
Close Match	score ≥ 0.894	Near-perfect relevance to the query
Very High Relevance	0.632 ≤ score < 0.894	Strongly related content
High Relevance	0.447 ≤ score < 0.632	Significantly related content
Good Relevance	0.316 ≤ score < 0.447	Moderately related content
Low Relevance	0.224 ≤ score < 0.316	Minimally related content
Very Low Relevance	0.1 ≤ score < 0.224	Barely related content
Irrelevant	score < 0.1	No meaningful relation to the query

Response Fields

Search Results

array

Array of search results ordered by ITS score (descending)

string

Unique identifier for the document

number

ITS (Information Theoretic Similarity) score between 0 and 1

string

Human-readable relevance label based on ITS score

string

Original text content (only for text namespaces)

object

Additional metadata associated with the document

Performance Information

number

Total time taken to process the search in seconds

object

Detailed timing breakdown for each search phase

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

Upload Text Data - Add searchable text documents
Upload Vector Data - Add searchable vector embeddings
List Namespaces - View available namespaces for searching

Delete Namespace Generate AI Answer

Getting Started

Namespace Management

Search & Discovery

AI Generation

Data Operations

File storage

Overview

Authentication

Body Parameters

Advanced Filtering

Metadata Filters

Keyword Filters

Combined Filters

ITS Scoring System

Response Fields

Search Results

Performance Information

Use Cases

​Overview

​Authentication

​Body Parameters

​Advanced Filtering

​Metadata Filters

​Keyword Filters

​Combined Filters

​ITS Scoring System

​Response Fields

​Search Results

​Performance Information

​Use Cases

​Related Endpoints

Overview

Authentication

Body Parameters

Advanced Filtering

Metadata Filters

Keyword Filters

Combined Filters

ITS Scoring System

Response Fields

Search Results

Performance Information

Use Cases

Related Endpoints