> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geekhub.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector stores

> Managed vector collections: upload text, we chunk + embed; query with semantic top-k. No Pinecone.

Vector stores is RAG-as-a-service: create a collection, upload text, and Geek Hub handles chunking + embedding + storage in pgvector with an HNSW index. Query with cosine similarity top-k.

When to use this vs your own pgvector/Pinecone:

* RAG prototype in hours, not days
* One less service to operate
* Cost inline on every operation (same tokenization as `/v1/embeddings`)
* Isolated per org via Supabase RLS

When NOT:

* More than \~1M chunks — HNSW index starts eating Postgres RAM
* Complex metadata filtering (hybrid search, reranking) — use a dedicated DB
* You already have an embeddings pipeline — no gain

## Create collection

```bash theme={null}
curl -X POST https://api.geekhub.mx/v1/vector-stores \
  -H "Authorization: Bearer ghub_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs",
    "model": "openai/text-embedding-3-small"
  }'
```

Returns the store `id`, used in subsequent calls.

## Upload text

```bash theme={null}
curl -X POST https://api.geekhub.mx/v1/vector-stores/$STORE_ID/files \
  -H "Authorization: Bearer ghub_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "faq.md",
    "text": "…full document contents…",
    "chunk_tokens": 512,
    "overlap_tokens": 64,
    "metadata": { "source": "notion", "version": "v2" }
  }'
```

The gateway:

1. Splits text into \~512-token chunks with 64 overlap
2. Embeds all chunks (batched to provider)
3. Inserts into pgvector with your `metadata`
4. Bills the embedding `input_tokens`

Response:

```json theme={null}
{
  "id": "file_uuid",
  "store_id": "store_uuid",
  "filename": "faq.md",
  "chunk_count": 24,
  "input_tokens": 12480,
  "created_at": "2026-07-06T18:03:12Z"
}
```

## Query top-k

```bash theme={null}
curl -X POST https://api.geekhub.mx/v1/vector-stores/$STORE_ID/query \
  -H "Authorization: Bearer ghub_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do I generate an API key",
    "top_k": 5
  }'
```

Response:

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "chunk_uuid",
      "file_id": "file_uuid",
      "chunk_index": 3,
      "content": "To generate an API key, go to /dashboard/keys …",
      "metadata": { "source": "notion", "version": "v2" },
      "similarity": 0.83
    }
  ],
  "usage": { "prompt_tokens": 7 }
}
```

`similarity` ranges from 1 (identical) to -1 (opposite). In practice > 0.7 is usable.

## Other endpoints

* `GET /v1/vector-stores` — lists all stores for your org
* `GET /v1/vector-stores/:id` — details + files
* `DELETE /v1/vector-stores/:id` — drops store + cascades to files and chunks

## Costs

* Upload and query embeddings: tokens × store model price
* Storage: free in v1 (subject to change if it starts costing us)
* Query: only the query embedding (not the stored corpus)

## Roadmap

* PDF/DOCX upload with server-side parsing
* Hybrid search (BM25 + vectors)
* Metadata filtering with `filter: { key: value }`
* LLM-based semantic chunking