# Add RAG with citations to a Supabase app

> Add retrieval-augmented answers to a Supabase app with @uthereal-sdk/cortex: an Edge Function handler, Supabase auth adapters, claim-level citations and highlighted PDF sources, with no pgvector pipeline to maintain.

- Canonical page: https://uthereal.ai/developers/supabase-rag
- Last updated: 2026-09-18
- Product: Uthereal Cortex (sovereign enterprise AI, Swiss/EU data residency)
- npm package: `@uthereal-sdk/cortex` (https://www.npmjs.com/package/@uthereal-sdk/cortex)
- Repository: https://github.com/Uthereal-Labs/Uthereal-Cortex-SDK

## Short answer

Short answer: install @uthereal-sdk/cortex, mount createCortexHandler in a Supabase Edge Function with the Supabase server adapter, and call it from the browser with createCortexBrowserClient. Keep CORTEX_SHARED_API_KEY in Edge Function secrets. You do not need pgvector, an embedding pipeline or a reranker.

Supabase gives you auth, Postgres and Edge Functions. What it does not give you is a retrieval stack that can prove where an answer came from. This is the shortest path from a Supabase project to a cited knowledge agent.

## Why not pgvector on its own

pgvector solves storage and similarity search. A production knowledge product needs more than that: layout-aware parsing, chunking that respects headings and tables, reranking, claim-to-source mapping, page-level PDF evidence and a refusal path when no passage supports the question. Those are the parts that take months and decide whether users trust the answers.

- Keep Supabase for auth, application data, storage and row level security
- Hand retrieval, ranking and citation mapping to Cortex
- Ship a cited answer in one install instead of an embedding pipeline

## The Edge Function handler

One authenticated endpoint. It verifies the Supabase session, then forwards to Cortex with the server-side key.

```
// supabase/functions/cortex/index.ts
import { createCortexHandler } from "@uthereal-sdk/cortex/server";
import { supabaseAuthenticate, supabaseStore } from "@uthereal-sdk/cortex/adapters/supabase-server";

const handler = createCortexHandler({
  config: {
    baseUrl: Deno.env.get("CORTEX_API_BASE_URL")!,
    assistantId: Deno.env.get("CORTEX_ASSISTANT_ID")!,
    apiKey: Deno.env.get("CORTEX_SHARED_API_KEY")!, // secret, server only
  },
  allowedOrigin: "https://your-app.example",
  authenticate: supabaseAuthenticate(),
  store: supabaseStore(),
});

Deno.serve(handler);
```
_supabase/functions/cortex/index.ts_

```
supabase secrets set \
  CORTEX_API_BASE_URL="https://agent.uthereal.ai/api/functions/v1/api-server-proxy" \
  CORTEX_ASSISTANT_ID="your-assistant-id" \
  CORTEX_SHARED_API_KEY="sk-..."
```
_Secrets: never in the client bundle_

## Calling it from the browser

```
import { createCortexBrowserClient } from "@uthereal-sdk/cortex/browser";
import { CitedAnswer } from "@uthereal-sdk/cortex/react";
import { supabaseFetch } from "@uthereal-sdk/cortex/adapters/supabase-browser";

const cortex = createCortexBrowserClient({
  endpoint: "/functions/v1/cortex",
  fetch: supabaseFetch(supabase), // attaches the user's access token
});

const conversationId = await cortex.createConversation();
for await (const update of cortex.ask(conversationId, { message })) {
  if (update.type === "answer") showPreview(update.answer);
}
```
_client.tsx_

> Render CitedAnswer inside your existing TanStack Query provider, and clear caches on sign-out so one user never sees another user's cached evidence.

## Let your AI coding tool wire it

Lovable, Codex, Claude Code, Cursor, Windsurf and GitHub Copilot each read a ready-made instruction file for this SDK. With the file in place, describe the feature and the tool writes the Supabase wiring.

```
Add a chat panel to this Supabase app that answers only from our uploaded
documents. Every claim must cite its source and open the PDF page,
highlighted. Use the Uthereal Cortex SDK with the Supabase adapters and keep
CORTEX_SHARED_API_KEY in Edge Function secrets.
```
_Prompt for your coding tool_

## Frequently asked questions

### Do I need pgvector to build RAG on Supabase?

No. pgvector gives you vector storage, but you still have to own chunking, embeddings, reranking, prompt construction, refusal behaviour and a citation UI. @uthereal-sdk/cortex calls a hosted retrieval service that returns cited answers, so Supabase keeps doing what it is good at: auth, storage and your application data.

### Where does the Cortex API key live in a Supabase app?

In Supabase Edge Function secrets, as CORTEX_SHARED_API_KEY. The browser calls your Edge Function with the user's Supabase session; the Edge Function calls Cortex. The key never reaches the client bundle.

### How do I map Supabase users to Cortex sessions?

Use the Supabase adapters: @uthereal-sdk/cortex/adapters/supabase-server for the handler and /adapters/supabase-browser for the client. Derive the Cortex user and session identifiers from the verified Supabase JWT, never from client input.

### Can I keep conversation history in my own Postgres tables?

Yes. The SDK takes a CortexStore adapter, so conversations and messages are written to your own tables with your own row level security policies.

### Does this work with Supabase Storage PDFs?

Yes. Upload the documents to a Cortex agent for retrieval; citations resolve to the exact page and open with the passage highlighted. Supabase Storage can remain your system of record for the original files.

## Related pages

- [SDK overview](https://uthereal.ai/developers/sdk): Full setup and API reference.
- [npm package](https://uthereal.ai/developers/npm): Install, exports and runtimes.
- [PDF page citations](https://uthereal.ai/developers/pdf-citations): How highlighted evidence works.
- [Do you need a vector database?](https://uthereal.ai/developers/vector-database-alternative): What you own if you run one.

## Next steps

- Create an agent and a scoped server key: https://agent.uthereal.ai
- Full SDK guide (HTML): https://uthereal.ai/developers/sdk
- Full SDK guide (Markdown): https://uthereal.ai/developers/sdk.md
- AI index for this site: https://uthereal.ai/llms.txt and https://uthereal.ai/llms-full.txt
- Help: sdk@uthereal.ai