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

# Fetch a source once, then read it as often as you need

> Every fetch and every upload is stored as a record. Read it again in another format, at another size, or as the whole page, without a second visit to the source. Every such read is from the same copy.

An agent rarely knows on its first read what it will need from a source. It reads the outline, then one section, then a table, and an hour later a second agent checks a quote. Each of these calls reads the same stored copy, the record. The source is visited once, and every reader sees the same text under the same ids.

## Read the record in another form

`get_contents` takes the id of a record and returns it in the form you ask for. This request reads a record as blocks, with a size limit large enough for all of its text.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/contents/CONTENTS_ID?formats=json&max_characters=200000" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

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

client = GetClean()

record = client.get_contents(contents_id="CONTENTS_ID", formats=["json"], max_characters=200000)
```

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

const client = new GetClean();

const record = await client.getContents("CONTENTS_ID", { formats: ["json"], max_characters: 200000 });
```

Replace `CONTENTS_ID` with the id of a record.

These fields choose the form of the read.

| Field | What it chooses |
| - | - |
| `formats` | `markdown`, `html`, `json`, `doclang`, or `links`. |
| `max_characters` | The most text to return, where `0` returns the outline and no text. |
| `scope` | `main` for the main content, or `whole_page` for everything that was on the page. |
| `block_kinds` | Only blocks of these kinds, such as `table`. |

A read changes nothing in the record. Its outcome, its time, its fingerprint, and the facts of its source are the ones of the fetch. The highlights, the summary, and the filled fields that the fetch asked for come back with every read, at no charge.

## Share one record among several agents

The id is all that another agent needs. An agent that directs 3 helpers fetches a page once and passes them the id. Each reads the sections it needs by id, and all 3 read the same copy, so they cannot contradict each other from 2 versions of a page that changed in between. The fingerprint in each response says which copy a read came from.

An id cannot be guessed, and a call with the id of another account returns the problem `not-found`.

## Know how long a record is stored

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

A call on an expired record returns the problem `contents-expired` for 30 days, and the problem names `fetch_contents` as the call that gets the source again. After those 30 days a call on the id returns `not-found`.

## List the records you have

`list_contents` returns the records of your account, the newest first, each with its id, its outcome, its source, and its dates, and without text. Use it to see whether a page is already there before you fetch it again. This request lists the records of one site.

```bash cURL theme={"theme":"css-variables"}
curl --get https://api.getclean.ai/v1/contents \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --data-urlencode "url=https://example.com/*"
```

```python Python theme={"theme":"css-variables"}
records = client.list_contents(url="https://example.com/*")
for record in records:
    print(record.id, record.source.title)
```

```typescript TypeScript theme={"theme":"css-variables"}
const records = await client.listContents({ url: "https://example.com/*" });
for await (const record of records) {
    console.log(record.id, record.source.title);
}
```

`url` matches an address exactly, or every address that starts with it if it ends in `*`. `carrier` narrows the list to live pages with `web`, to copies from an archive with `archive`, or to files you sent with `upload`.

## Store nothing

A fetch that sends `retention` as `none` stores nothing after its response. No later read is possible then, so ask in that one call for everything you need. The account's policy sets the default, and a request can shorten it to `none` and cannot lengthen it.

## Delete a record

`delete_contents` erases a record before it expires, with its picture, its served bytes, and the images of its pages. Later calls on the id return the problem `not-found`.

## Check what a read costs

A read of a stored record costs nothing: `get_contents`, `get_section`, `list_blocks`, `list_links`, and `list_contents`. The key needs the scope `contents:read`, and `contents:delete` to delete. A question that a model has to work on, such as a summary of a stored record, costs one model step.


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