How to Integrate Chroma with Your Headless CMS

What is Chroma?

Chroma is an open-source vector database built for AI applications that need embeddings, metadata filters, and similarity search. Teams use it for retrieval-augmented generation, semantic search, recommendations, and agent memory, either self-hosted or through Chroma Cloud. Its core model is collections: you add documents, IDs, embeddings or raw text, and metadata, then query for nearest neighbors.

Why integrate Chroma with a headless CMS?

If your product docs, help articles, product descriptions, or policy pages live in one system, but your vector index lives somewhere else, your AI experience can drift out of date fast. A title change ships on the website, but the old wording still answers customer questions in a chat flow. A product gets discontinued, but it still appears in recommendations because the vector database never heard about the update.

Connecting Chroma to a headless CMS fixes that gap by turning content events into indexing events. When an editor publishes a document, a webhook or server-side function can fetch the exact fields Chroma needs, build a clean text payload, attach metadata like language, product line, slug, and publish date, and upsert it into a Chroma collection. With Sanity, structured content in the Content Lake means you don’t have to scrape HTML or split page blobs before embedding. GROQ lets you pull the right fields and referenced content in one query.

The alternative is usually a scheduled job that runs every few hours, exports everything, chunks it again, and hopes nothing changed mid-run. That can work for small sites. It gets messy when you have 30 locales, 10,000 product pages, or editors publishing updates during a launch. Event-driven sync gives you smaller writes, fresher retrieval, and clearer failure points.

Architecture overview

A typical Sanity and Chroma integration starts when content is created, updated, published, or deleted in Sanity Studio. A Sanity webhook or Function receives the mutation event, then uses GROQ to fetch only the fields needed for retrieval, such as title, summary, Portable Text body, slug, category references, locale, and access flags. The server-side code converts that structured JSON into one or more retrieval documents, then calls Chroma’s SDK with collection.upsert() to write IDs, documents, and metadata into a collection. For deletes or unpublishes, the same flow calls collection.delete() with the Sanity document ID. When an end user searches or asks a question, your app embeds the query, queries Chroma for the closest documents, and uses the returned Sanity IDs or slugs to show results, build a RAG prompt, or link back to the source content.

Common use cases

Step-by-step integration

1. 1

   Set up Chroma

   Create a Chroma Cloud account or run Chroma locally. Create a database and collection, copy your API key, tenant, database, and endpoint, then install the SDK with npm install chromadb @sanity/client.

2. 2

   Model retrieval-ready content in Sanity Studio

   Add fields that make useful retrieval chunks, such as title, summary, Portable Text body, slug, locale, audience, product references, and last reviewed date. Keep metadata as typed fields so Chroma filters can use it later.

3. 3

   Choose what gets indexed

   Write a GROQ query that returns only published, searchable content. Include referenced fields you need for retrieval, such as category title or product SKU, instead of sending the full document.

4. 4

   Create the sync trigger

   Use a Sanity webhook for an external API route, or use a Sanity Function if you want the sync code to run server-side on content events without separate infrastructure. Trigger on create, update, publish, and delete events.

5. 5

   Push documents to Chroma

   In the handler, fetch the Sanity document, convert it into a text document, attach metadata, and call collection.upsert(). For deleted or unpublished documents, call collection.delete() using the same stable ID.

6. 6

   Test retrieval in your app

   Publish a test article, confirm it appears in the Chroma collection, then query with queryTexts or queryEmbeddings. Build the frontend search or RAG flow, and verify that returned IDs map back to the right Sanity slugs.

How Sanity + Chroma works

CMS approaches to Chroma

Keep building

Explore related integrations to complete your content stack.