Citations

Every retrieval response includes a numbered citations array. Each citation maps a citation marker (e.g. [1]) to a specific sourceItemId so your agent can render verifiable answers.

Shape

"citations": [
  { "index": 1, "sourceItemId": "9c0e7a3f-...", "title": "Brand decisions" },
  { "index": 2, "sourceItemId": "b4d12e88-...", "title": "Design review notes" }
]

Using citations in your prompt

The typical pattern: pass context.hits into your LLM prompt with the citation index inline, then ask the model to cite by index. Repo’s /v1/ask does this for you, but if you’re rolling your own:

const promptContext = hits
  .map((hit, i) => `[${i + 1}] ${hit.title}\n${hit.content}`)
  .join("\n\n");

const systemPrompt = `Answer using only the context below. Cite sources as [N].

${promptContext}`;

Resolving citations to URLs

The citations array doesn’t include URLs directly — that’s in the hits array. To render clickable links:

const linkable = citations.map(c => {
  const hit = hits.find(h => h.sourceItemId === c.sourceItemId);
  return { ...c, url: hit?.url, provider: hit?.provider };
});

Stable IDs across syncs

sourceItemId is a Repo-stable UUID, not a provider-side identifier. The same Notion page keeps its sourceItemId across re-syncs as long as the page hasn’t been deleted and recreated. This means:

Your agent can build URL caches that survive sync cycles
Audit logs reference real, persistent IDs
A chat history that mentions [1] from yesterday can still resolve to the same source today

Citation hygiene

A few patterns we recommend:

Render citations as the first thing in the answer (or alongside each claim), not as a footnote at the end. Users actually click them.
Show the provider icon next to the citation — [1] Slack #brand is more useful than [1].
Surface staleness when a cited source is >24h old: “based on the Notion page (synced 2 days ago)”.
Don’t fabricate citations — if the agent makes a claim not backed by a hit, omit the citation. Repo’s /v1/ask prompt is structured to avoid this but downstream agents can re-introduce the bug.

Get started

Core concepts

Connectors

Operations

Shape

Using citations in your prompt

Resolving citations to URLs

Stable IDs across syncs

Citation hygiene

​Shape

​Using citations in your prompt

​Resolving citations to URLs

​Stable IDs across syncs

​Citation hygiene

Shape

Using citations in your prompt

Resolving citations to URLs

Stable IDs across syncs

Citation hygiene