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

# Read the 2 sections you need from a 300-page document

> Get the outline of a source before any of its text: one row for each section, with its id, its title, and its size. Then read only the sections you need, by id. The rest stays in the record.

A credit agreement of 300 pages is larger than the context of the agent that has to read it. Text that is cut at a fixed length loses the part that mattered, and a summary loses the wording. A fetch of such a source returns its outline first. Each row of the outline is a section with an id, so you can read 2 sections of the agreement and still know what the others are.

## Get the outline before any text

Fetch the source with `max_characters` set to `0`. The response has the outline and the facts of the source, and no text.

```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", "max_characters": 0 }'
```

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

client = GetClean()

record = client.fetch_contents(url="SOURCE_URL", max_characters=0)
```

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

const client = new GetClean();

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

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

The outline is the `sections` list. This response is cut to 4 of its rows.

```json 201 Created theme={"theme":"css-variables"}
{
  "id": "cnt_5Gh7cdyeVQ6qoJhBFE31L1",
  "outcome": { "kind": "delivered", "reason": "whole" },
  "sections": [
    { "id": "s1", "title": "1. Definitions and interpretation", "level": 1, "characters": 41200, "basis": "structure", "first_page_number": 5, "last_page_number": 31 },
    { "id": "s14", "title": "8. Mandatory prepayment", "level": 1, "characters": 9800, "basis": "structure", "first_page_number": 41, "last_page_number": 46 },
    { "id": "s16", "title": "10. Default interest", "level": 1, "characters": 2400, "basis": "structure", "first_page_number": 47, "last_page_number": 48 },
    { "id": "s27", "title": "23. Events of Default", "level": 1, "characters": 18900, "basis": "structure", "first_page_number": 71, "last_page_number": 79 }
  ]
}
```

A row has the size of its section in `characters`, with everything under it. That number is what the read of the section will add to your context, so you can choose before you read.

`basis` says where the sections come from. On a web page they are the page's headings. In a document they are its own structure, or the outline of a PDF that has no structure. A scan has neither, and its outline is one row for each page.

The outline has at least the top level of sections. Deeper levels come one whole level at a time, while the outline has at most 200 rows. If levels were left out, the notice `sections_cut` says so, and a read of a section lists the sections under it.

## Read one section by its id

`get_section` returns the text of one section from the stored record. The source is not fetched again, and the call costs nothing.

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

```python Python theme={"theme":"css-variables"}
section = client.get_section(contents_id="CONTENTS_ID", section_id="s16")
```

```typescript TypeScript theme={"theme":"css-variables"}
const section = await client.getSection("CONTENTS_ID", "s16");
```

Replace `CONTENTS_ID` with the `id` of the record.

A section that is larger than `max_characters`, which is 20,000 if you send none, does not come cut in the middle. If it has sections under it, the response has its own first text and the rows of those sections, and you read each by its id. If it has none, the text is cut at the edge of a block, and `next_page_token` continues it.

The text before the first heading is the section `s0`. On a source without headings, `s0` is the whole text.

## Let the questions choose the sections

If you know what you are looking for, you do not need to choose from the outline. Send your questions as `highlights` with the fetch. For a source that is larger than `max_characters`, the response then has the sections that contain a highlight, with the reason `matching_sections`, and the outline beside them. For the request and the marks, see [Highlight the evidence for each question](https://docs.getclean.ai/read/highlight-passages-and-answers.md).

## Read the tables of a section

To get only one kind of content from a section, list its blocks by kind. A block is one unit of the content, such as a paragraph, a heading, or a table. This request returns the tables of the section, each cell by cell.

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

```python Python theme={"theme":"css-variables"}
tables = client.list_blocks(contents_id="CONTENTS_ID", section_id="s27", block_kinds=["table"])
```

```typescript TypeScript theme={"theme":"css-variables"}
const tables = await client.listBlocks("CONTENTS_ID", { section_id: "s27", block_kinds: ["table"] });
```

## Know how long the record is there

A record is stored for 48 hours after the last call that used it, and for at most 30 days. Each read of a section moves the 48 hours forward. `expires_at` in a response has the moment.

A document that is too long to be read within one fetch comes back with the outcome `partial` and the notice `upload_to_finish`. Send its address to `upload_contents`, which reads the whole document as a job.


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