Vector store

Phantom stores memories in your own vector store and never persists them on its side. You register the connection once; Phantom encrypts the token at rest and writes to the index on your behalf. The only supported provider today is Upstash Vector.

Recommended: connect from the dashboard

The easiest way to set up your vector store is through the console at app.phantomrouter.ai - paste your Upstash URL and token and it probes and saves the connection for you. See Connect your vector store for a step-by-step walkthrough with screenshots. The endpoints below are the programmatic equivalent for when you'd rather automate it.

All four endpoints require the chat:companion scope.

Embedding model & dimensions

The first time Phantom writes to your index, it pins the embedding model and its dimension (default openai/text-embedding-3-small, 1536 dims). Once memories exist, the model and dimension are immutable - you can still rotate the URL and token, but not change the embedding shape (that would orphan existing vectors). Provision a 1536-dimension index.

---

Get config

GET /api/v1/me/vector-store

Returns your config. The token is never included.

{
  "provider": "upstash",
  "url": "https://your-index.upstash.io",
  "embedding_model": "openai/text-embedding-3-small",
  "embedding_dimensions": 1536,
  "vectors_written": true,
  "created_at": "2026-06-20T10:00:00.000Z",
  "updated_at": "2026-06-24T12:30:00.000Z"
}

404 NOT_FOUND if no store is configured yet.

---

Create or update

PUT /api/v1/me/vector-store

Phantom test-probes the connection before saving and rejects an unreachable or dimension-mismatched index.

Field	Type	Required	Notes
provider	string	✓	Must be upstash.
url	string	✓	The index REST URL. https, 1–2000 chars. Private or internal addresses are rejected.
token	string	✓	The index REST token, 1–4000 chars. Encrypted at rest.
embedding_model	string	-	Defaults to openai/text-embedding-3-small. Immutable once vectors exist.

curl -X PUT https://api.phantomrouter.ai/api/v1/me/vector-store \
  -H "Authorization: Bearer $PHANTOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "upstash",
    "url": "https://your-index.upstash.io",
    "token": "your-upstash-rest-token"
  }'

Returns the same shape as Get config.

Errors: 400 INVALID_REQUEST (unsupported provider, can't connect, index dimension mismatch, or attempting to change the embedding model after vectors exist) · 503 SERVICE_UNAVAILABLE (the probe embedding failed).

---

Test connection

POST /api/v1/me/vector-store/test

Probes the configured store without changing it.

{ "connected": true, "dimension": 1536 }

A reachable-but-failing store returns { "connected": false } with HTTP 200 (not an error). 404 NOT_FOUND if no store is configured.

---

Delete config

DELETE /api/v1/me/vector-store

Removes the stored connection. Returns 204 No Content.

Your memories are safe

Deleting the config only removes Phantom's connection record. The vectors in your Upstash index are left untouched.