Retrieval

Search a knowledge base to retrieve relevant document chunks. This endpoint supports semantic (vector), keyword, and hybrid search modes. Use it to build custom RAG pipelines or to inspect what context would be retrieved for a given query.

Endpoint

POST https://api.tensoras.ai/v1/knowledge-bases/{kb_id}/retrieve

Authentication

Authorization: Bearer tns_your_key_here

Request Body

Parameter	Type	Required	Default	Description
`kb_id`	string	Yes	—	The knowledge base ID (path parameter).
`query`	string	Yes	—	The search query text.
`top_k`	integer	No	`10`	The maximum number of results to return. Max: 100.
`search_type`	string	No	`"hybrid"`	The search strategy. One of `"hybrid"`, `"vector"`, `"keyword"`.
`filters`	object	No	—	Metadata filters to narrow results. See filters below.
`include_metadata`	boolean	No	`true`	Whether to include document metadata in the results.
`min_score`	number	No	`0.0`	Minimum relevance score threshold. Results below this score are excluded.

Search Types

Type	Description
`hybrid`	Combines vector similarity search with keyword matching for the best overall relevance. This is the recommended default.
`vector`	Pure semantic search using embedding similarity. Best for finding conceptually related content even when exact keywords differ.
`keyword`	Traditional keyword-based search using BM25 scoring. Best when you need exact term matching.

Filters

Use metadata filters to narrow down search results. Filters are applied before scoring.

{
  "filters": {
    "document_name": "user-guide.pdf",
    "source_type": "file_upload",
    "metadata": {
      "department": "engineering",
      "version": {"$gte": 2}
    }
  }
}

Filter Field	Type	Description
`document_name`	string	Filter by exact document name.
`document_id`	string	Filter by document ID.
`source_type`	string	Filter by data source type.
`metadata`	object	Filter by custom metadata fields. Supports exact match and operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`.

Response Body

{
  "object": "list",
  "results": [
    {
      "chunk_id": "chunk_abc123",
      "text": "To configure SSL certificates, navigate to Settings > Security > SSL/TLS. Upload your certificate file and private key...",
      "score": 0.9234,
      "metadata": {
        "department": "engineering",
        "version": 3
      },
      "document_id": "doc_xyz789",
      "document_name": "admin-guide.pdf"
    },
    {
      "chunk_id": "chunk_def456",
      "text": "SSL certificates can be renewed automatically by enabling auto-renewal in the dashboard...",
      "score": 0.8756,
      "metadata": {
        "department": "engineering",
        "version": 3
      },
      "document_id": "doc_xyz789",
      "document_name": "admin-guide.pdf"
    }
  ],
  "query": "How do I configure SSL certificates?",
  "search_type": "hybrid",
  "knowledge_base_id": "kb_abc123"
}

Field	Type	Description
`object`	string	Always `"list"`.
`results`	array	The retrieved chunks, sorted by relevance score in descending order.
`results[].chunk_id`	string	The unique identifier of the chunk.
`results[].text`	string	The text content of the chunk.
`results[].score`	number	The relevance score between 0 and 1. Higher is more relevant.
`results[].metadata`	object	Document metadata, included when `include_metadata` is `true`.
`results[].document_id`	string	The ID of the source document.
`results[].document_name`	string	The name of the source document.
`query`	string	The original query text.
`search_type`	string	The search type that was used.
`knowledge_base_id`	string	The knowledge base that was searched.

Examples

Basic Retrieval

curl

curl https://api.tensoras.ai/v1/knowledge-bases/kb_abc123/retrieve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tns_your_key_here" \
  -d '{
    "query": "How do I configure SSL certificates?",
    "top_k": 5,
    "search_type": "hybrid"
  }'

Python

import requests
 
response = requests.post(
    "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123/retrieve",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer tns_your_key_here",
    },
    json={
        "query": "How do I configure SSL certificates?",
        "top_k": 5,
        "search_type": "hybrid",
    },
)
 
results = response.json()["results"]
for result in results:
    print(f"[{result['score']:.4f}] {result['document_name']}")
    print(f"  {result['text'][:100]}...")
    print()

Node.js

const response = await fetch(
  "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123/retrieve",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer tns_your_key_here",
    },
    body: JSON.stringify({
      query: "How do I configure SSL certificates?",
      top_k: 5,
      search_type: "hybrid",
    }),
  }
);
 
const { results } = await response.json();
for (const result of results) {
  console.log(`[${result.score.toFixed(4)}] ${result.document_name}`);
  console.log(`  ${result.text.slice(0, 100)}...`);
  console.log();
}

Retrieval with Filters

curl

curl https://api.tensoras.ai/v1/knowledge-bases/kb_abc123/retrieve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tns_your_key_here" \
  -d '{
    "query": "deployment best practices",
    "top_k": 10,
    "search_type": "vector",
    "filters": {
      "metadata": {
        "department": "engineering",
        "version": {"$gte": 2}
      }
    },
    "min_score": 0.5
  }'

Python

import requests
 
response = requests.post(
    "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123/retrieve",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer tns_your_key_here",
    },
    json={
        "query": "deployment best practices",
        "top_k": 10,
        "search_type": "vector",
        "filters": {
            "metadata": {
                "department": "engineering",
                "version": {"$gte": 2},
            }
        },
        "min_score": 0.5,
    },
)
 
results = response.json()["results"]
print(f"Found {len(results)} results above threshold")
for result in results:
    print(f"  [{result['score']:.4f}] {result['document_name']}: {result['text'][:80]}...")

Node.js

const response = await fetch(
  "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123/retrieve",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer tns_your_key_here",
    },
    body: JSON.stringify({
      query: "deployment best practices",
      top_k: 10,
      search_type: "vector",
      filters: {
        metadata: {
          department: "engineering",
          version: { $gte: 2 },
        },
      },
      min_score: 0.5,
    }),
  }
);
 
const { results } = await response.json();
console.log(`Found ${results.length} results above threshold`);
for (const result of results) {
  console.log(
    `  [${result.score.toFixed(4)}] ${result.document_name}: ${result.text.slice(0, 80)}...`
  );
}

Full RAG Pipeline

Combine retrieval with chat completions for a complete RAG implementation.

Python

import requests
from openai import OpenAI
 
API_BASE = "https://api.tensoras.ai/v1"
API_KEY = "tns_your_key_here"
 
# Step 1: Retrieve relevant context
retrieval_response = requests.post(
    f"{API_BASE}/knowledge-bases/kb_abc123/retrieve",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
    json={
        "query": "What is the refund policy?",
        "top_k": 5,
        "search_type": "hybrid",
    },
)
 
chunks = retrieval_response.json()["results"]
context = "\n\n---\n\n".join([chunk["text"] for chunk in chunks])
 
# Step 2: Generate a response using the retrieved context
client = OpenAI(base_url=API_BASE, api_key=API_KEY)
 
response = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[
        {
            "role": "system",
            "content": f"Answer the user's question based on the following context. If the answer is not in the context, say so.\n\nContext:\n{context}",
        },
        {"role": "user", "content": "What is the refund policy?"},
    ],
    temperature=0.3,
)
 
print(response.choices[0].message.content)

Error Handling

{
  "error": {
    "message": "Knowledge base 'kb_abc123' not found",
    "type": "not_found_error",
    "param": "kb_id",
    "code": "knowledge_base_not_found"
  }
}

Data Sources Ingestion Jobs