Sources and citations
How cited sources reach your UI, how to open the original document, and how to render markers yourself.
When an agent answers from your documents, it cites them. The model writes markers such as [S1] in its text, and the runtime attaches the matching sources to the message. You do not parse anything by hand to get started: BaseeraSurface shows the markers and the sources for you.
What a source is
Every assistant message has a sources array. Each Source has:
Prop
Type
Sources are listed in the order they were first cited, one per document section. Only refs the runtime handed out count: a marker the runtime did not issue never becomes a source.
Show them in the surface
BaseeraSurface renders each reply with its markers and a row of source chips under it. A chip that has a url opens the original; a private source shows its title only. No code is needed.
Open the original
useBaseeraChat returns openSource(source). It asks the runtime for a link and opens it in a new tab. The link is signed and lasts about 5 minutes.
"use client";
import { useBaseeraChat } from "@baseera/react";
export function Sources({ messageId }: { messageId: string }) {
const { messages, openSource } = useBaseeraChat();
const message = messages.find((m) => m.id === messageId);
if (!message || message.role !== "assistant") return null;
return (
<ul>
{message.sources.map((source) => (
<li key={source.ref}>
{source.url ? (
<button type="button" onClick={() => void openSource(source)}>
{source.title}
{source.page ? `, p. ${source.page}` : ""}
</button>
) : (
source.title
)}
</li>
))}
</ul>
);
}openSource opens the tab inside the click so a popup blocker allows it, then points it at the link. It resolves false and closes the tab when the source is private, gone, or not the user's to open. Access rules still apply: a user whose token lacks a claim never gets a restricted document in a search, a citation or a source link. See Signing user tokens.
Render markers yourself
@baseera/core exports helpers for citation markers:
import { extractCitations, resolveCitations, splitCitations } from "@baseera/core";
extractCitations("Refunds take 5 days [S1]. See also [S2, S3].");
// ["S1", "S2", "S3"]
splitCitations("Refunds take 5 days [S1].");
// ["Refunds take 5 days ", { refs: ["S1"] }, "."]extractCitations(text)returns every ref the text cites, in order of first appearance, without repeats. It accepts[S1],[S1, S3]and[S1][S2].splitCitations(text)splits the text around the markers, so you can render a superscript for each.resolveCitations(text, map)matches the refs to entries you hold and reports the refs it does not know ininvalid.