Vector Search

ZeroDB provides vector storage and semantic search, with two ways to work with it: a high-level flow that embeds text for you for free, and a low-level flow for bringing your own embeddings.

💡Free Embeddings Included

The high-level embed-and-store flow includes a free embedding service — no OpenAI key needed, just send text and ZeroDB generates and stores the vectors automatically.

ℹ️Every endpoint on this page is project-scoped

All paths below include your project_id. Get yours from the dashboard, or mint a temporary scoped project in one call with Instant DB.

Quick Start

npx zerodb-cli init

Embed & Store (recommended)

The easiest way to get text into ZeroDB — one call embeds your text for free and stores the resulting vectors.

POST/api/v1/public/{project_id}/embeddings/embed-and-store🔒

curl -X POST https://api.ainative.studio/api/v1/public/$PROJECT_ID/embeddings/embed-and-store \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["ZeroDB is fast", "Semantic search is powerful"],
    "metadata_list": [
      {"source": "docs", "category": "product"},
      {"source": "docs", "category": "feature"}
    ],
    "namespace": "default"
  }'

Response:

{
  "success": true,
  "vectors_stored": 2,
  "embeddings_generated": 2,
  "model": "bge-m3",
  "dimensions": 1024,
  "target_column": "embedding",
  "namespace": "default",
  "project_id": "...",
  "processing_time_ms": 128.4
}

Parameters:

Parameter	Type	Required	Description
`texts`	`string[]`	Yes	1–100 texts to embed and store
`metadata_list`	`object[]`	No	Metadata for each text, same order as `texts`
`namespace`	`string`	No	Namespace isolation (default: `"default"`)
`model`	`string`	No	Embedding model (default: `bge-m3`, 1024-dim) — see Choosing a model

Semantic Search

Search by meaning — ZeroDB embeds your query and finds the closest stored vectors.

POST/api/v1/public/{project_id}/embeddings/search🔒

curl -X POST https://api.ainative.studio/api/v1/public/$PROJECT_ID/embeddings/search \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fast database for AI",
    "limit": 5,
    "threshold": 0.3,
    "filter_metadata": {"source": "docs"}
  }'

Response:

{
  "results": [
    {
      "document": "ZeroDB is fast",
      "source": "docs",
      "vector_id": "...",
      "metadata": {"source": "docs", "category": "product"}
    }
  ],
  "query": "fast database for AI",
  "total_results": 1,
  "model": "bge-m3",
  "project_id": "...",
  "processing_time_ms": 42.1
}

Search Parameters:

Parameter	Type	Required	Description
`query`	`string`	Yes	Natural language search query
`limit`	`integer`	No	Max results, 1–100 (default: 10)
`threshold`	`float`	No	Similarity threshold, 0 = match everything, 1 = exact match only (default: 0.3)
`namespace`	`string`	No	Search within a specific namespace (default: `"default"`)
`filter_metadata`	`object`	No	Filter by metadata key-value pairs
`model`	`string`	No	Embedding model for the query. If omitted, auto-detected from the namespace's stored vectors so the query matches the data — set explicitly to override

Python

import requests

headers = {"X-API-Key": "YOUR_API_KEY"}
base = f"https://api.ainative.studio/api/v1/public/{project_id}"

# Embed and store
requests.post(f"{base}/embeddings/embed-and-store", headers=headers, json={
    "texts": ["AI agents need persistent memory"],
    "metadata_list": [{"source": "research", "year": 2026}],
    "namespace": "papers"
})

# Search
response = requests.post(f"{base}/embeddings/search", headers=headers, json={
    "query": "How do AI agents use memory?",
    "limit": 5,
    "threshold": 0.3,
    "filter_metadata": {"source": "research"}
})
for result in response.json()["results"]:
    print(f"{result['document'][:80]}")

LangChain Integration

pip install langchain-zerodb

from langchain_zerodb import ZeroDBVectorStore

store = ZeroDBVectorStore(
    api_key="your-api-key",
    project_id="your-project-id",
)

## Add documents (embeddings generated free)
store.add_texts(["ZeroDB is fast", "Semantic search"])

## Search by meaning
results = store.similarity_search("fast database", k=5)

LlamaIndex Integration

pip install llama-index-vector-stores-zerodb

from llama_index_zerodb import ZeroDBVectorStore
from llama_index.core import VectorStoreIndex

store = ZeroDBVectorStore(
    api_key="your-api-key",
    project_id="your-project-id",
)

index = VectorStoreIndex.from_vector_store(store)
response = index.as_query_engine().query("What is ZeroDB?")

Embeddings

ZeroDB generates embeddings automatically using TEI (Text Embeddings Inference) with BAAI/bge models. Get the live model list any time with GET /api/v1/public/embeddings/models.

bge-m3

Default

1024-dimension embeddings, multilingual, 8K context

Fast TEI Inference

Fast

Low-latency embedding generation backend

Free at All Tiers

No Cost

The embed-and-store and search endpoints on this page don't charge extra for embedding

Bring Your Own

Flexible

Already have vectors? Use the low-level API below instead

Low-Level Vectors API (bring your own embeddings)

If you generate embeddings elsewhere, work with the raw, project-scoped vectors API directly. This is a separate set of endpoints from embed-and-store above — it takes a pre-computed vector_embedding array instead of text.

POST/api/v1/public/zerodb/{project_id}/database/vectors/upsert🔒

curl -X POST https://api.ainative.studio/api/v1/public/zerodb/$PROJECT_ID/database/vectors/upsert \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vector_embedding": [0.01, -0.02, 0.5],
    "namespace": "docs",
    "metadata": {"source": "docs"}
  }'

Parameter	Type	Required	Description
`vector_embedding`	`float[]`	Yes	Your pre-computed embedding
`vector_id`	`string`	No	Custom vector ID (auto-generated if omitted)
`namespace`	`string`	No	Namespace isolation (default: `"default"`)
`metadata`	`object`	No	Key-value metadata for filtering

Quantum Vector Compression (TurboQuant)

ZeroDB includes vector compression based on Google's TurboQuant paper (ICLR 2026) — PolarQuant + QJL — for shrinking stored embeddings without materially losing search quality.

ℹ️When this helps

Compression overhead only pays off on real embedding dimensions (384+). A tiny test vector (under ~100 dims) can come back larger than the input — the per-vector metadata dominates at that size.

POST/api/v1/projects/{project_id}/database/vectors/quantum-compress🔒

Methods (pass as method; legacy aliases map automatically):

Method	Legacy alias	What it does	Verified minimum
`turboquant`	`quantum_harmonic`	PolarQuant + QJL combined	>2x compression, cosine similarity > 0.999
`polarquant`	`sparse_encode`	PolarQuant only	>2x compression, cosine similarity > 0.999
`qjl`	`entropy_reduce`	QJL sign-bit only — much smaller, lossier	>10x compression, cosine similarity > 0.5

Typical real-world results run higher than the verified minimums above — turboquant commonly reaches ~2.5–3.5x on normalized embeddings, and qjl commonly reaches ~25–30x. Actual ratio depends on the input vector's own statistics (sparsity, magnitude distribution).

Request body:

Field	Type	Default	Notes
`vector_embedding`	`float[]`	required	1–4096 dimensions
`method`	string	`quantum_harmonic`	One of `turboquant`, `polarquant`, `qjl` (or a legacy alias above)
`precision`	int	`16`	Radius quantization bits: `8`, `16`, or `32`

Example (384-dim embedding, turboquant, precision: 16):

curl -X POST https://api.ainative.studio/api/v1/projects/{project_id}/database/vectors/quantum-compress \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vector_embedding": [...384 floats...], "method": "turboquant", "precision": 16}'

{
  "compressed_data": "AIABAAAQ3IAhPsAAAAD//wAA...",
  "original_dimensions": 384,
  "compressed_dimensions": 162,
  "compression_ratio": 0.4232,
  "compression_metadata": {
    "magnitude": 1.0,
    "sparsity": 0.0,
    "dimensions": 384,
    "precision": 16
  },
  "stats": {
    "original_size": 1536,
    "compressed_size": 650,
    "compression_time_ms": 0.97,
    "algorithm": "turboquant"
  }
}

compression_ratio is compressed_size / original_size — the example above compressed 1536 bytes down to 650 (about 2.4x), confirmed by a live call against this exact endpoint.

All Endpoints

Two different prefixes — the embed-and-store flow and the low-level vectors API are NOT interchangeable paths for the same thing, so double-check which base you're using.

Embed-and-store flow, prefixed with /api/v1/public/{project_id}:

Method	Path	Description
POST	`/embeddings/embed-and-store`	Embed text (free) and store as vectors — the easy path
POST	`/embeddings/search`	Semantic search by natural-language query
GET	`/embeddings/models`	List available embedding models (no project scope needed)

Low-level vectors API, prefixed with /api/v1/public/zerodb/{project_id}:

Method	Path	Description
POST	`/database/vectors/upsert`	Upsert ONE pre-computed vector
POST	`/database/vectors/upsert-batch`	Upsert up to 500 pre-computed vectors in one call
POST	`/database/vectors/search`	Similarity search with a query vector you supply
GET	`/database/vectors`	List vectors with pagination
GET	`/database/vectors/{vector_id}`	Get a single vector by ID
DELETE	`/database/vectors/{vector_id}`	Delete a vector by ID
GET	`/database/vectors/stats`	Vector count and storage stats

Vector Search​

Quick Start​

Embed & Store (recommended)​

Semantic Search​

Python​

LangChain Integration​

LlamaIndex Integration​

Embeddings​