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

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Cite the passage, not the page

> A citation that names the page leaves the reader to search it. Cite the passage: the record, the block, the printed page, and the words. Anyone can open it again, and a later check can tell whether the source still says it.

A report says that default interest is 2 percent above the normal rate, and gives a link to a credit agreement of 96 pages. The reader who wants to check the sentence has to find the clause. A citation should end the search, not start it. Every passage that getclean returns has a place that stays the same, so a sentence of your report can lead straight to the words it rests on.

## Take the place with the passage

Every way of reading a record returns the place of what it returns. A highlight has it, a filled field has it, and each block of the content has it.

| Part of the place | What it is |
| - | - |
| The record | The copy of the source that getclean stores, with its `id` and its `fingerprint`, the hash of its text. |
| The section | The part of the outline the passage is in, with its title. |
| The block | The paragraph, the table, or the heading itself, whose id is the same on every read of the record. |
| The page | On a document, the position of the page in the file and the number printed on it. |
| The cell | Inside a table, the row and the column. |
| The words | The passage as the source has it. |

A place is not a count of characters. A count changes with every format, and a block does not.

## Write the citation

Store with each sentence of the report what a reader needs to open it. A citation of the sentence about default interest can look like this.

```json A citation in your report theme={"theme":"css-variables"}
{
  "source": "Facility Agreement, clause 10, page 43",
  "url": "SOURCE_URL",
  "fetched_at": "2026-11-04T08:40:12Z",
  "fingerprint": "sha-256=:kw4QGoYGxOYpZ0EZGL+nxMfFUXfrxcp+P0M4EOrEiH4=:",
  "version": "1.0.0",
  "contents_id": "CONTENTS_ID",
  "block_id": "BLOCK_ID",
  "words": "at a rate which is 2 per cent. per annum higher than the rate which would have been payable"
}
```

The first line is for a person. It comes from the section's title and the printed page, which the place gives you. The rest is for a program.

## Open a citation

To show the passage, read the block by its id from the stored record. The read costs nothing.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/contents/CONTENTS_ID/blocks?block_ids=BLOCK_ID" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean

client = GetClean()

blocks = client.list_blocks(contents_id="CONTENTS_ID", block_ids=["BLOCK_ID"])
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const blocks = await client.listBlocks("CONTENTS_ID", { block_ids: ["BLOCK_ID"] });
```

Replace `CONTENTS_ID` with the id of the record and `BLOCK_ID` with the id of the block, both from the citation.

To show the passage in its surroundings, read its section with the highlight marks. For the request, see [Highlight the evidence for each question](https://docs.getclean.ai/read/highlight-passages-and-answers.md).

## Check a citation after the record is gone

A record is stored for 48 hours after its last use, and for at most 30 days. A report is read for years. The citation written in the form shown on this page still works, in 2 steps.

1. Fetch the source again, and compare the new record's `fingerprint` with the one in the citation. If the 2 are equal, the source has the same text as on the day of the report. Fingerprints can be compared only under the same version of getclean and its configuration, so send the citation's `version` as `pinned_version` while that version is served.
2. If the fingerprints differ, send the citation's `words` to the new record as a highlight, with `deterministic_only` set to `true`. A highlight whose `basis` is `exact` or `near` says the passage is still there, and where it is now. The notice `highlight_not_found` says the source no longer has those words.

A reader then knows one of 3 things about a sentence of an old report: the source is unchanged, the passage is still there in a changed source, or the passage is gone. None of the 3 is a guess, and none needs a model.

The step with `baseline_fingerprint` that saves the text of an unchanged page works only while the earlier record is stored. For that step, see [Find the one cell that changed](https://docs.getclean.ai/read/track-what-changed.md).

For a source that must be shown as it was on the day of the report, ask for that day. See [Time machine: read a page as it was on a past day](https://docs.getclean.ai/read/time-machine.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.