Search API

The Search API provides a single REST endpoint for semantic search across vector databases. The endpoint converts a natural language query into an embedding vector, searches the vector store named in the URL, and returns the most similar results with relevance scores. Embedding and vector database connection details are stored in HashiCorp Vault and resolved server-side. Clients never send secret names — the server always uses its own configured secret names (in multi-tenant mode this enforces tenant isolation), so any secret-name fields in a request body are ignored.

Search a Vector Store

POST /api/v1/search/{store}

One endpoint serves all vector stores. The {store} path parameter selects the store:

Store	Container field	Container default	Store-specific fields
`qdrant`	`collection`	`documents`
`weaviate`	`className`	`Documents`
`milvus`	`collection`	`documents`
`chroma`	`collection`	`documents`
`pgvector`	`table`	`documents`	`schema` (default `public`)

Common Parameters

All stores share these request-body parameters:

Field	Type	Required	Default	Description
`query`	string	Yes		Natural language search query
`topK`	integer	No	5	Number of results to return

Plus the store’s container field from the table above (e.g. collection for Qdrant, className for Weaviate, table/schema for pgvector).

Common Response Format

{
  "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).

Error Responses

An unknown {store} value returns 400 Bad Request with a message naming the valid stores:

Unknown vector store: 'faiss'. Valid stores: chroma, milvus, pgvector, qdrant, weaviate

Other user-actionable errors also return 400 Bad Request with a plain-text message — most notably a vector dimension mismatch, which usually means the embedding provider was changed between ingest and query. Fix it by switching the embedding provider in Configuration to match the collection’s dimension, or by re-ingesting under the current provider. Only stores that are actually running and reachable can be searched successfully. Use GET /api/v1/vector-stores/available to discover which stores are live before searching — the UI’s Search tab uses this to gate its store dropdown. Unexpected server errors return 500 Internal Server Error.

Qdrant

curl -X POST http://localhost:8080/api/v1/search/qdrant \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "collection": "documents",
    "topK": 5
  }'

Weaviate

The container field is className (PascalCase, default Documents).

curl -X POST http://localhost:8080/api/v1/search/weaviate \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "className": "Documents",
    "topK": 5
  }'

Milvus

curl -X POST http://localhost:8080/api/v1/search/milvus \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "collection": "documents",
    "topK": 5
  }'

Chroma

curl -X POST http://localhost:8080/api/v1/search/chroma \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "collection": "documents",
    "topK": 5
  }'

pgvector

The container field is table, with an optional schema (default public).

curl -X POST http://localhost:8080/api/v1/search/pgvector \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue projections",
    "table": "documents",
    "schema": "public",
    "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

Field	Type	Required	Default	Description
`question`	string	Yes		Natural language question
`table`	string	Yes		Target table name
`schema`	string	No	`public`	PostgreSQL schema
`database`	string	No	`datris`	PostgreSQL database
`limit`	integer	No	100	Maximum 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

Field	Type	Required	Description
`query`	string	Yes	The question to answer
`context`	string	Yes	Context 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

These secrets are configured on the server (seeded by vault-init.sh and managed via the Configuration tab) — they are never passed in search requests.

Embedding Secret

Self-describing — the resolver reads provider, endpoint, model, apiKey, and (optionally) version from inside the secret. The server uses the secret named by ai.embedding.secretName (oss/embedding). 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

Each store has a server-configured secret resolved by store key: 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" }

API Documentation

Pipelines

Ingestion

AI

Status

Query

Search

Metadata

Configuration

Health

Secrets

Taps

Code repository

Versions

Auth

API Keys

Assistant

Chat

MCP

Tap Prompts

Search a Vector Store

Common Parameters

Common Response Format

Error Responses

Qdrant

Weaviate

Milvus

Chroma

pgvector

Natural Language Query

AI Answer (RAG)

Vault Secret Structure

Embedding Secret

Vector Database Secrets

​Search a Vector Store

​Common Parameters

​Common Response Format

​Error Responses

​Qdrant

​Weaviate

​Milvus

​Chroma

​pgvector

​Natural Language Query

​AI Answer (RAG)

​Vault Secret Structure

​Embedding Secret

​Vector Database Secrets

Search a Vector Store

Common Parameters

Common Response Format

Error Responses

Qdrant

Weaviate

Milvus

Chroma

pgvector

Natural Language Query

AI Answer (RAG)

Vault Secret Structure

Embedding Secret

Vector Database Secrets