How to add citations to an AI chatbot

• The model is asked to produce citation markers as text, so it can invent them
• Citations point at whole documents, leaving the reader to search manually
• Chunks lose page and position data during ingestion, so nothing can be highlighted
• Retrieval returns similar text, not the text that actually supported the claim

Each of these fails the same test: a reader cannot verify a single sentence in under five seconds. In regulated, medical, legal, financial or publishing work, that failure makes the whole feature unusable.

• Layout-aware parsing — keep headings, tables, page numbers and character spans
• Semantic chunking — coherent passages with stable identifiers, not fixed-size cuts
• Retrieval and reranking — recall first, then precision on the shortlist
• Grounded generation — the model answers only from the retrieved passages
• Claim resolution — each claim is mapped back to the passage identifiers that support it

The identifiers are the whole trick. Once a passage identifier survives from ingestion to the rendered answer, a citation becomes a lookup instead of a guess.

// server — your authenticated endpoint
import { createCortexHandler } from "./sdk/server.ts";

export const handler = createCortexHandler({
  config: {
    baseUrl: process.env.CORTEX_API_BASE_URL!,
    assistantId: process.env.CORTEX_ASSISTANT_ID!,
    apiKey: process.env.CORTEX_SHARED_API_KEY!, // server secret only
  },
  allowedOrigin: "https://your-app.example",
  authenticate: async (request) => verifyYourApplicationSession(request),
  store: yourStoreAdapter,
});

// browser — stream the answer, render clickable citations
import { createCortexBrowserClient } from "./sdk/browser.ts";
import { CitedAnswer } from "./sdk/react.ts";

const cortex = createCortexBrowserClient({ endpoint: "/cortex", fetch: authedFetch });
const id = await cortex.createConversation();
for await (const update of cortex.ask(id, { message })) render(update);

<CitedAnswer answer={saved.answer} messageId={saved.id} loadPdf={cortex.pdf} />;

Clicking a citation calls cortex.pdf, which returns the source page with the supporting passage highlighted — no viewer to build.

• Every claim resolves to a passage a reader can open
• The answer refuses rather than guesses when retrieval finds nothing
• The API key never reaches the browser bundle
• Sessions and users map to your own authenticated records, not client input
• Retrieval-only output (rag) is available for workflows that need raw evidence