@upstash/vector

# @upstash/vector

HTTP/REST vector database client. Works in Next.js (Node and Edge), Cloudflare Workers, Vercel, Deno and Bun.

## Install

```bash
npm install @upstash/vector
```

## Credentials

```bash
UPSTASH_VECTOR_REST_URL=...
UPSTASH_VECTOR_REST_TOKEN=...
```

- No account (agents, demos): `curl -X POST https://upstash.com/start-vector -H "Idempotency-Key: $(uuidgen)" -H "User-Agent: <your-agent>"` returns a temporary index with credentials (3 days, claimable).
- Account: console.upstash.com/vector, create an index, then copy the REST URL and token from the REST API section.
- Create the index with a built-in embedding model (e.g. BAAI/bge-small-en-v1.5) so you can upsert and query raw text with no OpenAI key.

## Next.js App Router: upsert and query

```ts
// src/lib/vector.ts
import { Index } from "@upstash/vector";
let index: Index | undefined;
export function getIndex() {
  return (index ??= Index.fromEnv()); // lazy: does not break `next build` without env vars
}
```

```ts
// src/app/api/vectors/route.ts
import { getIndex } from "@/lib/vector";
export const runtime = "nodejs";

export async function POST(req: Request) {
  const { id, text, metadata } = await req.json();
  await getIndex().upsert({ id, data: text, metadata }); // `data` = embedded by the index's model
  return Response.json({ ok: true });
}

export async function GET(req: Request) {
  const q = new URL(req.url).searchParams.get("q");
  if (!q) return Response.json({ error: "q required" }, { status: 400 });
  const results = await getIndex().query({ data: q, topK: 5, includeMetadata: true });
  return Response.json(results);
}
```

Use `vector: number[]` instead of `data` if the index has no embedding model; the dimension must match the index.

## Verify

```bash
npm run build
curl -X POST localhost:3000/api/vectors -d '{"id":"1","text":"hello world"}'
curl 'localhost:3000/api/vectors?q=hello'
```

## Agents

MCP server: https://mcp.upstash.com/mcp. Skills: `npx skills add https://github.com/upstash/skills`. See AGENTS.md.

# AGENTS.md: @upstash/vector

## Install
`npm install @upstash/vector`

## Env vars
- `UPSTASH_VECTOR_REST_URL`: from console.upstash.com/vector (index, REST API), or from `POST https://upstash.com/start-vector` (no signup, 3-day temp index).
- `UPSTASH_VECTOR_REST_TOKEN`: same place. Use the read-only token only for query-only code.
- Put them in `.env.local`. Commit `.env.example` and add `!.env.example` to `.gitignore` if `.env*` is ignored.

## Next.js App Router: the one path
```ts
// src/lib/vector.ts (server only)
import { Index } from "@upstash/vector";
let index: Index | undefined;
export const getIndex = () => (index ??= Index.fromEnv());
```
Call `getIndex()` inside route handlers or server actions, never at module top level.
- Upsert: `await getIndex().upsert([{ id, data: text, metadata }])`
- Query: `await getIndex().query({ data: text, topK: 5, includeMetadata: true })`
- Batch upserts in groups of about 100 to 1000 vectors.

## Three mistakes agents make
1. Calling `Index.fromEnv()` or `new Index()` at module scope. `next build` then fails without env vars. Use the lazy getter.
2. Passing `data` (text) to an index created without an embedding model, or `vector` with the wrong dimension. Check the index's dimension in the console. Prefer an index with a built-in embedding model.
3. Hand-rolling `fetch` against the REST API or an in-memory fallback instead of the SDK, then leaving the real path untested.

## Verify
1. `npm run build` passes with NO env vars set.
2. With env vars set: POST one item, GET a query, confirm the id comes back with `score` > 0.
3. `index.info()` shows `vectorCount` increased.

## Do not
- Do not use an in-memory fallback in place of Upstash. If credentials are missing, get a temp index from start-vector or tell the user exactly which two env vars to set.

# Upstash Vector

> Serverless vector database over HTTP/REST. Use `@upstash/vector` to upsert and query embeddings from Next.js, Workers and Node. Indexes can embed text for you (built-in models), so no OpenAI key is needed. Free tier: 10K daily queries.

## Start here
- [Quickstart (TypeScript SDK)](https://upstash.com/docs/vector/overall/getstarted.md): create index, install SDK, upsert, query
- [No-account temp index](https://upstash.com/start-vector): POST for credentials, free, expires in 3 days
- [Next.js App Router example](https://upstash.com/docs/vector/sdks/ts/getting-started.md): route handler with a lazy client

## SDK (prefer over raw REST)
- [Upsert](https://upstash.com/docs/vector/sdks/ts/commands/upsert.md)
- [Query](https://upstash.com/docs/vector/sdks/ts/commands/query.md)
- [Namespaces](https://upstash.com/docs/vector/features/namespaces.md)
- [Metadata filtering](https://upstash.com/docs/vector/features/filtering.md)

## Embeddings
- [Built-in embedding models](https://upstash.com/docs/vector/features/embeddingmodels.md): upsert and query with `data` instead of `vector`

## RAG
- [RAG with Vercel AI SDK](https://upstash.com/docs/vector/integrations/vercelai.md)

## Optional
- [REST API reference](https://upstash.com/docs/vector/api/endpoints/upsert-data.md)
- [MCP server](https://upstash.com/docs/agent-resources/mcp.md)
- [Agent skills](https://upstash.com/docs/agent-resources/skills.md)
- [Pricing](https://upstash.com/pricing/vector.md)