Skip to main content
POST
/
v1
/
mcp
/
query
Query Dataset
curl --request POST \
  --url https://api.fltr.com/v1/mcp/query \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "dataset_id": "<string>",
  "limit": 123,
  "rerank": true,
  "filters": {}
}
'
{
  "results": [
    {}
  ],
  "results[].chunk_id": "<string>",
  "results[].content": "<string>",
  "results[].score": 123,
  "results[].metadata": {},
  "results[].document_id": "<string>",
  "query_time_ms": 123
}

​
Request

Performs semantic search combining vector similarity and keyword matching.

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Body

​
query
string
required
Search query or question (max 1000 characters)
​
dataset_id
string
required
Dataset to search
​
limit
integer
default:5
Number of results to return (max: 50)
​
rerank
boolean
default:false
Enable Cohere reranking for better quality
​
filters
object
Filter by metadata fields

​
Response

​
results
array
Array of search results
​
results[].chunk_id
string
Unique chunk identifier
​
results[].content
string
Text content of the chunk
​
results[].score
number
Relevance score (0-1, higher is better)
​
results[].metadata
object
Document metadata
​
results[].document_id
string
Parent document ID
​
query_time_ms
integer
Query execution time in milliseconds

​
Examples

​
Basic Query

cURL
curl -X POST https://api.fltr.com/v1/mcp/query \
  -H "Authorization: Bearer fltr_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I authenticate with FLTR?",
    "dataset_id": "ds_abc123",
    "limit": 3
  }'
Python
response = requests.post(
    "https://api.fltr.com/v1/mcp/query",
    headers={
        "Authorization": "Bearer fltr_sk_abc123...",
        "Content-Type": "application/json"
    },
    json={
        "query": "How do I authenticate with FLTR?",
        "dataset_id": "ds_abc123",
        "limit": 3
    }
)

results = response.json()
for result in results['results']:
    print(f"[{result['score']:.2f}] {result['metadata']['title']}")
    print(result['content'][:200])
JavaScript
const response = await fetch("https://api.fltr.com/v1/mcp/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fltr_sk_abc123...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "How do I authenticate with FLTR?",
    dataset_id: "ds_abc123",
    limit: 3
  })
});

const data = await response.json();
data.results.forEach(result => {
  console.log(`[${result.score}] ${result.metadata.title}`);
});

​
With Reranking

{
  "query": "authentication methods",
  "dataset_id": "ds_abc123",
  "limit": 10,
  "rerank": true
}

​
With Filters

{
  "query": "API documentation",
  "dataset_id": "ds_abc123",
  "limit": 5,
  "filters": {
    "category": "tutorial",
    "published": true
  }
}

​
Response

{
  "results": [
    {
      "chunk_id": "ch_xyz789",
      "content": "FLTR supports three authentication methods: API keys for services, OAuth 2.1 for MCP clients, and session tokens for web apps...",
      "score": 0.89,
      "metadata": {
        "title": "Authentication Guide",
        "category": "security",
        "url": "https://docs.fltr.com/auth"
      },
      "document_id": "doc_abc123"
    },
    {
      "chunk_id": "ch_abc456",
      "content": "To authenticate API requests, include your API key in the Authorization header: Bearer fltr_sk_...",
      "score": 0.82,
      "metadata": {
        "title": "API Keys",
        "category": "security"
      },
      "document_id": "doc_def456"
    }
  ],
  "query_time_ms": 45
}

​
Search Algorithm

FLTR uses hybrid search combining:
  1. Vector Search - Semantic similarity using embeddings
  2. Keyword Search - BM25 for exact matches
  3. Fusion - RRF (Reciprocal Rank Fusion) to combine results
Optional Cohere reranking provides additional quality improvement.

​
Scoring

Scores range from 0 to 1:
  • 0.9-1.0 - Excellent match
  • 0.7-0.9 - Good match
  • 0.5-0.7 - Moderate match
  • Below 0.5 - Weak match

​
Performance

  • Average latency: 50-200ms
  • With reranking: +100-300ms
  • Timeout: 10 seconds

​
Limits

  • Max query length: 1,000 characters
  • Max results: 50 per request
  • Filters: 10 fields maximum

​
Tips

  • Use natural language questions
  • Include context in your query
  • Enable reranking for better quality
  • Filter by metadata to narrow results
  • Request 3-5 results for most use cases