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

# Turn PDFs, Office files, and scans into evidence you can cite by page

> Send a file or its address and get the same record a web page gives: the content with its sections, its tables, and its page numbers. A scanned page is read from its picture, and the response says how sure the reading is.

Much of what research rests on is not a web page. It is a contract in a data room, a filing as a PDF, a spreadsheet of a budget, a scan of minutes from 1998. `upload_contents` reads the file and returns a record, the same kind a fetched page gives, so every later step works on a file as it does on a page: the outline, the sections, the highlights, the comparison.

## Upload a file

Send the file as `document`. The SDKs take a path, the bytes, or a stream.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents:upload \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Idempotency-Key: IDEMPOTENCY_KEY" \
  --form "document=@FILE_PATH"
```

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

client = GetClean()

result = client.upload_contents(document="FILE_PATH", wait=True)
record = result.contents
```

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

const client = new GetClean();

const result = await client.uploadContents({ document: { path: "FILE_PATH" }, wait: true });
const record = result.contents;
```

Replace `FILE_PATH` with the path of the file, and `IDEMPOTENCY_KEY` with a value of your own that is new for each upload. An upload must have this key, so that a file sent twice is not read and charged twice. The SDKs make the key for you.

A file can be up to 100 MiB. It is deleted when the read ends, and only the record is stored.

For a file that is on the web, send its address as `url` in place of `document`.

## Wait for a long file

A short file comes back in the same call. A long one, such as a scan of 300 pages, is read as a job, because a read that stopped early would lose pages. The call then returns the job, and the record follows when the job is done. With `wait` set, the SDKs follow the job and return the record.

A job reads the pages in order. If a spending limit or the job's 30 minutes ends it, the record has the pages read so far and its outcome is `partial`.

## Read what came from the file

The record has `pages`, which says how the read went. This response is cut to that field.

```json Part of the response theme={"theme":"css-variables"}
{
  "pages": {
    "count": 312,
    "parsed_count": 310,
    "failed_pages": [118, 204],
    "recognized": [
      { "page_number": 7, "confidence": 0.98 },
      { "page_number": 8, "confidence": 0.61 }
    ]
  }
}
```

Each block and each section of the record has the page it is on, as `page_number`, and the number printed on that page, as `page_label`, so a citation can say "page iv" as the document does.

What the record has depends on what the file has.

| File | What you get |
| - | - |
| Word and other text documents | Headings, tables, footnotes tied to the text that cites them, and bold, italic, and struck text, with tracked changes shown as accepted and counted in a notice. |
| A PDF with structure | Headings, tables cell by cell, and text formatting, with a table that runs over several pages as one table. |
| A PDF without structure | The text, with sections from the PDF's outline or one for each page, its tables as text, and the notice `marks_not_read` for the bold and struck text that could not be read. |
| A spreadsheet | Each sheet as a section with its table: the cells as displayed, the address of the first cell, and which cells have a formula. |
| A scan or a photo | The text recognized from each page's picture, with a confidence for each page and each block. |

A document can be one of 22 types, from PDF and the Office formats to Markdown, CSV, JSON, and images. `get_limits` lists them. An archive file such as a ZIP, and audio or video, are not read, and the record's outcome says so.

## Choose the format of the content

A record of a file comes in the same formats as a record of a web page. The content is the same in each, and each format is for another reader.

| Format | What it is for |
| - | - |
| `markdown` | A model that reads the document, and the default. |
| `json` | Code, which gets the content as blocks and each table cell by cell. |
| `html` | Your product, where a person sees the document. |
| `links` | The next fetch, with every link of the document and its kind. |

Send the formats you want in `formats`. For what each format has, see [Fetch what a page says, not what surrounds it](https://docs.getclean.ai/read/page-as-published.md).

## Trust a scan as far as it deserves

A page without text in it is read from its picture. `pages.recognized` has each such page with a `confidence` from 0 to 1 and a picture of the page, so you can check a reading against what it was read from. A page read below the published bar makes the notice `recognition_uncertain`.

Send the weak pages to a person, and not all 312, which is what the number is for.

To help the reading, name the languages of the scan in `recognition_languages`. Handwriting, and a formula that is only a picture, come as flat text or not at all.

## Record where a saved page came from

A page behind a sign-in cannot be fetched by its address. A person can open it, save it, and upload the file. Send the page's address as `captured_url` and the time it was saved as `captured_at`, and the record says where and when the page was seen.

## Check what a file costs

An upload costs one unit for the file, one for each page read, and one more for each page recognized from its picture. A long scan is the most expensive call there is. To learn a document's size before you pay for its pages, fetch its address with `max_characters` set to `0` and a low `max_cost`: the response has the page count and the outline.


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