# Ending Document Hallucinations: How API-Level Citations Tie Every AI Agent Claim to the Exact Source Passage

> API-level citations for AI agents boost source recall by 15% and tie every claim to exact page or character indices without output token charges for quotes.

- Published: 2026-10-17
- Author: Master Mind
- Canonical: https://aimaster.fi/en/artikkelit/hallusinoinnin-loppu-dokumenttiprosesseissa-nain-api-tason-lahdeviittaukset-sito

Built-in API-level citations increase source recall accuracy by up to 15% compared to custom prompt-based implementations (Anthropic, 2025). When a growth company automates contract reviews, tender responses, or technical customer support, **AI agent citations and hallucination prevention** decide whether your specialists trust the system or double-check every line by hand. Asking a language model in a prompt to list its sources is a polite wish; enforcing citations at the API layer is a deterministic verification mechanism.

Only 1% of Finnish companies use their data to create new business (Sitra), and in knowledge-heavy workflows the bottleneck is rarely a lack of documents. Your company already has thousands of pages of manuals, quality standards, and commercial agreements, but nobody dares to let an agent answer customer or auditor questions if a single invented warranty term can cost a deal.

## Why do prompt-based source citations fail in a growth company's document workflows?

Prompt-based source citations fail in production because the language model generates both the claim and the source reference as free-form text. The model can cite the right document title while misquoting a tolerance value, merging two incompatible clauses, or inventing a page number that does not exist in your PDF.

When a sales engineer or legal counsel catches an AI agent fabricating a single reference, they stop trusting the entire tool. Instead of saving hours, your team spends the afternoon scrolling through a 120-page PDF to verify whether section 4.2 actually says what the agent claimed. That turns an automation project into an expensive proofreading exercise—and no slide deck will fix it.

Traditional Retrieval-Augmented Generation (RAG, where a search index feeds text snippets to a language model) only solves half the problem. Even when the retrieval pipeline finds the right paragraphs, a standard prompt still leaves it up to the model to copy the quote accurately and report where it came from.

## How do API-level citations prevent AI agent hallucinations?

**AI agent citations and hallucination prevention** at the API layer work by chunking source documents into verifiable units before inference and forcing the response to return exact location indices. Instead of letting the model write out quotes from memory, the API parser extracts the cited passage (`cited_text`) directly from the source file.

In Anthropic's Claude Citations API (2025–2026), setting `citations.enabled=true` on a document block changes how the model processes your files. The platform automatically splits documents into sentences and returns structured citation blocks alongside every claim the agent makes. Depending on the document format, each citation includes a precise pointer:

- **Plain text documents:** The API chunks text into sentences and returns 0-indexed character ranges (`start_char_index` and `end_char_index`) pointing to the exact characters in the source file.
- **PDF documents:** The API extracts text from the PDF, splits it into sentences, and returns 1-indexed page number ranges (`start_page_number` and `end_page_number`). Scanned image-only PDFs are not citable directly, which is why your company needs an [OCR and chunking pipeline for AI agents](https://aimaster.fi/en/artikkelit/dokumenttidata-ei-ole-viela-tietoa-nain-kasvuyritys-rakentaa-ocr-ja-pilkkomisput) first.
- **Custom content documents:** If you pass pre-chunked lists, tables, or transcripts, the API skips automatic sentence splitting and returns 0-indexed block pointers (`start_block_index` and `end_block_index`).

Crucially, the `cited_text` field returned by the API is populated by the platform parser, not generated token-by-token by the model. According to Anthropic's API documentation (2026), `cited_text` does not count toward your output tokens, and it is not billed as input tokens when passed back in subsequent conversation turns. You get exact verbatim quotes at zero output token cost.

| Dimension | Prompt-Based Citations | Standard RAG Without API Citations | API-Level Citations (Citations API) |
| --- | --- | --- | --- |
| Source pointer accuracy | Generated as free text; prone to invented page numbers | Knows the retrieved chunk, not the exact sentence inside it | Deterministic character, page, or block index from source file |
| Quote integrity | Model may paraphrase or alter numbers inside quotes | Model rewrites the quote during generation | Parser extracts `cited_text` directly from original document |
| Output token cost for quotes | Billed at full output token price for every quoted word | Billed at full output token price for every quoted word | `cited_text` is free of output token charges (0 output tokens) |
| Recall accuracy | Baseline; degrades on long multi-document prompts | Depends on chunk size and prompt instructions | Up to +15% higher recall accuracy (Anthropic, 2025) |

## How do you combine API citations and JSON Structured Outputs in an ERP or CRM pipeline?

API-level citations and strict JSON schema outputs cannot be enabled in the same API call—attempting both returns an HTTP 400 error (Anthropic, 2026). In production, you solve this by separating document verification and system integration into a two-step agent pipeline: step one verifies the facts with citations, and step two formats the JSON payload.

The technical reason for this incompatibility is straightforward. Citations require interleaving text claims and citation metadata blocks, whereas [structured outputs and JSON schema in AI integrations](https://aimaster.fi/en/artikkelit/structured-outputs-ja-json-skeema-tekoalyintegraatiossa-estavat-rikkinaiset-erp-kutsut) lock the entire model output into a single strict JSON syntax tree. If a developer tries to pass `citations: {"enabled": true}` and `output_config.format` in one request, the call fails immediately.

At AIMASTER, we build this as a clean two-stage architecture on top of [Master OS](https://aimaster.fi/tuotteet/master-layer). **Master OS** is a company's AI Operating System: a platform that connects the company's existing systems (CRM, ERP, documents), data, and agents securely for AI use. In stage one, the reader agent queries your cached documents (`cache_control: {"type": "ephemeral"}`) with citations enabled and produces a verified answer with exact page and character indices. In stage two, a lightweight formatter call converts those verified claims and their citation pointers into a strict JSON schema ready for your ERP or ticketing system.

## How does a growth company deploy a source-verified document agent in 3-day sprints?

Deploying a source-verified document agent starts by mapping the highest-value document bottleneck, standardizing your source files, and building a citation-enforced workflow in 3-day sprints. You do not need to rebuild your document management system; the agent connects directly to your existing folders and databases.

Although 57% of Finnish SMEs use AI (2025), 43% do not use it at all, and the biggest barrier to adoption is a lack of skills (43% of non-users). Many growth companies have tested generic chat tools on PDF files, been burned by an invented figure, and concluded that AI is not ready for serious technical or legal documentation. The issue is not the model—it is missing architecture.

We take document workflows from skepticism to production through three concrete steps:

- **[Master Plan](https://aimaster.fi/tuotteet/master-plan)** is an AI strategy sprint that maps where AI generates the most value for your company—measured in euros. We identify which tender, contract, or technical support process loses the most specialist hours to manual document checking.
- **Master OS** connects your PDF manuals, agreements, and product specifications into a versioned pipeline where scanned files are converted via OCR, static manuals are placed in prompt cache, and `citations.enabled=true` is enforced on every query.
- **[Master Mind](https://aimaster.fi/tuotteet/master-mind)** is a suite of AI agents that runs on top of Master OS and handles business processes independently. **Tailored AI solutions** are delivered using an agile sprint model: one sprint is 3 development days. In the user interface, every sentence produced by the agent highlights the exact source paragraph on click.

Consider an anonymized Finnish B2B machinery growth company whose sales engineers answer 50-page customer specification tenders. Previously, checking compliance clauses across hydraulic, electrical, and safety manuals took two days per tender. With a citation-enforced agent running on Master OS, the agent drafts the technical response and attaches the exact manual title, page number, and verbatim quote (`cited_text`) to every single promise. The engineer clicks the link, sees the highlighted sentence in the PDF, and approves the tender in 20 minutes. We apply the same uncompromising reliability in our own portfolio products, such as Lyyli.ai and VÖRK, as well as in production systems built for public reference customers like Tagomo and Aini (Jaajo Linnonmaa).

Want to see which document process in your company can be automated without the risk of hallucinated answers? Start with a [Free Master Mind Analysis](https://aimaster.fi/analyysi), and we will map where source-verified AI agents deliver the highest euro impact for your business.

## Frequently asked questions

### How do API-level citations differ from asking the AI to cite sources in a prompt?

A prompt instruction is just a text request to the language model, which can still invent page numbers or misquote paragraphs. API-level citations parse the source documents before inference and return verified character or page index pointers directly from the provided files.

### Do quoted source passages increase AI agent output token costs?

No. In the Anthropic Claude Citations API, the cited_text field containing the direct quote from your source document does not count toward output tokens. It is also excluded from input token charges on subsequent conversation turns.

### What document types support API-level citations?

Plain text documents return 0-indexed character ranges, PDF documents with extractable text return 1-indexed page ranges, and custom content documents return 0-indexed block ranges. Scanned image-only PDFs must first go through an OCR pipeline before citations can be used.

### Can API-level citations and JSON Structured Outputs be used in the same API call?

No. Enabling citations and strict JSON schema output in the same API request returns a 400 error because citation blocks are interleaved with text. Production systems use a two-step pipeline: step one extracts verified answers with citations, and step two formats the payload into JSON.