> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userepo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Citations

> How Repo links every answer back to its source.

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

```json theme={null}
"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:

```typescript theme={null}
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:

```typescript theme={null}
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.