kognita|Docs

API reference

Search

Three search endpoints return the same ranked result shape: full-text, semantic, and hybrid. Read Search concepts to understand when to use each mode.

Base path

https://api.kognita.ai/api/v1/knowledge-bases/{id}/search
POST
/v1/knowledge-bases/{id}/search/full-text

Full-text keyword search

POST
/v1/knowledge-bases/{id}/search/semantic

Vector similarity search

POST
/v1/knowledge-bases/{id}/search/hybrid

Weighted blend of full-text + semantic

Shared response schema

All three endpoints return the same SearchResponse:

{
  "success": true,
  "data": [
    {
      "id": "chunk_001",          // chunk ID
      "contentChunk": "...",      // text of the matching chunk
      "score": 0.94               // relevance score, higher = more relevant
    }
  ]
}

Full-text search

POST
/api/v1/knowledge-bases/{id}/search/full-text

Tokenizes the query and matches against a PostgreSQL full-text index. No embedding model call is made, giving it the lowest latency of the three modes.

Path parameters

ParameterTypeDescription
idrequired
string(path)Knowledge base ID.

Request body

ParameterTypeDescription
queryrequired
string(body)The search query string.
limit
integer(body)Maximum number of results to return. Default: 10. Max: 100.
metadataFilter
object(body)Optional key/value pairs to filter results by metadata fields set at ingest time.
Request example
{
  "query": "knowledge base API",
  "limit": 10,
  "metadataFilter": { "source": "docs" }
}

Responses

200OK
{
  "success": true,
  "data": [
    { "id": "chunk_001", "contentChunk": "...", "score": 1.2 },
    { "id": "chunk_003", "contentChunk": "...", "score": 0.9 }
  ]
}
400Bad Request
404Knowledge base not found
500Internal Server Error

Semantic search

POST
/api/v1/knowledge-bases/{id}/search/semantic

Embeds the query using the knowledge base's configured embedding model and returns the nearest neighbors by cosine similarity. Understands synonyms and paraphrases.

Request body

ParameterTypeDescription
queryrequired
string(body)The natural language query.
limit
integer(body)Maximum results. Default: 10. Max: 100.
metadataFilter
object(body)Optional key/value pairs to filter results by metadata fields set at ingest time.
Request example
{
  "query": "how do I store knowledge for my AI assistant?",
  "limit": 5,
  "metadataFilter": { "source": "docs" }
}

Responses

200OK
{
  "success": true,
  "data": [
    { "id": "chunk_001", "contentChunk": "...", "score": 0.94 }
  ]
}
400Bad Request
404Not Found
502Bad Gateway

Hybrid search

POST
/api/v1/knowledge-bases/{id}/search/hybrid

Combines full-text and semantic scores with a configurable weight. Recommended as the default for most RAG pipelines.

Request body

ParameterTypeDescription
queryrequired
string(body)The search query.
limit
integer(body)Maximum results. Default: 10. Max: 100.
semanticWeight
number [0–1](body)How much weight to give semantic similarity vs full-text. 0 = full-text only, 1 = semantic only. Default: 0.5.
metadataFilter
object(body)Optional key/value pairs to filter results by metadata fields set at ingest time.
Request example
{
  "query": "what is a knowledge base?",
  "limit": 10,
  "semanticWeight": 0.7,
  "metadataFilter": { "source": "docs" }
}

Choosing semanticWeight

0.0Pure full-text. Best when queries use exact domain terms.
0.3Mostly keyword, some semantic boost. Good for product search.
0.5Balanced (default). Safe starting point.
0.7Mostly semantic. Recommended for natural language Q&A.
1.0Pure semantic. Use when you want concept matching only.

Responses

200OK
{
  "success": true,
  "data": [
    { "id": "chunk_002", "contentChunk": "...", "score": 0.87 },
    { "id": "chunk_001", "contentChunk": "...", "score": 0.82 }
  ]
}
400Bad Request
404Not Found
502Bad Gateway
← ContentSearch concepts →