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

# API reference

> The getclean API at api.getclean.ai has 22 operations under /v1, takes a bearer key on every request, and answers with what happened before anything else. This page lists every operation, the rules they all share, and the headers you send and get back.

The getclean API is a single HTTPS API at `https://api.getclean.ai`, described by one OpenAPI 3.1 contract with 22 operations under `/v1`. Every request carries `Authorization: Bearer <key>`, and every record starts with what happened, as an outcome, instead of an HTTP status. Each operation's page in this section is generated from the contract, so its parameters, examples and rules are the contract's own words. The contract itself is [`openapi.yaml`](https://docs.getclean.ai/openapi.yaml).

## A request and its response

This request fetches a shop page that answers with a bot challenge instead of the page.

```bash theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents \
  -H "Authorization: Bearer $GETCLEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://shop.example/offer"}'
```

The response is `201 Created`, which is what every outcome of a fetch gets. The record below leaves out its `source` and `execution` fields; [Fetch contents](https://docs.getclean.ai/api-reference/fetch-contents.md) shows it in full.

```http theme={"theme":"css-variables"}
HTTP/1.1 201 Created
Location: https://api.getclean.ai/v1/contents/cnt_7Qp2cdxxK32qkfIDrqRUE2
Request-Id: req_01KXuaBXEPybVuXmnCI9Bl
Content-Type: application/json

{
  "id": "cnt_7Qp2cdxxK32qkfIDrqRUE2",
  "outcome": {
    "kind": "failed",
    "reason": "challenge_served",
    "message": "A bot challenge stood where the page should be; a retry later may work on sites that do not challenge every new visitor, or a person opens the URL and uploads the saved page with captured_url."
  },
  "notices": [],
  "fetched_at": "2026-11-04T08:41:03Z",
  "truncated": false,
  "cost": {
    "ceiling": { "amount": "0.0500", "currency": "USD" },
    "actual": { "amount": "0.0000", "currency": "USD" },
    "units": {},
    "replayed": false
  },
  "retention": "hold",
  "run_id": "run_default",
  "expires_at": "2026-11-06T08:41:03Z",
  "request_id": "req_01KXuaBXEPybVuXmnCI9Bl"
}
```

`outcome` comes first. Its `kind` is one of `delivered`, `partial`, `failed`, `refused` or `needs_person`, its `reason` says why, and its `message` says what you can try next. A page that couldn't be read is a record like any other, and you pay for what happened: `cost.actual` is zero here. A problem, sent as `application/problem+json`, only answers a request that getclean itself refuses, such as `401 unauthorized` for a missing key or `422 invalid-field` for a value outside its set. [Records](https://docs.getclean.ai/understand/records.md) goes through a record field by field, [Outcomes and notices](https://docs.getclean.ai/understand/outcomes-and-notices.md) lists every reason, and [Errors](https://docs.getclean.ai/understand/errors.md) lists every problem type.

## The operations

The operations form two families, contents and search, plus one request that serves both, `get_limits`. The contents family takes one source, a web page or a document, by URL or as a file, and makes its record; every later question about that source is answered from the record for free. The search family runs one question, in up to twenty wordings, on up to ten sources at once, and returns one ranked list with the facts of each result and a receipt of what ran where, before any page is fetched. Each line below is the first sentence of that operation's page.

### Fetch and upload

| Operation | What it does |
| - | - |
| [`fetch_contents`](https://docs.getclean.ai/api-reference/fetch-contents) `POST /v1/contents` | Fetch a web page or a document at a URL. You get its main content with the structure intact, in the formats you ask for, the outline of its sections, the facts of the source, a fingerprint and the price, as one record that is kept for later reads. |
| [`upload_contents`](https://docs.getclean.ai/api-reference/upload-contents) `POST /v1/contents:upload` | Read a document you hold, or one at a URL that needs more time than a fetch gives. You get the same record a fetch makes, with `pages` saying how many pages were read, which failed and which were recognized from their image. |
| [`get_job`](https://docs.getclean.ai/api-reference/get-job) `GET /v1/jobs/{job_id}` | Read a job, or wait for it to finish, free. The response comes at the final state or when `wait_seconds` ends, with the job as it stands. |
| [`cancel_job`](https://docs.getclean.ai/api-reference/cancel-job) `POST /v1/jobs/{job_id}:cancel` | Ask a job to stop, free. With pages already parsed the record is `partial`, `canceled`, the pages kept and charged. |
| [`list_jobs`](https://docs.getclean.ai/api-reference/list-jobs) `GET /v1/jobs` | List the account's jobs, newest first, free. `state` and `kind` filter them. |
| [`fetch_contents_batch`](https://docs.getclean.ai/api-reference/fetch-contents-batch) `POST /v1/contents:batch` | Fetch 1 to 20 pages or documents at their URLs in one request. You get one record per address, with a tally first and the sum of the costs last. |

### Records

| Operation | What it does |
| - | - |
| [`get_contents`](https://docs.getclean.ai/api-reference/get-contents) `GET /v1/contents/{contents_id}` | Read a record you already have, free: the same copy in any format, at any size, under either view, with the model work the fetch made. |
| [`get_section`](https://docs.getclean.ai/api-reference/get-section) `GET /v1/contents/{contents_id}/sections/{section_id}` | Read one section of a record, free: its text when it fits, its own text and the rows of its child sections when it does not. |
| [`list_blocks`](https://docs.getclean.ai/api-reference/list-blocks) `GET /v1/contents/{contents_id}/blocks` | List the blocks of a record, free: by kind, by section, by document page or by id, in document order, one page of results at a time. |
| [`list_links`](https://docs.getclean.ai/api-reference/list-links) `GET /v1/contents/{contents_id}/links` | List the links of a record, free: every link with its kind and the block and section that hold it. |
| [`list_contents`](https://docs.getclean.ai/api-reference/list-contents) `GET /v1/contents` | List the records the account keeps, newest first, free. Each item is compact: the record's id, outcome, source and dates, with no text. |
| [`delete_contents`](https://docs.getclean.ai/api-reference/delete-contents) `DELETE /v1/contents/{contents_id}` | Erase a record before it expires: the record, its screenshot, its raw HTML, its document images, its recognized page images and its stored replays. |

### Working with a record

| Operation | What it does |
| - | - |
| [`highlight_contents`](https://docs.getclean.ai/api-reference/highlight-contents) `POST /v1/contents/{contents_id}:highlight` | Find words or questions in a record you already have and mark where they stand, without fetching again. A string found word for word is free; one a model has to judge costs one model step. |
| [`fill_schema`](https://docs.getclean.ai/api-reference/fill-schema) `POST /v1/contents/{contents_id}:fill` | Fill your JSON Schema from a record you already have. You get a value only where the record states it, with the place and the cited words for each property. |
| [`summarize_contents`](https://docs.getclean.ai/api-reference/summarize-contents) `POST /v1/contents/{contents_id}:summarize` | Have a model write a summary of a record you already have, at most 1,500 characters in the content's language. |
| [`compare_contents`](https://docs.getclean.ai/api-reference/compare-contents) `POST /v1/contents/{contents_id}:compare` | Compare a record you already have with a baseline, block by block and cell by cell, without a model, free. |

### Search

| Operation | What it does |
| - | - |
| [`search`](https://docs.getclean.ai/api-reference/search) `POST /v1/search` | Search up to ten sources with one question, in up to twenty wordings, and get one ranked list of results with the facts of each and a receipt of what ran where, before any page is read. |
| [`get_search`](https://docs.getclean.ai/api-reference/get-search) `GET /v1/search/{search_id}` | Read a search you already have, free: the first page as it was answered, and behind it the full list the search stored, including the results it dropped and why. |
| [`search_batch`](https://docs.getclean.ai/api-reference/search-batch) `POST /v1/search:batch` | Run 1 to 20 searches in one request, one record each. |
| [`list_datasources`](https://docs.getclean.ai/api-reference/list-datasources) `GET /v1/datasources` | List the places getclean can search, free. `filters` and `operators` say what each source honors, before any search. |
| [`get_datasource`](https://docs.getclean.ai/api-reference/get-datasource) `GET /v1/datasources/{datasource_id}` | Read one entry of the catalog in full, free. |

### Account

| Operation | What it does |
| - | - |
| [`get_limits`](https://docs.getclean.ai/api-reference/get-limits) `GET /v1/limits` | Read your key's limits and your account's money in one response, free, before a batch or any request that has to fit a budget. |

## What every operation has in common

| Topic | The rule |
| - | - |
| The credential | Every request carries `Authorization: Bearer <key>`, where the key is an API key from `https://app.getclean.ai` or an access token issued by `https://auth.getclean.ai/realms/getclean`. A credential in the query string is ignored. Each operation says which scope it needs, and a key without it gets `403 insufficient-scope` with every needed scope in `scopes_required`. [Authenticate a request](https://docs.getclean.ai/start/authentication.md) covers both kinds of credential. |
| The request id | Every response has a `Request-Id` header with a `req_` id, repeated in the body as `request_id`. A replay gets its own id, not the original request's. Quote it when you ask about a request. |
| Bodies | A JSON body can be up to 256 KB, a KB being 1,000 bytes, and can be gzip-coded. The upload is `multipart/form-data`, up to 101 MiB, with the document part up to 100 MiB. |
| Money | Every amount is an object such as `{"amount": "0.0500", "currency": "USD"}`: a decimal string with up to four decimal places and an ISO 4217 currency code. |
| Time | Date-times are RFC 3339 in UTC, like `2026-11-06T12:00:00Z`. Dates are full dates, like `2026-10-01`. |
| The rate | One rate covers every operation. `RateLimit` and `RateLimit-Policy` report it on every response except a `401`. [Limits](https://docs.getclean.ai/understand/limits.md) has the figures. |
| Retries | Eight operations take an `Idempotency-Key`, so a retried request is never charged twice. [Errors](https://docs.getclean.ai/understand/errors.md) has every rule. |
| Tracing | Every operation accepts an optional W3C `traceparent` header. It's logged with the request and never forwarded to a site or a source. |
| `HEAD` | `HEAD` on any `GET` of either family returns the headers the `GET` would send, with no body, straight away. A `HEAD` on `get_job` doesn't wait. |
| Problems | A response that isn't a result is `application/problem+json`, as RFC 9457 defines it, with one shape for every status. A method a resource doesn't offer gets `405` with `Allow`, and a representation it can't produce gets `406`. |
| Transport | HTTPS only. A plain HTTP request gets `400 invalid-request` on that same connection, with the HTTPS URL in `detail`, and is never redirected. |

## Headers you send

| Header | When | Form |
| - | - | - |
| `Authorization` | Every request | `Bearer <key>`, an API key or an access token. |
| `Content-Type` | Every request with a body | `application/json`, or `multipart/form-data` on the upload. Anything else gets `415`. |
| `Content-Encoding` | Optional, on a JSON body | `gzip`. The upload takes no content coding. |
| `Idempotency-Key` | Optional on `fetch_contents`, `highlight_contents`, `fill_schema`, `summarize_contents` and `search`. Required on `upload_contents`, `fetch_contents_batch` and `search_batch`. | 1 to 255 visible ASCII characters, used exactly as sent. Leaving out a required key gets `400 invalid-request` with the header's name in the problem. |
| `traceparent` | Optional, on every request | W3C Trace Context. A malformed value is ignored, never refused. |
| `Expect` | Optional, on the upload | `100-continue`. A declared `Content-Length` over 101 MiB, and every refusal that the method, the path and the headers decide, is answered before `100 Continue`, so a refused upload never sends its document. |

## Headers you get back

| Header | On | Form |
| - | - | - |
| `Request-Id` | Every response | This request's `req_` id. |
| `RateLimit` | Every response except a `401` | What's left of your quota: `"requests";r=<left>;t=<seconds>` and `"concurrency";r=<left>`. |
| `RateLimit-Policy` | Every response except a `401` | Your key's policy: `"requests";q=<per minute>;w=60` and `"concurrency";q=<at once>;qu="concurrent-requests"`. |
| `Location` | A `201` from `fetch_contents`, `upload_contents` or `search`; a `202` from `upload_contents` | The absolute URL of the record on a `201`, or of the job on a `202`. |
| `Retry-After` | Always on a `202`, a `429` and a `503`. On a `200` from `get_job` or `cancel_job` while the job isn't finished. On a `409` only for `idempotency-key-in-flight`. | Whole seconds, 1 or more, repeated in the body as `retry_after_seconds`. |
| `WWW-Authenticate` | Every `401`. A `403` only for `insufficient-scope`. | The bearer challenge, which names the document that leads to the sign-in. |
| `Sunset` | Every response of a resource whose retirement has been announced | The moment of the end, as an IMF-fixdate (RFC 8594). Never used for a retiring version of getclean, which is announced by the `version_retiring` notice instead. |
| `Deprecation` | Every response of a resource or an element whose retirement has been announced | The moment of the announcement as a Structured Field Date (RFC 9745). |
| `Accept` | A `415` | The media types the operation accepts. |
| `Accept-Encoding` | A `415` caused by a content coding | `gzip`, and `identity` on the upload, which takes none. |
| `Link` | A `451` | `rel="blocked-by"`, pointing at getclean's own notice page for the demand. |
| `Allow` | A `405` | The methods the resource offers. |
| `Cache-Control` | `get_limits`, `list_datasources`, `get_datasource` | `no-store` on your limits, because the response is specific to your key. `max-age=3600` on the catalog, so a cached answer repeats the first request's `request_id` and rate figures. |
| `Content-Type` | Every response with a body | `application/json`, or `application/problem+json` for a problem. |

## Where the rules are

> [card] [Records](https://docs.getclean.ai/understand/records.md)
>
> What a record contains, how long it's kept, and how to read it again for free.

> [card] [Outcomes and notices](https://docs.getclean.ai/understand/outcomes-and-notices.md)
>
> Every outcome reason and every notice code, with what you can try next.

> [card] [Errors and retries](https://docs.getclean.ai/understand/errors.md)
>
> Every problem type, who has to act, the fix as data, and the idempotency key.

> [card] [Costs and budgets](https://docs.getclean.ai/understand/costs-and-budgets.md)
>
> The ceiling, the five limits behind it, and what gets dropped when the money runs short.

> [card] [Limits](https://docs.getclean.ai/understand/limits.md)
>
> The rate, the bounds of every field, the body sizes and the key's policy.

> [card] [Repeatable output and model steps](https://docs.getclean.ai/understand/repeatability.md)
>
> What repeats, what doesn't, pinning a version, and how a retirement is announced.


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