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

# Highlight the evidence for each question

> Send up to 5 phrases or questions with a fetch, or to a stored record. Each place that matches comes back with its section, its block, and its page, and with a mark in the text that says which question found it.

A reviewer who checks a report opens the source and looks for the sentence behind each claim. `highlight_contents` does that search. It takes a record, which is the copy of a page or a document that getclean stores after a fetch or an upload, and it returns every place in the record that bears on each of your strings. Each place is one highlight.

## Ask up to 5 questions in one call

Send from 1 to 5 strings in `highlights`. A string is a phrase to find word for word, or a question in plain words, of at most 4,000 characters. This request asks 5 things of a credit agreement that was uploaded before: 2 defined terms, 2 questions, and a phrase. With `max_characters` set to `0`, the response has the highlights and no text.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents/CONTENTS_ID:highlight \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "highlights": [
      "Change of Control",
      "What if the borrower pays late?",
      "governed by the laws of",
      "Which events let the lenders demand repayment at once?",
      "Material Adverse Effect"
    ],
    "max_characters": 0
  }'
```

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

client = GetClean()

places = client.highlight_contents(
    contents_id="CONTENTS_ID",
    highlights=[
        "Change of Control",
        "What if the borrower pays late?",
        "governed by the laws of",
        "Which events let the lenders demand repayment at once?",
        "Material Adverse Effect",
    ],
    max_characters=0,
)
```

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

const client = new GetClean();

const places = await client.highlightContents("CONTENTS_ID", {
    highlights: [
        "Change of Control",
        "What if the borrower pays late?",
        "governed by the laws of",
        "Which events let the lenders demand repayment at once?",
        "Material Adverse Effect",
    ],
    max_characters: 0,
});
```

Replace `CONTENTS_ID` with the id of a record, such as `cnt_3Fk9abaUhNX7t2eKkgfd3e`.

The response lists every highlight. This one is cut to the highlights of the first 3 strings, and each highlight to the fields that this section explains.

```json 200 OK theme={"theme":"css-variables"}
{
  "highlights": [
    {
      "id": "h1",
      "query_index": 0,
      "text": "Change of Control",
      "basis": "exact",
      "page_number": 9,
      "page_label": "5"
    },
    {
      "id": "h2",
      "query_index": 0,
      "text": "Change of Control",
      "basis": "exact",
      "page_number": 41,
      "page_label": "37"
    },
    {
      "id": "h3",
      "query_index": 1,
      "text": "If the Borrower fails to pay any amount payable by it under a Finance Document on its due date, interest shall accrue on the overdue amount from the due date up to the date of actual payment at a rate which is 2 per cent. per annum higher than the rate which would have been payable.",
      "basis": "judged",
      "page_number": 47,
      "page_label": "43"
    },
    {
      "id": "h4",
      "query_index": 2,
      "text": "governed by the laws of",
      "basis": "exact",
      "page_number": 92,
      "page_label": "88"
    }
  ]
}
```

Each highlight names the string that found it in `query_index`, counted from 0. The term "Change of Control" is in the agreement twice, in its definition and in the clause that uses it, so it has 2 highlights. Every occurrence of a string is a highlight of its own, in the order of the document, up to 50 in one call. If there are more, the notice `highlights_cut` says so.

The question has no words in common with the clause that answers it. A model chose the block that bears on it, and `text` has the agreement's own words, never the model's.

## Get the passages with their marks

To get the text with the highlights, set `max_characters` above `0`. The response then has the sections that contain a highlight, in the order of the document, and each highlight is inside a mark.

```markdown theme={"theme":"css-variables"}
## 10. Default interest

<mark id="h3">If the Borrower fails to pay any amount payable by it under a Finance Document on its due date, interest shall accrue on the overdue amount from the due date up to the date of actual payment at a rate which is 2 per cent. per annum higher than the rate which would have been payable.</mark>
```

`formats` takes `markdown`, `html`, and `json`. In `json` the text comes as blocks, and each block lists its highlights as `highlight_ids`. The record's own text is never changed by a call. The marks are in the response only.

If the sections with highlights are larger than `max_characters`, they come while they fit, and the last one is cut at the edge of a block with its marked blocks inside. `truncated` is then `true`.

## Give each question its own color

A screen that shows the source needs one more step: a color for each string. The mark's `id` leads to its highlight, and the highlight's `query_index` leads to the string. This function adds a class to each mark of an `html` response.

```typescript theme={"theme":"css-variables"}
const classes = ["question-0", "question-1", "question-2", "question-3", "question-4"];

function colorMarks(html: string, highlights: { id: string; query_index: number }[]): string {
    for (const highlight of highlights) {
        html = html.replaceAll(
            `<mark id="${highlight.id}">`,
            `<mark id="${highlight.id}" class="${classes[highlight.query_index]}">`,
        );
    }
    return html;
}
```

The reader of a contract review then sees 5 questions answered in 5 colors on the agreement itself, and your code has split no text and searched no text.

## Tell a quote from a judgment

Each highlight says in `basis` how it was found.

| `basis` | How the highlight was found | The same on every call |
| - | - | - |
| `exact` | The words are in one block as written, with their case. | Yes |
| `near` | The words are in one block if case and the punctuation at the ends of words are ignored. | Yes |
| `judged` | The words are not in the text, and a model chose the blocks that bear on the string. | Not promised |

A quotation in a report should rest on an `exact` or a `near` highlight, because those are found without a model and are the same on every call. Treat a `judged` highlight as a passage to read. A model chose it, and another run can choose another block.

To allow only highlights found word for word, send `deterministic_only` as `true`. No model runs then. A string that is not in the text makes the notice `highlight_not_found`, one notice for each string, and the call still succeeds.

On a scanned page the strings are matched against the recognized words, and each highlight has the `confidence` of its block. A recognition error in the scan is not forgiven by `exact` or by `near`.

## Cite a highlight by its block

The place of a highlight is a section, a block, and the words as found: each highlight has a `section_id` and a `block_id`. On a document with pages it also has `page_number`, the position of the page in the file, and `page_label`, the number printed on the page. Inside a table it has `row` and `column`. The place is never a count of characters, because a count would change with every format and every mark.

The ids of sections and blocks are the same on every read of a record. A citation that names the record and the block can be opened again by you, by a second agent that checks the work, or by a person.

To read the whole block around a highlight, list the record's blocks by id.

```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"}
blocks = client.list_blocks(contents_id="CONTENTS_ID", block_ids=["BLOCK_ID"])
```

```typescript TypeScript theme={"theme":"css-variables"}
const blocks = await client.listBlocks("CONTENTS_ID", { block_ids: ["BLOCK_ID"] });
```

Replace `BLOCK_ID` with the `block_id` of the highlight.

## Highlight while you fetch

`fetch_contents` and `upload_contents` take the same `highlights` field, so a source can be fetched and searched in one call. A search takes it for the results that it fetches, in `contents.highlights`.

```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",
    "highlights": ["What if the borrower pays late?"]
  }'
```

```python Python theme={"theme":"css-variables"}
record = client.fetch_contents(
    url="SOURCE_URL",
    highlights=["What if the borrower pays late?"],
)
```

```typescript TypeScript theme={"theme":"css-variables"}
const record = await client.fetchContents({
    url: "SOURCE_URL",
    highlights: ["What if the borrower pays late?"],
});
```

Replace `SOURCE_URL` with the address of a page or a document.

On a fetch the highlights also decide which text comes back from a long source. If the text is larger than `max_characters` and a highlight was found, the response has the sections that contain highlights, with the reason `matching_sections`, and the outline of the whole. You get the passages that bear on your questions, and the rest of the source stays in the record for a later read.

The record stores the highlights of its fetch. `get_contents` returns them later with the marks in whatever text it returns.

## Check what a call costs

A call in which every string is found word for word costs nothing. If a model judges any string, the call costs one model step, whatever the number of strings.

`highlight_contents` needs a key with the scope `contents:read`. It also needs `contents:model`, because a string can need a model, unless the request sends `deterministic_only` as `true`.


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