> ## 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.

# Find the one cell that changed

> Send a record's fingerprint with the next fetch to learn whether a source changed. Compare 2 records to get every change, block by block and cell by cell, with the text before and after.

A regulator changes one rate in one table of a long page. A check of the whole page says only that the page is different. `compare_contents` names the block and the cell, with the text before and after. It takes 2 records, which are the copies of a source that getclean stores after each fetch or upload. It uses no model, so the same 2 records give the same comparison on every call.

## Check whether a source changed

Every record has a `fingerprint`, a hash of its text. To learn whether a source still has the text of a record you have, send that record's fingerprint as `baseline_fingerprint` with the next fetch.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "SOURCE_URL",
    "baseline_fingerprint": "FINGERPRINT"
  }'
```

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

client = GetClean()

record = client.fetch_contents(
    url="SOURCE_URL",
    baseline_fingerprint="FINGERPRINT",
)
```

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

const client = new GetClean();

const record = await client.fetchContents({
    url: "SOURCE_URL",
    baseline_fingerprint: "FINGERPRINT",
});
```

Replace `SOURCE_URL` with the address of the source, and `FINGERPRINT` with the `fingerprint` of the earlier record, such as `sha-256=:kw4QGoYGxOYpZ0EZGL+nxMfFUXfrxcp+P0M4EOrEiH4=:`.

If the text is the same, the response says so and has no text. This response is cut to 3 of its fields.

```json 201 Created theme={"theme":"css-variables"}
{
  "id": "cnt_2bLpzRvKxOEx0I72jKoQSw",
  "outcome": { "kind": "delivered", "reason": "unchanged" },
  "fingerprint": "sha-256=:kw4QGoYGxOYpZ0EZGL+nxMfFUXfrxcp+P0M4EOrEiH4=:"
}
```

If the text differs, the fetch returns the new record in full, and its `fingerprint` is a new one.

A fingerprint compares only with a record of the same kind: the same view of the page, the same version and configuration of getclean, and the same kind of source. If it does not, the notice `fingerprint_incomparable` says which of these differs, and the fetch returns the record in full. If no record of your account has the fingerprint, which is the case after the earlier record expired, the notice is `fingerprint_unknown`.

A page that is `unchanged` costs the same as a fetch, because the page is read in full to compare it. A document at a URL is compared by its bytes first, and no page of it is parsed if the bytes are the same.

## Compare 2 records

To see what changed, compare the new record with the earlier one.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents/CONTENTS_ID:compare \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "baseline_contents_id": "BASELINE_CONTENTS_ID" }'
```

```python Python theme={"theme":"css-variables"}
changes = client.compare_contents(
    contents_id="CONTENTS_ID",
    baseline_contents_id="BASELINE_CONTENTS_ID",
)
```

```typescript TypeScript theme={"theme":"css-variables"}
const changes = await client.compareContents("CONTENTS_ID", {
    baseline_contents_id: "BASELINE_CONTENTS_ID",
});
```

Replace `CONTENTS_ID` with the id of the new record and `BASELINE_CONTENTS_ID` with the id of the earlier one. In the SDKs the call returns the changes as a list to loop over, and the rest of the response is on its `response`.

The response has a tally and then each change. This one is cut to those 3 fields, and each side of a change to its text. One cell of one table changed between 2 fetches a week apart.

```json 200 OK theme={"theme":"css-variables"}
{
  "changed": true,
  "counts": { "added": 0, "removed": 0, "changed": 1, "moved": 0 },
  "changes": [
    {
      "kind": "changed",
      "block_kind": "table",
      "before": { "text": "| Q3 | 41.2% |" },
      "after": { "text": "| Q3 | 41.6% |" },
      "cells": [
        { "row": 1, "column": 1, "before_text": "41.2%", "after_text": "41.6%" }
      ]
    }
  ]
}
```

The unit of the comparison is the block: a paragraph, a heading, a table. Each side of a change has the block's text and its place: the section, the block, and on a document the page. A change has one of 4 kinds.

| `kind` | What it means |
| - | - |
| `changed` | The block is in both records and its text differs. |
| `added` | The block is only in the new record. |
| `removed` | The block is only in the earlier record. |
| `moved` | The same text is at another position. |

In a table the comparison goes on to the cells. `cells` has each changed cell with its `row` and `column`, counted from 0, and its text before and after.

Text is compared without its formatting. If `changed` is `true` and `changes` is empty, the words are the same and only inline formatting, such as bold or italic, moved. A change to a page's markup that leaves the text and its order as they were is no change at all, because a record is the content and not the markup.

Both records must come from the same version of getclean and the same view. If they do not, the request is refused with the problem `records-incomparable`, and the problem names the field that differs.

## Compare with a text you stored

A record is stored for 48 hours after its last use and for at most 30 days. For a source that you check less often than that, such as once a quarter, store the record's whole `markdown` and its `fingerprint` yourself, and send both as the baseline.

```json Request body theme={"theme":"css-variables"}
{
  "baseline_markdown": "BASELINE_MARKDOWN",
  "baseline_fingerprint": "FINGERPRINT"
}
```

Replace `BASELINE_MARKDOWN` with the whole text as the record returned it, of at most 1,000,000 characters. The call first checks that the text has the fingerprint, and it refuses a text that was cut or edited. The `before` side of each change then has its text and no ids, because the baseline is not a record.

## Check 20 sources in one call

`fetch_contents_batch` takes up to 20 addresses, each with its own `baseline_fingerprint`. The response starts with a tally, and a source that did not change comes back without text.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents:batch \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: IDEMPOTENCY_KEY" \
  --data '{
    "items": [
      { "url": "SOURCE_URL", "baseline_fingerprint": "FINGERPRINT" },
      { "url": "SECOND_SOURCE_URL", "baseline_fingerprint": "SECOND_FINGERPRINT" }
    ]
  }'
```

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

batch = client.fetch_contents_batch(
    items=[
        ContentsBatchItem(url="SOURCE_URL", baseline_fingerprint="FINGERPRINT"),
        ContentsBatchItem(url="SECOND_SOURCE_URL", baseline_fingerprint="SECOND_FINGERPRINT"),
    ],
)
```

```typescript TypeScript theme={"theme":"css-variables"}
const batch = await client.fetchContentsBatch({
    items: [
        { url: "SOURCE_URL", baseline_fingerprint: "FINGERPRINT" },
        { url: "SECOND_SOURCE_URL", baseline_fingerprint: "SECOND_FINGERPRINT" },
    ],
});
```

Replace `SECOND_SOURCE_URL` and `SECOND_FINGERPRINT` with the address and the fingerprint of the second source. Replace `IDEMPOTENCY_KEY` with a value of your own that is new for each batch, such as `watch-2026-11-15`. A batch must have this key, so that a batch sent twice is not fetched and charged twice. The SDKs make the key for you.

A nightly check of a list of official pages is then 2 steps. The batch says which sources changed. One comparison for each of those says what changed.

## Check what a comparison costs

`compare_contents` costs nothing and needs a key with the scope `contents:read`. A fetch with a `baseline_fingerprint` is charged as a fetch.


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