Search Endpoints
The Search API provides semantic and keyword search capabilities across schemas, conversations, knowledge bases, and documentation. It uses Qdrant vector storage for embedding-based retrieval combined with keyword filtering for hybrid search results.
Semantic Search
Performs a semantic search across schema embeddings, conversation history, and knowledge bases using vector similarity.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/search/semantic |
| Auth | JWT required |
Request Body
{
"query": "customer revenue by region",
"tenant_id": "acme-corp",
"collections": ["schema", "conversations", "knowledge"],
"top_k": 10,
"min_score": 0.7,
"filters": {
"schema_type": "table"
}
}Response
{
"results": [
{
"id": "tbl-sales-001",
"collection": "schema",
"content": "sales table with columns: customer_id, region, revenue, order_date",
"score": 0.94,
"metadata": {
"table_name": "sales",
"schema": "public",
"column_count": 12
}
}
],
"total": 5,
"execution_time_ms": 45
}Schema Search
Searches specifically within the tenant schema catalog for tables, columns, and relationships.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/search/schema |
| Auth | JWT required |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | yes | Search query |
| tenant_id | string | yes | Tenant identifier |
| type | string | no | Filter by type (table, column, relationship) |
| limit | integer | no | Max results (default 20) |
Response
{
"results": [
{
"type": "table",
"name": "customers",
"schema": "public",
"description": "Customer master data",
"columns": ["id", "name", "region", "tier"],
"relevance_score": 0.89
}
]
}Conversation Search
Searches within past conversation sessions for relevant questions and answers.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/search/conversations |
| Auth | JWT required |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | yes | Search query |
| tenant_id | string | yes | Tenant identifier |
| user_id | string | no | Filter by user |
| date_from | string | no | ISO date lower bound |
| date_to | string | no | ISO date upper bound |
| limit | integer | no | Max results (default 10) |
Response
{
"results": [
{
"session_id": "sess-xyz789",
"question": "What is our customer churn rate?",
"answer": "The current customer churn rate is 4.2%...",
"timestamp": "2025-03-10T14:30:00Z",
"relevance_score": 0.87
}
]
}Knowledge Base Search
Searches the knowledge base for documentation, business definitions, and domain context.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/search/knowledge |
| Auth | JWT required |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | yes | Search query |
| tenant_id | string | yes | Tenant identifier |
| category | string | no | Filter by category (glossary, metric, documentation) |
| limit | integer | no | Max results (default 10) |
Hybrid Search
Combines semantic vector search with keyword filtering for maximum relevance.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/search/hybrid |
| Auth | JWT required |
Request Body
{
"query": "monthly active users by plan",
"tenant_id": "acme-corp",
"semantic_weight": 0.7,
"keyword_weight": 0.3,
"top_k": 10,
"collections": ["schema", "knowledge"]
}Response
The response format matches the semantic search response with an additional match_type field indicating whether each result was matched via semantic similarity, keyword matching, or both.