Skip to main content
The Search API provides REST endpoints for semantic search across vector databases. Each endpoint converts a natural language query into an embedding vector, searches the specified vector database, and returns the most similar results with relevance scores. All search endpoints use embedding and vector database connection details stored in HashiCorp Vault. Secret names can be passed per-request or configured as server defaults in application.yaml.

​
Common Parameters

All search endpoints share these parameters:
FieldTypeRequiredDefaultDescription
querystringYesNatural language search query
embeddingSecretNamestringNoai.embedding.secretNameOptional override of the embedding Vault secret. Defaults to the server-level ai.embedding.secretName (oss/embedding), which is seeded automatically by vault-init.sh. The secret is self-describing: provider, endpoint, model, apiKey, and (optionally) version.
topKintegerNo5Number of results to return

​
Common Response Format

All search endpoints return: 
{
  "results": [
    {
      "text": "document chunk content",
      "chunk_index": 0,
      "source_pipeline": "pipeline_name",
      "filename": "document.pdf",
      "_score": 0.89
    }
  ],
  "count": 1
}
The _score field indicates relevance (higher is more similar, normalized to 0–1 where applicable).

​
Search Qdrant

POST /api/v1/search/qdrant
FieldTypeRequiredDefaultDescription
collectionstringNodocumentsQdrant collection name
qdrantSecretNamestringNoServer defaultVault secret (must contain host, optionally port, apiKey). Uses server default if omitted.
curl -X POST http://localhost:8080/api/v1/search/qdrant \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "collection": "documents",
    "qdrantSecretName": "oss/qdrant",
    "topK": 5
  }'

​
Search Weaviate

POST /api/v1/search/weaviate
FieldTypeRequiredDefaultDescription
classNamestringNoDocumentsWeaviate class name (PascalCase)
weaviateSecretNamestringNoServer defaultVault secret (must contain host, optionally port, scheme, apiKey). Uses server default if omitted.
curl -X POST http://localhost:8080/api/v1/search/weaviate \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "className": "Documents",
    "weaviateSecretName": "oss/weaviate",
    "topK": 5
  }'

​
Search Milvus

POST /api/v1/search/milvus
FieldTypeRequiredDefaultDescription
collectionstringNodocumentsMilvus collection name
milvusSecretNamestringNoServer defaultVault secret (must contain host, optionally port, apiKey). Uses server default if omitted.
curl -X POST http://localhost:8080/api/v1/search/milvus \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "collection": "documents",
    "milvusSecretName": "oss/milvus",
    "topK": 5
  }'

​
Search Chroma

POST /api/v1/search/chroma
FieldTypeRequiredDefaultDescription
collectionstringNodocumentsChroma collection name
chromaSecretNamestringNoServer defaultVault secret (must contain host, optionally port). Uses server default if omitted.
curl -X POST http://localhost:8080/api/v1/search/chroma \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "collection": "documents",
    "chromaSecretName": "oss/chroma",
    "topK": 5
  }'

​
Search pgvector

POST /api/v1/search/pgvector
FieldTypeRequiredDefaultDescription
tablestringNodocumentsPostgreSQL table name
schemastringNopublicPostgreSQL schema
postgresSecretNamestringNoServer defaultVault secret (must contain jdbcUrl, optionally username, password). Uses server default if omitted.
curl -X POST http://localhost:8080/api/v1/search/pgvector \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "table": "documents",
    "schema": "public",
    "postgresSecretName": "oss/pgvector",
    "topK": 5
  }'

​
Natural Language Query

Ask a question in plain English — the AI generates and executes a SQL query against PostgreSQL. 
POST /api/v1/query/natural
FieldTypeRequiredDefaultDescription
questionstringYesNatural language question
tablestringYesTarget table name
schemastringNopublicPostgreSQL schema
databasestringNodatrisPostgreSQL database
limitintegerNo100Maximum rows to return
curl -X POST http://localhost:8080/api/v1/query/natural \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the top 5 stocks by volume?",
    "table": "stock_prices"
  }'
Returns the AI-generated SQL query and its results.

​
AI Answer (RAG)

Answer a question using AI based on provided context — typically used after a vector search to generate a natural language answer from retrieved chunks. 
POST /api/v1/ai/answer
FieldTypeRequiredDescription
querystringYesThe question to answer
contextstringYesContext text (e.g., concatenated search results)
curl -X POST http://localhost:8080/api/v1/ai/answer \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What was Apple'\''s revenue last quarter?",
    "context": "Apple reported revenue of $94.9 billion for Q1 2026..."
  }'
Returns the AI-generated answer based on the provided context.

​
Vault Secret Structure

​
Embedding Secret

Self-describing — the resolver reads provider, endpoint, model, apiKey, and (optionally) version from inside the secret. See AI Configuration. 
{
  "provider": "openai",
  "endpoint": "https://api.openai.com/v1/embeddings",
  "model": "text-embedding-3-small",
  "apiKey": "sk-..."
}
For Anthropic-only deployments, the bundled TEI sidecar serves bge-m3 and vault-init.sh seeds the embedding secret to point at it (provider: "tei", endpoint: "http://tei:80/v1/embeddings", model: "BAAI/bge-m3").

​
Vector Database Secrets

Qdrant: 
{ "host": "localhost", "port": "6334", "apiKey": "" }
Weaviate: 
{ "host": "localhost", "port": "8079", "scheme": "http", "apiKey": "" }
Milvus: 
{ "host": "localhost", "port": "19530", "apiKey": "" }
Chroma: 
{ "host": "localhost", "port": "8000" }
pgvector: 
{ "jdbcUrl": "jdbc:postgresql://localhost:5432/datris", "username": "postgres", "password": "postgres" }