---
title: "Vector Search"
description: "Store and search vector embeddings with free TEI-powered embeddings and HNSW indexes"
canonical: "https://docs.ainative.studio/docs/zerodb/vectors"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Vector Search

Source: https://docs.ainative.studio/docs/zerodb/vectors

> Store and search vector embeddings with free TEI-powered embeddings and HNSW indexes

## Vector Search

ZeroDB provides vector storage and semantic search with **free embeddings** — no OpenAI key required.

<Callout type="tip" title="Free Embeddings Included">
ZeroDB includes a free embedding service powered by TEI (Text Embeddings Inference). No OpenAI key needed — just send text and get vectors back automatically.
</Callout>

## Quick Start

<PackageInstall
  npm="npx zerodb-cli init"
  pip="pip install zerodb-mcp"
/>

## Store Vectors

<APIEndpoint method="POST" path="/api/v1/public/zerodb/vectors" auth />

```bash
curl -X POST https://api.ainative.studio/api/v1/public/zerodb/vectors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["ZeroDB is fast", "Semantic search is powerful"],
    "metadata": [
      {"source": "docs", "category": "product"},
      {"source": "docs", "category": "feature"}
    ]
  }'
```

Embeddings are generated automatically using TEI (HuggingFace Text Embeddings Inference) at zero cost.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `texts` | `string[]` | Yes | Text content to embed and store |
| `vector` | `float[]` | No | Pre-computed embedding (if omitted, auto-generated) |
| `metadata` | `object[]` | No | Key-value metadata for filtering |
| `namespace` | `string` | No | Namespace isolation (default: "default") |
| `ids` | `string[]` | No | Custom IDs. Auto-generated if omitted. |

## Search by Meaning

<APIEndpoint method="POST" path="/api/v1/public/zerodb/vectors/search" auth />

```bash
curl -X POST https://api.ainative.studio/api/v1/public/zerodb/vectors/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fast database for AI",
    "limit": 5,
    "min_score": 0.7,
    "filter_metadata": {"source": "docs"}
  }'
```

Response:
```json
{
  "results": [
    {
      "id": "vec_abc...",
      "text": "ZeroDB is fast",
      "score": 0.94,
      "metadata": {"source": "docs", "category": "product"}
    }
  ]
}
```

**Search Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | `string` | Yes | Natural language search query |
| `limit` | `integer` | No | Max results (default: 10, max: 100) |
| `min_score` | `float` | No | Minimum similarity score (0.0–1.0) |
| `namespace` | `string` | No | Search within a specific namespace |
| `filter_metadata` | `object` | No | Filter by metadata key-value pairs |

## Python SDK

```python
import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
base = "https://api.ainative.studio/api/v1/public/zerodb"

## Store vectors
requests.post(f"{base}/vectors", headers=headers, json={
    "texts": ["AI agents need persistent memory"],
    "metadata": [{"source": "research", "year": 2026}],
    "namespace": "papers"
})

## Search
response = requests.post(f"{base}/vectors/search", headers=headers, json={
    "query": "How do AI agents use memory?",
    "limit": 5,
    "min_score": 0.7,
    "filter_metadata": {"source": "research"}
})
for result in response.json()["results"]:
    print(f"{result['score']:.3f} — {result['text'][:80]}")
```

## LangChain Integration

<PackageInstall pip="pip install langchain-zerodb" />

```python
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

<PackageInstall pip="pip install llama-index-vector-stores-zerodb" />

```python
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 with BAAI/bge models:

<CardGrid cols={2}>
  <FeatureCard title="BAAI/bge-base-en-v1.5" badge="Default">768-dimension embeddings optimized for semantic search</FeatureCard>
  <FeatureCard title="16ms Inference" badge="Fast">Average embedding latency with TEI backend</FeatureCard>
  <FeatureCard title="Free at All Tiers" badge="No Cost">No OpenAI key needed — embeddings included</FeatureCard>
  <FeatureCard title="Bring Your Own" badge="Flexible">Pass a `vector` field to use custom embeddings</FeatureCard>
</CardGrid>

## Upsert Alias

`POST /zerodb/vectors/upsert` is an alias for `POST /zerodb/vectors`. Use either — both accept the same request body and return the same response.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/zerodb/vectors/upsert \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["ZeroDB is fast"], "namespace": "docs"}'
```

## All Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/zerodb/vectors` | Upsert vectors with text or raw embeddings |
| POST | `/zerodb/vectors/upsert` | Alias for POST `/zerodb/vectors` |
| POST | `/zerodb/vectors/search` | Semantic similarity search |
| GET | `/zerodb/vectors` | List vectors with pagination |
| DELETE | `/zerodb/vectors/{id}` | Delete a vector by ID |
| GET | `/zerodb/vectors/stats` | Vector count and storage stats |
| POST | `/zerodb/embed` | Generate embeddings from text (free) |