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

# Upload contents

> 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, the content with its structure intact, the map of its sections, the facts of the source, a fingerprint and the price, with `pages` saying how many pages were read, which failed and which were recognized from their image, and the record is kept for later reads.

Send the file as the `document` part, or its address as `url`. The parse runs on as a job when it needs more than `wait_seconds`: a scanned document takes seconds per page, and stopping early would lose pages, so this call may answer with a job where `fetch_contents` never does. Use `fetch_contents` for a web page, or for a document at a URL that fits in one wait; use `get_contents` to read a record you already have.

## What it costs

The key needs `contents:fetch`, plus `contents:model` when you send `json_schema`, set `summary` or send `highlights` without `deterministic_only`; getclean decides this from the form before any work. The price is 1 `contents`, plus `document_pages` for every page parsed and `recognized_pages` for every page recognized, plus `model_steps` for each model field that ran. A long scan is the most expensive call there is, since each recognized page bills both page units. It is billed when the record becomes final: in the call that answered `201`, or when the job completes or is canceled with pages done. An `unchanged` answer bills the same 1 `contents`. A parse that failed, was refused or needs a person bills nothing.

## What comes back

* The parse finished within `wait_seconds`: `201 Created`, `Location` naming the record, and `ContentsUpload` with `contents` set, the record with its `cost`.
* The parse goes on: `202 Accepted`, `Location` naming the job, `Retry-After` saying when to read it, and `ContentsUpload` with `job` set. `get_job` reads the job, and `get_contents` reads the record once `contents_id` is set.
* The record is kept 48 hours after its last call and at most 30 days; the job is kept 30 days after its end.

## The body

`multipart/form-data`, at most 101 MiB, the `document` part at most 100 MiB. Every field is a part under its own name.

* One of `document` and `url` is required; both at once is refused `exclusive`, neither `required`.
* A boolean is the text `true` or `false`; a number is decimal text.
* `json_schema`, `max_cost`, `max_source_price` and `metadata` are JSON parts, read as JSON whatever `Content-Type` the part declares.
* A list field is one part per value under the field's name.
* An empty value of a scalar field means the same as leaving it out; an empty value of a list field is an empty list, refused `bound`. Null cannot be written in a form.
* A scalar field sent as two parts is refused `duplicate`. A JSON part that does not parse is `422 invalid-field`, `syntax`, place `form`.
* The `document` part's `filename` and `Content-Type` are hints. The bytes decide the type, among `Limits.document_media_types`; where the bytes alone cannot tell, the declared type decides, then the extension, then plain text.
* `Expect: 100-continue` is honored. A declared `Content-Length` past 101 MiB, and every refusal the method, the path and the headers decide, `401`, `403 insufficient-scope` for `contents:fetch`, the `400` for a missing `Idempotency-Key`, `415` and `409 idempotency-key-in-flight`, is answered before `100 Continue`. The scope a form field decides, `contents:model`, is checked once the form is read and before any work. The `document` part's 100 MiB is checked as the part arrives, `413`.

## The idempotency key

`Idempotency-Key` is required here, since a repeated upload would parse and bill the same document twice; without it the call is `400 invalid-request` naming the header. The same key with the same file and fields returns the first answer again, with this call's `request_id`, `expires_at` as it stands and `replayed` true on `cost`; nothing is billed again. The body is compared by its digest over the file and the fields. A retried start with the same key is the same job. The same key while the first call still runs is `409 idempotency-key-in-flight`; the same key with another body is `422 idempotency-key-reused`. A replay whose record was deleted is `404 not-found` naming the deletion.

## What comes back from a document

* Sections come from the document's own structure; a PDF without one, from its outline, else one row per page; a scan, one row per page. `Section.basis` says which.
* Blocks are `text`, `heading` and `table` where the format carries structure; `image` for an embedded image, served at its `url` with its digest; `math` where the format carries equations; `code` for a source file, one block per file, `code_language` from the extension. The other kinds occur only in an HTML file, which takes a page's kinds.
* `page_number` and `page_label` stand on every block of a paged format and on none of an unpaged one. `pages` is present for every document; on an unpaged format its `count` is the text's size in units of `bounds.contents.document_page_characters` characters, rounded up. A slide is a page.
* XML, JSON and YAML keep every key or element name, one `name: value` line per leaf, the top-level members as sections and the nested ones as headings.
* A spreadsheet's cells come as their stored displayed values under the workbook's locale, never another; each sheet is a section titled by its name, and its table carries `top_left_cell` and `formula_cells`.
* A DOCX keeps its bold, italics and strikethroughs; tracked changes are shown as accepted, with the notice `tracked_changes` and the count. A PDF keeps them only where it carries the structure for them; without it, the notice `marks_not_read` says so, and a strikethrough drawn as a line over text is not detected.
* A footnote reference stays as `[^n]`; the note's block carries `note_for` where the format links it; in a PDF without structure a footnote is a text block at the foot of its page.
* Tables come with their structure where the format carries it; a table that continues onto later pages is one block with `last_page_number`. The tables of a PDF without structure and of a scan come as text.
* Recognition runs on every page without a text layer. Each such page stands in `pages.recognized` with its confidence and a picture of the page; `execution.models` lists the step `recognition` with its version, and `language_detection` when the languages were detected; a page that yields no word stands in `failed_pages`; a recognized block carries `confidence`. A recognized page bills one `document_pages` unit and one `recognized_pages` unit. Handwriting and formulas without equation structure come as flattened text or not at all, with no notice.
* `highlights` on recognized text match the recognized words; `near` forgives case and end punctuation, and neither `exact` nor `near` forgives a recognition error.
* A still image sent as the document, PNG, JPEG, TIFF, WebP or HEIC, is one page without a text layer and is recognized like a scan. A compressed file such as a ZIP, a mailbox file, a saved web archive, an audio or a video file is refused as the record's outcome `unsupported_media_type`.
* The model steps, the highlight marks, the map's bound and `block_kinds` work as on `fetch_contents`, over the document's content.
* An HTML file is read as a page, from its bytes alone: nothing is fetched and nothing is run, so the styles, scripts and images it only points to are not loaded and its main content may differ from what the person saw. `main`, `left_out`, `hidden_text`, the walls and `sign_in_needed` apply to it; no screenshot is made.
* The fingerprint is the sha-256 over the markdown written from the document's blocks. `source.document_digest` is the sha-256 of the bytes, so you can check that the document parsed is the one you hold.
* On a file sent as `document`, `source` carries `url` as `captured_url` or not at all; no `final_url` and no `status_code`; `redirects` `[]`; `carrier` `upload`; no `access_kind`; `filename` as sent; `media_type` as the bytes showed it; `title`, `authors`, the dates and `language` as the document's properties declare them; no `publisher`, `canonical_url` or `archive`; `robots` `not_applicable`; no `visitor`. `scope` is `main`, the whole document; `hidden_text` and `left_out` are absent, present on an HTML file. The table under `Contents` says which members each kind of source carries.
* The bytes you sent are deleted when the parse ends; only the record is kept.

## Fields that do not apply

Each is a notice `field_not_applicable` naming the field, never a refusal: `doclang` on a document that is not HTML; `max_source_price` with `document`; `block_kinds` with nothing to narrow. `recognition_languages` with no page to recognize has no effect and makes no notice.

## `url`

getclean downloads the document and parses it as an upload, as a job when the parse outlives `wait_seconds`. `source.carrier` is `web`, and `source.url` and `final_url` are set. The address and domain rules of `fetch_contents` apply. A download that fails takes the outcomes of a fetch: `not_found`, `access_denied`, `rate_limited`, `server_error`, `http_error`, or a network failure named as RFC 9209 names it. A download that is a web page, a challenge or a sign-in page among them, is a record `refused`, `unsupported_media_type`, with the message naming `fetch_contents`: this call reads documents, not pages, and a wall can be told from a page only by reading it as one.

## `baseline_fingerprint`

The bytes are checked first: when a record of your account issued the fingerprint and the file's `document_digest` matches it, the answer is `unchanged` with no parse and no page billed, at this call's price. Otherwise the parse runs and bills its pages, and a content fingerprint that matches then answers `unchanged`. If no record of your account issued the fingerprint, you get the notice `fingerprint_unknown`, and the parse runs whole.

## Money and time

`max_cost` is reserved at the start. The pages are parsed, and recognized, one by one in order, and every stop keeps the pages done: the parse stops before the page that would pass the ceiling, `partial`, `cost_capped`, or `budget_capped` under a run's or a key's budget. The job's own bound is 30 minutes; past it the record ends `partial`, `time_capped`. `max_source_price` applies with `url` as on a fetch.

## The job

It starts with `202`, `Location`, `Retry-After` and the job in the body, stored before the answer is sent.

* `completed`: `contents_id` is set and the record is delivered or partial.
* `failed`: `problem` is set when nothing was made; else `contents_id` is set and the record carries `failed`, `refused` or `needs_person`.
* `canceled` with pages done: a record `partial`, `canceled`, the pages kept and billed. With none: no record and nothing billed.
* `cost` is the units so far on every read, the final figure once `finished`.
* The job is kept 30 days after its end, then answers `410 job-expired` for 30 days to the owning account, then `404`. The record has its own life, 48 hours after its last call and at most 30 days, so a job may point at a record that has expired.

## Refused before any work

, every violation of the form reported at once in `violations`, place `form`:

* `Idempotency-Key` absent: `400 invalid-request`.
* A body that is not `multipart/form-data`, or carries a content coding: `415 unsupported-media-type`.
* `document` and `url` both present: `invalid-field`, `exclusive`; neither: `required`.
* `captured_url` or `captured_at` with `url`: `dependent`. `captured_url` with a scheme other than http or https, or `captured_at` that is not an RFC 3339 instant: `syntax`.
* `scope`, `as_of_date`, `subject_country` or `subject_language`, which belong to a page and not to a file: `unknown_field`.
* The `document` part over 100 MiB: `413 body-too-large`.
* Every rule of `fetch_contents` on the fields the two share, with the same kinds:
  * a `formats` value, a `block_kinds` value or `retention` outside its set: `not_allowed`; a duplicate value: `duplicate`;
  * `max_characters` between 1 and 999, or any other bound passed: `bound`;
  * `json_schema` or `summary` under `deterministic_only`: `model-work-refused`; `json_schema`, `summary` or `deterministic_only: false` under a key whose policy forbids model work: `403 policy-limit-exceeded`;
  * `max_cost` below the smallest call's price: `cost-exceeds-cap`;
  * a malformed `baseline_fingerprint`: `syntax`; a `json_schema` that is not valid JSON Schema: `syntax`, and one whose root is not `type: object`, that has no `properties`, or whose `pattern` needs backtracking: `not_allowed`;
  * an unknown `run_id`: `not_allowed`; `retention: hold` under a `none` policy: `403 policy-limit-exceeded`; an unknown field: `unknown_field`; `pinned_version` not served: `version-withdrawn`.
* With `url`: a scheme other than http or https, or a password in the userinfo, `syntax`; localhost, an address that is not globally reachable, or a bad port, `destination-refused`; a host outside the key's domain policy, or a URL the key's credential policy refuses, `403 policy-limit-exceeded`.

## Notices this operation makes

`highlight_not_found`, `highlights_cut`, `sections_cut`, `links_cut`, `structured_data_cut`, `size_limit`, `conversion_mismatch`, `field_not_applicable`, `cost_cut`, `budget_cut`, `time_cut`, `step_failed`, `model_link_removed`, `recognition_uncertain`, `tracked_changes`, `fingerprint_incomparable`, `fingerprint_unknown`, `marks_not_read`, `default_set_by_policy`, `version_retiring`; on an HTML file also `hidden_text_cut`, `unread_region`, `no_main_content` and `paywall_declared`; with `url` also `redirected`. `content_not_rendered` is a published code that this version does not make.

## Problem types

* 400 `invalid-request`, The request is invalid.
* 401 `unauthorized`, The key is missing or rejected.
* 403 `insufficient-scope`, The key lacks a scope this call needs; `policy-limit-exceeded`, The key's policy forbids this; `credit-exhausted`, The credit is exhausted; `run-budget-exhausted`, The run's budget is exhausted; `key-budget-exhausted`, The key's budget is exhausted.
* 404 `not-found`, Not found, on a replay whose record was deleted.
* 409 `idempotency-key-in-flight`, The same request is still running.
* 413 `body-too-large`, The body is too large.
* 415 `unsupported-media-type`, The media type is not supported.
* 422 `invalid-field`, A field is invalid; `destination-refused`, The destination is refused, with `url`; `model-work-refused`, Model work is refused by the request; `cost-exceeds-cap`, The cost cap is below the smallest call; `version-withdrawn`, The version is no longer served; `idempotency-key-reused`, The idempotency key was reused with another body.
* 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
* 451 `legal-block`, Withheld under a legal demand.
* 500 `internal-error`, The service failed.
* 503 `overloaded`, The service is overloaded.

## When a record is not delivered

`outcome.message` says what may work next, and the table under `Outcome.reason` gives it for every reason.


## OpenAPI

````yaml /openapi.yaml post /v1/contents:upload
openapi: 3.1.0
info:
  title: getclean API
  version: 1.0.0
  description: >-
    getclean is the data layer for research agents. Every call is shaped around
    one step of research, and every answer is made to be reasoned from and
    cited. Give it a URL, a file or a question. What comes back answers the
    questions a researcher has of a source. What it says, exactly: the main
    content with every heading, table, merged cell, strikethrough and word as
    the source carries them, the same on every read. Where it says it: section
    and block ids that hold across every read, and the places where your own
    words or questions stand. As of when: the dates the source declares, and on
    request the page as an archive held it on a past day. Whether to trust it:
    what the page hides, what was left out, who publishes it, and what it
    declares about its use. What changed since you last looked: a fingerprint,
    and a comparison block by block and cell by cell. What it cost: a ceiling
    you set before, and the bill after.


    Every record is kept, so every later question about the same source is
    answered from the same copy, free. No model judges the content unless you
    ask for it: the summary, the schema fill and the judged highlights are steps
    you name, each listed in the answer with its version, and
    `deterministic_only` turns every judging step off. Two steps run on their
    own and are listed too: text recognition on a scanned page, a fixed step
    that repeats under one version, and the identification of a publisher
    getclean has not seen before, which costs you nothing. A search runs two
    model steps by default, the ranking of its results and the choice of
    sources; the same switch turns them off.


    There are two groups of calls, called families here. The contents family
    takes one source, a web page or a document, by URL or as a file, and makes
    its record: the content in the formats you ask for, the map of its sections,
    its blocks and links, the places where it says a thing, the facts of the
    source, a fingerprint and the price. The search family runs one question, in
    up to twenty wordings, on up to ten datasources at once, merges the results
    into one ranked list, and returns them with their facts and a receipt of
    what ran where, before any page is read. Every answer of either is a record
    with an id, `cnt_` for a source and `srch_` for a search, that every later
    call names.


    Every record opens with `outcome`: what happened at the source, never an
    HTTP status. A page that could not be read is still a record, whose outcome
    says why and what may work next, and the bill follows the outcome: a read
    that failed, was refused or needs a person costs nothing. Only a request
    getclean itself refuses, a bad field, a missing credential, a cap too low,
    is an HTTP error, with a problem body that says whose move it is.


    ## The words this contract uses


    - A record is one result of one billed call. It is kept 48 hours after its
    last call and at most 30 days from its making; `expires_at` names the
    moment, and every call on the record moves it forward within that cap. After
    that, a call on the record is `410` for 30 days, then `404`.

    - A page is a web page at a URL. A document is a file, read at a URL or
    uploaded; a document page is one page of such a file; a page of results is
    one page of a list. Page alone means a web page.

    - A character is one Unicode code point. Every text limit, `max_characters`
    among them, counts characters so.

    - A closed set lists every value a member will ever take. An open set lists
    the values served now, and a later version may add one, so read an unknown
    value as a new one, never as an error.

    - The key is whichever credential you sent, an API key or an access token. A
    field that depends on the key, such as the cap on one call, reads the
    account that credential stands for.

    - The smallest call is a call with nothing extra: one `contents` unit for a
    fetch, one `searches` and one `datasource_queries` unit for a search. A cap
    below it is refused before any work.

    - A run groups records under one budget. Every key has one run,
    `run_default`, and this contract names no other.

    - The kind of source, `carrier`, is `web` for a live page, `archive` for an
    archive's copy of a page read under `as_of_date`, and `upload` for bytes you
    sent.

    - A view of a page is `main`, the main content alone, or `whole_page`,
    everything on the page; the field is `scope`. A document has one view.


    ## The credential


    Every call carries `Authorization: Bearer <key>`. The bearer value is an API
    key from `https://app.getclean.ai` or an access token issued by
    `https://auth.getclean.ai/realms/getclean`. Either resolves to one account
    with its scopes, its cap on one call, its budgets, its policy and its
    default run. A credential in the query string is ignored. A call with no
    usable credential is answered `401` with `WWW-Authenticate: Bearer
    realm="getclean",
    resource_metadata="https://api.getclean.ai/.well-known/oauth-protected-resource"`.
    That address serves the API's protected resource metadata (RFC 9728) to
    anyone, outside the versioned paths, with `Cache-Control: max-age=3600`:
    `resource` `https://api.getclean.ai`, `authorization_servers` the one
    issuer, `scopes_supported` the nine scopes, `bearer_methods_supported`
    `["header"]`. It is not an operation of this contract. An agent that arrives
    with nothing follows it to the issuer and its device sign-in.


    ## HEAD, 405 and 406


    Every `GET` of both families answers `HEAD` at once with the headers the
    `GET` would send and no body; a `HEAD` on `get_job` does not wait. The
    contract declares no `HEAD` operations. A method the resource does not offer
    is answered `405` with `Allow`; a representation it cannot give, `406`; each
    a problem of type `about:blank` whose title is the status's reason phrase.
    The contract declares neither per operation.


    ## What every answer promises, and what it does not


    - The reason `whole` means that everything you asked for fit. It does not
    promise that what came is the article: a page that is not what its address
    promises can come back as content, an error page sent with status 200, a
    subscription offer, a page with no main content, a portal that shows its
    results only inside a session. `not_found` comes from the status code alone.

    - A challenge, a block, a sign-in page or a purchase wall is recognized by
    signs in the response or on the page, never by its words. Such a sign
    decides before the status code. A wall with no known sign comes back as
    content. A page that declares its content not free carries the notice
    `paywall_declared`, whatever came.

    - The main content is what getclean keeps as the page's substance. It can
    leave real content out as another part; `left_out` names the kinds and sizes
    left out, and `get_contents` with `scope: whole_page` shows the rest, free.
    When no main content is found but the page has text or links, the whole page
    is delivered under `scope: whole_page` with the notice `no_main_content`.

    - Some regions of a page cannot be read as text. Where such a region covers
    part of the main content, the notice `unread_region` names its kind and
    size. A feed that grows as it is scrolled is read to a limit, never to its
    end. A frame from another site is an `embed` block with its address.

    - A page is read for at most `wait_seconds` and measured as it stands at
    that moment. A page still changing then carries the notice `not_settled`.
    The reason `deadline` means only that nothing readable had come by then.

    - Text that a reader of the page cannot see is kept apart in `hidden_text`,
    with the reason, never mixed into the content. Text hidden in a way getclean
    does not detect comes back as content. Hidden text is looked for in web
    pages and HTML files only. Keeping it apart is the default, since nothing is
    lost.

    - `title`, `authors`, `published_date`, `published_at`, `modified_date`,
    `publisher`, `canonical_url`, `language`, `language_versions`,
    `structured_data` and `declared_terms` are what the page or the document
    declares about itself; getclean does not check them against the content. A
    document's own dates often record when the file was made.

    - On a page whose headings are styled text rather than heading markup, the
    heading levels follow the styling and may nest wrongly.

    - The default sizes, `max_characters` 20,000 among them, were chosen with
    Latin script in mind. A text in a denser script, Chinese or Japanese, holds
    more in the same count, and no default is set per script.

    - A price that reads 0 may not be the price the page shows; check `counts`
    and the page's kind before trusting it.

    - The fingerprint compares only within one `scope`, one `execution.version`,
    one `execution.configuration` and one kind of source. A different
    fingerprint means the kept text differs, not that the article changed, since
    a site can serve two visits two different pages. `compare_contents` shows
    where.

    - On a web page, `unchanged` still reads the page in full and bills the
    fetch; what it saves is the text not sent and your agent's time, never the
    price. On a document whose bytes match the fingerprint's record, no page is
    parsed or billed.

    - Under one `execution.version` and `execution.configuration`, the same page
    or the same bytes give the same content and the same `s` and `b` ids on
    every call. A model step names its version and is not promised to repeat;
    `exact` and `near` matches repeat.

    - `challenge_served` may repeat on sites that challenge every new visitor.

    - Text inside images is not recognized on a page or a document that has a
    text layer; your agent reads it from `image.url`.

    - A link's kind is taken from its address, a guess; no request is made per
    link, so a link carries no size or served type.

    - An archive copy is the page as the archive served it, its links pointing
    into the archive. `fetched_at` is when getclean read the copy. `robots` is
    the site's own robots file as read now.

    - `page_number` is the page's position in the file, counted from 1;
    `page_label` is the label the document itself prints on the page, where it
    declares one.

    - A page that redirects elsewhere is delivered as what arrived; `final_url`
    and `redirects` show the path, and the notice `redirected` says when the
    final URL differs beyond the scheme, the host's case, a trailing slash and
    tracking parameters. Whether it is still the source is your agent's call.

    - `fetched_at` is getclean's own clock; no outside time source signs it.

    - A document's own arithmetic is not checked. Cells come as displayed,
    `formula_cells` says where a formula stood on a spreadsheet, and whether the
    figures satisfy the document's totals is your agent's check from the table's
    cells.

    - A highlight's place is a block id, a section id and the words as found,
    with a mark in the text returned, never an offset in characters, since the
    text is markdown whose offsets move with every mark and every format.

    - What this API does not do, and what it answers instead:
      - translate a page, or transcribe a recording; a recording's time ranges and frames: `unsupported_media_type`;
      - read a structure too large to take whole by its rows or a named column: `too_large`, with the count read;
      - sign in to a site for a fetch by URL: `sign_in_needed`; a registered login serves only a fetch made inside a search;
      - compose a text in force from its amendments, fill a template from several documents, or group copies: your agent's work, from each record's blocks and ids.
    - The price of a document is unknown before the call, since its page count
    is known only once it is downloaded. `max_cost` is the protection, and a
    fetch at the smallest call's price with `max_characters: 0` returns
    `pages.count` and the outline for one `contents` unit.

    - What your agent does from a record, with its blocks, ids and digests:
      - compare a clause with a clause of another document;
      - parse a displayed number, or a document's number format, which getclean does not declare;
      - judge whether a text was written by a machine, which getclean does not judge;
      - match two images, which getclean matches by identical bytes only; a web image's bytes are not kept;
      - read a reporter's page citation from an opinion's text.
    - A page exists only where the format has pages. A web page carries no page,
    and a page number printed in its text is your agent's to read.

    - An uploaded HTML file is read from its bytes alone, with nothing fetched
    and nothing run, so the styles, scripts and images it only points to are not
    loaded and its main content may differ from what the person saw; no
    screenshot is made.

    - A baseline you hold yourself is the whole text the record returned, since
    its hash is checked; a partial text cannot be compared.

    - What getclean did to a page is described by its published configuration at
    its version, with `left_out` and `hidden_text`; there is no log per read
    beyond them.

    - A markup change that keeps the text and its order is invisible to the
    comparison, since the record is the content.

    - A recognized page comes in the reading order the recognition produced,
    unmarked; headings come as text; pictures inside the page are not separated;
    a region the source blacked out is not told apart from a failed recognition.

    - An agent that checks a page again after its record expired gets
    `fingerprint_unknown` and pays the full price; it keeps the earlier text
    itself and compares with `compare_contents`.

    - A second-factor prompt counts as a sign-in page.

    - Content inside an app is not read; only pages and documents are.

    - The API has no field for a referrer or for a site's own settings; a
    setting reaches the read only through the URL.

    - A page's `declared_terms` are the page's; an image's licence is read on
    the image's own page.

    - getclean pays no site for a page. A page that asks a price ends
    `payment_required`, with the price in `cost.source_price`.
servers:
  - url: https://api.getclean.ai
security:
  - bearer: []
paths:
  /v1/contents:upload:
    post:
      summary: Upload contents
      description: >-
        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, the content with its
        structure intact, the map of its sections, the facts of the source, a
        fingerprint and the price, with `pages` saying how many pages were read,
        which failed and which were recognized from their image, and the record
        is kept for later reads.
      operationId: upload_contents
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
        - $ref: '#/components/parameters/Traceparent'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadContentsRequest'
            encoding:
              document:
                contentType: application/octet-stream
              json_schema:
                contentType: application/json
              max_cost:
                contentType: application/json
              max_source_price:
                contentType: application/json
              metadata:
                contentType: application/json
            examples:
              upload_contents.delivered:
                summary: >-
                  A ten-page PDF with a text layer, the document part carrying
                  the file's bytes
                value:
                  document: minutes.pdf
              upload_contents.job:
                summary: >-
                  A 312-page document with three scanned pages, under a ceiling
                  of one dollar
                value:
                  document: records.pdf
                  max_cost:
                    amount: '1.0000'
                    currency: USD
      responses:
        '201':
          description: >-
            The parse finished within `wait_seconds`: `ContentsUpload` with
            `contents` set, the record with the members its outcome carries and
            its `cost`, and `Location` naming the record.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentsUpload'
              examples:
                upload_contents.delivered:
                  summary: >-
                    A ten-page PDF with a text layer, parsed whole within the
                    wait
                  value:
                    contents:
                      id: cnt_2Kp0zzrSBNSNtgjapZm9pq
                      outcome:
                        kind: delivered
                        reason: whole
                      notices: []
                      fetched_at: '2026-11-04T10:05:00Z'
                      fingerprint: 'sha-256=:Ab3QtW7hCl7ACP+qfkR6P97Od1HtkFFDIcl9B4pPos0=:'
                      scope: main
                      record_scope: main
                      formats:
                        - markdown
                      truncated: false
                      markdown: '# Minutes of the meeting…'
                      counts:
                        characters: 18400
                        blocks:
                          heading: 6
                          text: 40
                        links: {}
                      source:
                        redirects: []
                        media_type: application/pdf
                        carrier: upload
                        filename: minutes.pdf
                        document_digest: 'sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:'
                        title: Minutes
                        authors: []
                        published_date: '2026-09-01'
                        published_date_precision: day
                        published_date_basis: document_properties
                        modified_date: null
                        language: en
                        language_versions: []
                        robots: not_applicable
                        declared_terms: []
                        structured_data: []
                        origins: []
                      pages:
                        count: 10
                        parsed_count: 10
                        failed_pages: []
                        recognized: []
                        pictured: []
                      execution:
                        version: 1.0.0
                        configuration: cfg-2026-11
                        models: []
                        elapsed_seconds: 3.2
                      cost:
                        ceiling:
                          amount: '1.0000'
                          currency: USD
                        actual:
                          amount: '0.0150'
                          currency: USD
                        units:
                          contents: 1
                          document_pages: 10
                        replayed: false
                      retention: hold
                      run_id: run_default
                      expires_at: '2026-11-06T10:05:00Z'
                      request_id: req_01MWhgMG0UHPXXGtnjhJJO
                    request_id: req_01MWhgMG0UHPXXGtnjhJJO
        '202':
          description: >-
            The parse goes on: `ContentsUpload` with `job` set, `Location`
            naming the job and `Retry-After` saying when to read it; `get_job`
            reads the job, and `get_contents` the record once `contents_id` is
            set.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Location:
              $ref: '#/components/headers/Location'
            Retry-After:
              $ref: '#/components/headers/RetryAfterRequired'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentsUpload'
              examples:
                upload_contents.job:
                  summary: >-
                    A 312-page document with three scanned pages, its parse
                    running as a job
                  value:
                    job:
                      id: job_8Rt2mqXKclxu58MCwLkSCV
                      kind: upload_contents
                      state: running
                      finished: false
                      stage: recognizing
                      counts:
                        parsed_count: 41
                        failed_count: 0
                        remaining_count: 271
                      cost:
                        ceiling:
                          amount: '1.0000'
                          currency: USD
                        actual:
                          amount: '0.0610'
                          currency: USD
                        units:
                          contents: 1
                          document_pages: 41
                          recognized_pages: 3
                        replayed: false
                      retry_after_seconds: 20
                      created_at: '2026-11-04T10:02:11Z'
                      updated_at: '2026-11-04T10:02:41Z'
                      request_id: req_01LyBFDAgNmn3TTbQ2Fe4r
                    request_id: req_01LyBFDAgNmn3TTbQ2Fe4r
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '422':
          $ref: '#/components/responses/Problem422'
        '429':
          $ref: '#/components/responses/Problem429'
        '451':
          $ref: '#/components/responses/Problem451'
        '500':
          $ref: '#/components/responses/Problem500'
        '503':
          $ref: '#/components/responses/Problem503'
components:
  parameters:
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        One key per logical call, so a retry is never billed twice.


        Required on this operation, where a duplicate would cost the most;
        without it the call is `400 invalid-request` naming the header. The SDKs
        fill a fresh key when you give none and send the same key on every retry
        of that call; the command line and the MCP server do the same. Give your
        own key when your program retries across processes, so the second run
        finds the first answer.


        The form: 1 to 255 visible ASCII characters, used exactly as sent, so a
        value written as a quoted Structured Field String keeps its quotes as
        part of the key. That is a stated departure from the IETF draft
        `draft-ietf-httpapi-idempotency-key-header`, revision 08, which is not
        yet a standard; this parameter documents the form in full.


        What a repeated key does:

        - The same key with the same body returns the first answer again, with
        this call's `request_id`, the current `expires_at` and `replayed` true
        on every `cost`. Nothing is billed again. On the upload the body is
        compared by a digest over the document and the fields, and a retried
        start with the same key is the same job.

        - The same key while the first call still runs: `409
        idempotency-key-in-flight`, with `Retry-After`.

        - The same key with another body: `422 idempotency-key-reused`.


        Answers are stored for 24 hours, per account, for billed answers and
        running jobs only. A call that may bill is kept in the store from its
        start, so a second call with its key meets the `409` while it runs.
      example: 7c2e9b10-4d3f-4a6b-9e81-0f5a6c7d8e92
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[!-~]{1,255}$
    Traceparent:
      name: traceparent
      in: header
      required: false
      description: >-
        Your own trace id for the call, the W3C Trace Context `traceparent`
        header, optional on every operation. getclean logs it with the call, so
        a request in your traces can be matched to its `Request-Id`, and never
        forwards it to a site or a source, a stated departure from W3C Trace
        Context section 3.4, which asks a vendor to pass it on. A malformed
        value is ignored, never refused, as the same recommendation asks.
      schema:
        type: string
  schemas:
    UploadContentsRequest:
      type: object
      description: >-
        What you send to `upload_contents`, as `multipart/form-data`: every
        field is a part under its own name, and a list field is one part per
        value. Send either `document`, the file itself, or `url`, where the file
        is; both at once is refused `exclusive`, neither `required`. A boolean
        is the text `true` or `false`; a number is decimal text; `json_schema`,
        `max_cost`, `max_source_price` and `metadata` are JSON parts; an empty
        value of a scalar field means the same as leaving it out. The form is
        closed: a field it does not list is refused `invalid-field`,
        `unknown_field`, and `scope`, `as_of_date`, `subject_country` and
        `subject_language`, which belong to a page and not to a file, are
        unknown here.
      additionalProperties: false
      properties:
        document:
          type: string
          format: binary
          description: >-
            The file to read, as the one file part, at most 100 MiB, with any
            media type on the wire. The part's `filename` and `Content-Type` are
            hints only: the bytes decide the type, among
            `Limits.document_media_types`; where the bytes alone cannot tell,
            the declared type, then the extension, then plain text. A still
            image is read as one scanned page. A compressed file such as a ZIP,
            a mailbox file, a saved web archive, an audio or a video file is
            refused as the record's outcome `unsupported_media_type`. One of
            `document` and `url` is required.
        url:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            Where the file is, http or https, at most 2,048 characters, under
            the same address and domain rules as a fetch. getclean downloads it
            and reads it as an upload, as a job when the reading outlives
            `wait_seconds`. A URL that serves a web page is a record `refused`,
            `unsupported_media_type`, with the message naming `fetch_contents`.
            One of `document` and `url` is required.
          examples:
            - https://example.com/filings/annual-2025.pdf
        captured_url:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            The address the page you saved came from, when `document` is a page
            you captured yourself, as you state it; recorded as `source.url`
            with `carrier` `upload`, so the record says where the page was seen.
            http or https, at most 2,048 characters; a scheme other than http or
            https is refused `syntax`. With `document` only; with `url` it is
            refused `dependent`. Default none.
          examples:
            - https://shop.example/offer
        captured_at:
          type: string
          format: date-time
          description: >-
            When you saved the page, as you state it, an RFC 3339 instant, kept
            in UTC; recorded as `source.captured_at`. A value that is not an RFC
            3339 instant is refused `syntax`. With `document` only; with `url`
            it is refused `dependent`. Default none.
          examples:
            - '2026-11-04T08:41:03Z'
        baseline_fingerprint:
          type: string
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: >-
            The fingerprint of a copy you already hold, as a record returned it,
            `sha-256=:…:`. The bytes are checked first: when a record of this
            account issued the fingerprint and the file's `document_digest`
            matches it, the answer is `unchanged` with no parse and no page
            billed, at this call's price. Otherwise the parse runs and bills its
            pages, and a content fingerprint that matches then answers
            `unchanged`. Default none. A malformed value is refused `syntax`; a
            fingerprint no record of this account issued makes the notice
            `fingerprint_unknown`, and the parse runs whole.
          examples:
            - 'sha-256=:Ab3QtW7hCl7ACP+qfkR6P97Od1HtkFFDIcl9B4pPos0=:'
        max_characters:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 20000
          description: >-
            The most text to return, in characters. `0` returns no text but the
            map of sections and the facts, which is how you see a document's
            shape before reading its text. Default 20,000; `0`, or 1,000 to
            1,000,000; a value between 1 and 999 is refused `bound`.
        formats:
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          default:
            - markdown
          description: >-
            The formats to return, 1 to 5 of these, one part per value:
            `markdown`, the content as one markdown string; `html`, as clean
            HTML; `doclang`, as DocLang, an XML that keeps each block with its
            place on the page, on an HTML file only; `json`, as `Block` objects;
            `links`, every link with its kind. Default `["markdown"]`. A form
            carries no empty list, so the map and the facts alone come by
            `max_characters: 0`. `screenshot` and `raw_html` are not values
            here, since an upload reads a file and never a live page. An open
            set; a repeated value is refused `duplicate`, a value outside the
            set `not_allowed`, and `doclang` on a document that is not HTML
            makes the notice `field_not_applicable`.
          items:
            type: string
            minLength: 1
            description: One of the formats the field lists.
            examples:
              - markdown
              - html
              - doclang
              - json
              - links
        block_kinds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            Keep only blocks of these kinds, in every format and in every model
            step: 1 to 10 of `text`, `heading`, `code`, `math`, `divider`,
            `interactive`, `table`, `image`, `embed`, `media`, an open set, one
            part per value. Default: every kind. In a document only `text`,
            `heading`, `table`, `image`, `math` and `code` occur; an HTML file
            takes every kind. An empty list is refused `bound`, a repeated value
            `duplicate`. When nothing would use it, no text format, no `links`,
            no `highlights`, no `json_schema` and no `summary`, the notice
            `field_not_applicable` says so.
          items:
            type: string
            minLength: 1
            description: One of the block kinds the field lists.
            examples:
              - text
              - heading
              - code
              - math
              - divider
              - interactive
              - table
              - image
              - embed
              - media
        highlights:
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          description: >-
            Words or questions to find in the content and mark where they stand,
            as on `fetch_contents`: 1 to 5 strings of 1 to 4,000 characters
            each, one part per value. Each string is one query, and every place
            it finds carries its position as `query_index`. Default none.
            Sending this without `deterministic_only` needs `contents:model`,
            since a string may need a model. A string found verbatim costs
            nothing; the strings a model had to judge cost one model step for
            the whole call. On recognized text, `exact` and `near` match the
            recognized words; `near` forgives case and end punctuation, and
            neither forgives a recognition error.
          items:
            type: string
            minLength: 1
            maxLength: 4000
        json_schema:
          type: object
          description: >-
            Your own fields, filled from the content by a model, each value with
            the words it came from; one model step, needs `contents:model`. A
            JSON part: a JSON Schema 2020-12 object whose root is `type: object`
            with `properties`, at most 50 KB. Default none. A schema that is not
            valid JSON Schema is refused `syntax`; one whose root is not `type:
            object`, that has no `properties`, or whose `pattern` needs
            backtracking is refused `not_allowed`. Under the request's
            `deterministic_only` it is refused `model-work-refused`; under a key
            whose policy forbids model work, `policy-limit-exceeded`.
        summary:
          type: boolean
          default: false
          description: >-
            Have a model write a summary of the content, at most 1,500
            characters, in the content's language; one model step, needs
            `contents:model`. Default false. Under the request's
            `deterministic_only` it is refused `model-work-refused`; under a key
            whose policy forbids model work, `policy-limit-exceeded`.
        deterministic_only:
          type: boolean
          default: false
          description: >-
            Turn off every step whose output could differ between two runs of
            the same bytes: no judged highlight, no schema fill, no summary. The
            text and the ids repeat on every call in any case; with this on,
            every other part of the answer repeats too. Text recognition on a
            page without a text layer still runs and is listed, since it repeats
            under one version. Default false. A key whose policy forbids model
            work makes it true, with the notice `default_set_by_policy`; sending
            false under such a key is `policy-limit-exceeded`.
        recognition_languages:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            The languages to expect on pages without a text layer, 1 to 10 BCP
            47 tags of 1 to 35 characters each, among
            `Limits.recognition_languages`, one part per value; another is
            refused `not_allowed`. Default detected: the document's declared
            language, else the language of its text, else the script found on
            the page. With no such page it has no effect and makes no notice.
          items:
            type: string
            minLength: 1
            maxLength: 35
        wait_seconds:
          type: number
          minimum: 5
          maximum: 90
          default: 30
          description: >-
            The most seconds this call may work before it answers, counted from
            the moment the work starts; time spent waiting to start is not
            counted. A parse that finishes inside it answers `201` with the
            record; one that needs more answers `202` with a job and runs on. 5
            to 90; default 30.
        max_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most this call may cost, a `Money` as a JSON part in the
            account's currency, reserved at the start against the balance and
            the budgets. A long scan is the most expensive call there is, since
            each recognized page bills two page units, so set it with that in
            mind. Default the key's cap on one call. A value below the smallest
            call's price is refused `cost-exceeds-cap`, with `minimum_cap`.
        max_source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The most you would allow getclean to pay a site that asks a price
            for the document at `url`, a `Money` as a JSON part; with `document`
            it does nothing, the notice `field_not_applicable`. getclean pays no
            site, whatever the value: a site that asks a price ends
            `payment_required`, with the price in `cost.source_price`. Default
            none.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the record is kept. `none` keeps nothing past the delivery:
            when the parse ran as a job, the record waits for the first
            `get_contents`, which is its delivery, and is erased after that
            answer. `hold` keeps the record 48 hours after its last call, at
            most 30 days, and is allowed only under a `hold` policy, since a
            request never loosens the key. Default the key's `policy.retention`.
        pinned_version:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The version of getclean to run under, at most 64 characters; it
            fixes how documents are read and how pages are recognized, and
            `execution.version` equals it. Default the current version,
            `Limits.current_version`. A version not served, never or no longer,
            is `version-withdrawn`, with the versions served.
          examples:
            - 1.0.0
        run_id:
          type: string
          pattern: ^run_(default|[A-Za-z0-9]{22})$
          default: run_default
          description: >-
            The run the record belongs to, an existing run of the key; a key has
            one run, `run_default`. Default the key's default run. An unknown
            run is refused `not_allowed`.
        metadata:
          type: object
          minProperties: 1
          maxProperties: 20
          propertyNames:
            minLength: 1
            maxLength: 64
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 512
          description: >-
            Your own labels, a JSON part, returned on the record as sent and
            never passed to a site: at most 20 string pairs, keys of 1 to 64
            characters, values of 1 to 512. Default none. An empty map is
            refused `bound`.
    ContentsUpload:
      type: object
      description: >-
        What `upload_contents` answers. On a `201` it carries `contents`, the
        record, since the parse finished within `wait_seconds`; on a `202` it
        carries `job`, since the parse goes on. Exactly one of the two is
        present on the wire; both are optional in this schema because one schema
        serves both answers. On a `202`, read the job with `get_job` until it is
        final, then read the record with `get_contents`.
      required:
        - request_id
      properties:
        contents:
          $ref: '#/components/schemas/Contents'
          description: >-
            The record, with the members its outcome carries and its `cost`.
            Present on a `201`.
        job:
          $ref: '#/components/schemas/Job'
          description: >-
            The job, stored before this answer is sent, so a read of it never
            misses. Present on a `202`.
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: This call's id, the same as the `Request-Id` header.
          examples:
            - req_01MWhgMG0UHPXXGtnjhJJO
    Money:
      type: object
      description: >-
        One sum of money, the one object for every sum in both families. A sum
        you send names the account's currency; another currency is refused
        `invalid-field`, `not_allowed`, with the account's currency in
        `allowed_values`.
      additionalProperties: false
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,4})?$
          description: >-
            The amount as a decimal string, never negative, with at most four
            fraction digits; `0.5` and `0.5000` are the same sum.
          examples:
            - '0.0500'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: The currency's ISO 4217 code, three capital letters.
          examples:
            - USD
    Retention:
      type: string
      description: >-
        How long a record is kept; `hold`, 48 hours after its last call and at
        most 30 days from its making, or `none`, nothing kept past the answer. A
        closed set.
      enum:
        - hold
        - none
    Contents:
      type: object
      description: >-
        One record: one fetch or upload of one source at one moment, with a
        `cnt_` id, kept 48 hours after its last call and at most 30 days from
        its making. Its facts never change. It is the answer of `fetch_contents`
        and of `get_contents`, and the record inside the answers of
        `upload_contents` and `fetch_contents_batch`. It reads in one order:
        what happened; the notices to read first; when it was read; the content
        in the formats asked, or the map of sections when the text did not fit;
        the facts of the source; the fingerprint; the price.


        What is the record's and what is this answer's. The record's facts come
        as stored on every later answer: `outcome`, `fetched_at`, `fingerprint`,
        `record_scope`, `source`, `pages`, `execution`, `retention` and the
        fetch's model work. Each answer adds only its own: `scope`, the view it
        delivers; `truncated`; `formats`; its notices; `request_id`;
        `expires_at`. A member whose line states a condition is present only
        while the condition holds and absent otherwise, never `[]` or null in
        its place; a scalar is null only where its line says so.


        Which members each outcome carries:

        - Delivered `whole`, `sections_only` or `matching_sections`, and every
        partial record: `id`, `outcome`, `notices`, `fetched_at`, `fingerprint`,
        `scope`, `formats`, `truncated`; the formats asked for among `markdown`,
        `html`, `doclang`, `blocks`, `links`, `screenshot` and `raw_html`;
        `sections` by its rule; `counts`, `source`, `execution`, `retention`,
        `run_id`, `expires_at`, `request_id`, `record_scope`; `hidden_text` and
        `left_out` on a web page or an HTML file; `highlights`, `summary`,
        `schema_values`, `schema_statuses`, `pages`, `cost` and `metadata` by
        their rules.

        - Delivered `unchanged`, as the fetch answers it: the first eight, with
        `formats` as `[]` and `truncated` false; `source`, `execution`,
        `retention`, `run_id`, `expires_at`, `request_id`, `record_scope`;
        `cost` and `metadata` by their rules. The record holds the content,
        which `get_contents` answers.

        - Failed, refused or needs a person: `id`, `outcome`, `notices`,
        `fetched_at`, `truncated` false, `source`, `execution`, `retention`,
        `run_id`, `expires_at`, `request_id`; `pages` when the page count was
        read and `sections` when the outline was read; `cost` and `metadata` by
        their rules; `cost.actual` zero.


        Which members each kind of source carries. A live page is a web page
        read now; an archive copy is a page read under `as_of_date`; a document
        is a file, read at a URL or uploaded; an HTML file is an upload read as
        a page.


        | Member | Present on | Not on |

        |---|---|---|

        | `screenshot`, when asked | a live page | an archive copy, a document,
        an upload |

        | `raw_html`, when asked | a live page, an archive copy | a document, an
        upload |

        | `doclang`, when asked | a live page, an archive copy, an HTML file | a
        document that is not HTML |

        | `hidden_text`, `left_out` | a live page, an archive copy, an HTML file
        | a document that is not HTML |

        | `scope` `whole_page` | a live page, an archive copy, an HTML file | a
        document, which has one view |

        | `pages`, and the page numbers and labels on blocks, sections and
        highlights | a document with pages; an unpaged document carries `pages`
        with a count by characters and no page numbers | a page |

        | `pages.recognized`, `Block.confidence`, `Table.cell_confidences` | a
        document with pages that have no text layer | every other source |

        | `Table.top_left_cell`, `Table.formula_cells` | a spreadsheet | every
        other source |

        | `source.final_url`, `status_code`, `publisher`, `canonical_url`,
        `access_kind`, `profile` | a live page, an archive copy, a document at a
        URL | an upload |

        | `source.visitor` | a live page, a document at a URL | an archive copy,
        an upload |

        | `source.archive`, `archives_consulted`, `next_capture_at` | an archive
        copy | every other source |

        | `source.filename`, `source.captured_at` | an upload | every other
        source |

        | `source.document_digest` | a document | a page |

        | `source.url` | every source but an upload sent without `captured_url`
        | |


        When a record is not delivered, `outcome.message` says what may work
        next, and the table under `Outcome.reason` gives it for every reason.
      required:
        - id
        - outcome
        - notices
        - fetched_at
        - truncated
        - source
        - execution
        - retention
        - run_id
        - expires_at
        - request_id
      properties:
        id:
          type: string
          pattern: ^cnt_[A-Za-z0-9]{22}$
          description: >-
            The record's id: `cnt_` and 22 random characters, which cannot be
            guessed. Another account's id answers `404`.
          examples:
            - cnt_3Fk9abaUhNX7t2eKkgfd3e
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: >-
            What happened, first. It is the fetch's fact, and no later call
            rewrites it.
        notices:
          type: array
          description: >-
            What to read before the content, never an error. On the fetch's own
            answer every notice is that answer's own; on every later answer
            about the record, the notices kept with it come first, each with
            `held` true, then that answer's own. `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the fetch or the parse started, RFC 3339 in UTC in whole
            seconds, by getclean's clock.
          examples:
            - '2026-11-04T08:40:12Z'
        fingerprint:
          type: string
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: >-
            A hash of the content. Two records with the same fingerprint hold
            the same text, so you can tell whether a page changed between two
            fetches without comparing their text. It is the sha-256 of the
            record's markdown as the fetch kept it under `record_scope`, with
            nothing filtered out and no highlight marks, after Unicode NFC and
            LF line ends and without any front matter, written in the form of
            RFC 9530, `sha-256=:…:`. Anyone who holds that whole markdown, as
            `get_contents` returns it under `record_scope` with a
            `max_characters` that fits all of it, no `block_kinds` and no
            highlights, can compute the same value. It compares only within one
            `scope`, one `execution.version`, one `execution.configuration` and
            one kind of source. Present on delivered and partial records.
          examples:
            - 'sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:'
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view this answer delivers, `main` or `whole_page`; on the
            fetch's own answer, the record's own. Present on delivered and
            partial records.
        formats:
          type: array
          description: >-
            The formats this answer carries, among `markdown`, `html`,
            `doclang`, `json`, `links`, `screenshot` and `raw_html`, an open
            set; `[]` on `unchanged` as the fetch answers it. Present on
            delivered and partial records.
          items:
            type: string
            examples:
              - markdown
              - html
              - doclang
              - json
              - links
              - screenshot
              - raw_html
        truncated:
          type: boolean
          description: >-
            True when text was asked for, `max_characters` above `0` with a text
            format, and it did not fit, so the map came instead. This answer's
            fact, not the record's.
        markdown:
          type: string
          x-third-party: true
          description: >-
            The content as one markdown string, its inline formatting kept:
            bold, italic, strikethrough, code and links as markdown, `<sup>` and
            `<sub>` as inline HTML, a footnote reference as `[^n]`, and `<mark
            id="h1">…</mark>` around each highlight. Present when asked for and
            text came. Third-party text as the source wrote it, which may carry
            instructions.
        html:
          type: string
          x-third-party: true
          description: >-
            The content as clean HTML, with the highlight marks. Present when
            asked for and text came. Third-party text as the source wrote it,
            which may carry instructions.
        doclang:
          type: string
          x-third-party: true
          description: >-
            The content as DocLang, an XML that keeps each block with its place
            on the page in pixels; no highlight marks. Present when asked for
            and text came, on a web page or an HTML file only. Third-party text
            as the source wrote it, which may carry instructions.
        blocks:
          type: array
          description: >-
            The content as `Block` objects, each with its `highlight_ids`. Only
            the text counts against `max_characters`, not the other members.
            Present when asked for and text came.
          items:
            $ref: '#/components/schemas/Block'
        links:
          type: array
          description: >-
            Every link of the content with its kind, at most 1,000; the notice
            `links_cut` says when the list was cut, and `list_links` has the
            rest. Present when asked for.
          items:
            $ref: '#/components/schemas/Link'
        screenshot:
          $ref: '#/components/schemas/Screenshot'
          description: >-
            A picture of the whole page, of a live page only. Present when asked
            for at fetch time on a live page; carried on every later
            `get_contents` under `retention` `hold`; sent inline once under
            `none`.
        sections:
          type: array
          description: >-
            The map of the content: one row per section with its id, title,
            level and size in characters, and no text. Present when
            `max_characters` is `0`, or when a text format was asked for and the
            text did not fit. Level 1 and `s0` are always there; deeper levels
            come while their rows fit, and the notice `sections_cut` says when
            levels were left out.
          items:
            $ref: '#/components/schemas/Section'
        counts:
          $ref: '#/components/schemas/ContentsCounts'
          description: >-
            How much the record holds: characters, blocks by kind, links by
            kind. The record's own under its own view; this answer's under
            `scope` `whole_page` on a record fetched under `main`. Present on
            delivered and partial records, except `unchanged` as the fetch
            answers it.
        highlights:
          type: array
          description: >-
            Every place your `highlights` strings found, in document order, at
            most 50, each naming the string that found it by `query_index`.
            Present when `highlights` were sent at fetch time; kept with the
            record, and returned on `get_contents` with the marks placed
            wherever a highlighted block appears in the text returned.
          items:
            $ref: '#/components/schemas/Highlight'
        summary:
          type: string
          x-third-party: true
          maxLength: 1500
          description: >-
            The summary a model wrote of the content, at most 1,500 characters,
            in the content's language, with no link and no image in it. Present
            when `summary` was sent and the summary was written; kept with the
            record. Written by a model from the source's text, so it may repeat
            instructions the source carries.
        schema_values:
          type: object
          x-third-party: true
          description: >-
            Your schema filled from the content, in the schema's own shape, a
            value only where the content states it and never a plausible guess;
            a property with nothing to fill is left out. Present when
            `json_schema` was sent and filled; kept with the record. Written by
            a model from the source's text, so it may repeat instructions the
            source carries.
        schema_statuses:
          type: object
          description: >-
            How each property of your schema was filled, one `SchemaStatus` per
            property, keyed by a JSON Pointer into `schema_values`: a nested
            property by its path, an array property by its own pointer and not
            its items. Present when `json_schema` was sent and filled; kept with
            the record.
          additionalProperties:
            $ref: '#/components/schemas/SchemaStatus'
        hidden_text:
          type: array
          description: >-
            Text a reader of the page could not see, kept apart from the content
            with the reason it was hidden; at most 50 items, with the notice
            `hidden_text_cut` when cut. Present on a web page or an HTML file,
            delivered or partial, except `unchanged` as the fetch answers it;
            `[]` when there is none.
          items:
            $ref: '#/components/schemas/HiddenText'
        left_out:
          type: array
          description: >-
            The parts of the page outside the main content, each with its kind
            and size, so you know what was left out and can read it under
            `scope` `whole_page`, where this is `[]`. Present as `hidden_text`
            is.
          items:
            $ref: '#/components/schemas/LeftOut'
        source:
          $ref: '#/components/schemas/Source'
          description: >-
            The facts of the source as the page or the document declares them,
            and the facts of the read: the address, the redirects, the status,
            the title, the authors, the dates, the language, the publisher's
            profile, and what the site declares about its use.
        pages:
          $ref: '#/components/schemas/DocumentPages'
          description: >-
            The pages of a document: how many, how many were parsed, which
            failed, which were recognized from an image. Present on every
            document under every outcome that parsed or counted it,
            `cost_capped` with no page parsed and `too_large` with the count
            read included; absent on a web page. On a format without pages,
            `count` is the equivalent by characters and `failed_pages`,
            `recognized` and `pictured` are `[]`.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How the record was made: getclean's version and configuration, every
            model step with its version, and the time it took.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The bill for making the record. Present on the record as answered by
            the call that billed it, `fetch_contents`, `upload_contents` or
            `fetch_contents_batch`, zero when nothing was billed; absent on the
            record as answered by `get_contents`, which is free.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the record is kept, `hold` or `none`. Under `none` nothing
            is kept past this answer, and `expires_at` is the answer's own
            moment.
        run_id:
          type: string
          pattern: ^run_(default|[A-Za-z0-9]{22})$
          description: >-
            The run the record belongs to; a later model step on the record is
            charged to it.
          examples:
            - run_default
        metadata:
          type: object
          description: Your own labels, returned as sent. Present when sent.
          additionalProperties:
            type: string
        expires_at:
          type: string
          format: date-time
          description: >-
            When the record expires. This call moved it ahead: 48 hours from
            now, never past 30 days from the record's making; under `retention`
            `none` it is this answer's own moment. After that, a call on the
            record is `410 contents-expired` for 30 days, then `404`.
          examples:
            - '2026-11-06T08:40:12Z'
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: >-
            This call's id, the same as the `Request-Id` header; on a replay,
            this call's and not the first call's.
          examples:
            - req_01JzsALAAlsNsdoVz1EElr
        record_scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view the fetch ran under, `main` or `whole_page`; the
            fingerprint hashes this view's markdown. Present on delivered and
            partial records.
        raw_html:
          $ref: '#/components/schemas/RawHtml'
          description: >-
            The page's bytes exactly as the server sent them, with their digest,
            size and media type. Present when asked for at fetch time on a live
            page or an archive copy; carried on every later `get_contents` under
            `retention` `hold`; sent inline once under `none`.
    Job:
      type: object
      description: >-
        A parse that outlives its request. `completed` when its record is
        delivered or partial, `failed` otherwise, with `problem` set when
        nothing was made; `canceled` keeps and bills the pages done. Kept 30
        days after its end, then `410 job-expired` for 30 days, then `404`. A
        job carries no notices and no version.
      required:
        - id
        - kind
        - state
        - finished
        - counts
        - cost
        - created_at
        - updated_at
        - request_id
      properties:
        id:
          type: string
          pattern: ^job_[A-Za-z0-9]{22}$
          description: >-
            The job's id, `job_` and 22 random characters; another account's id
            answers `404`.
          examples:
            - job_8Rt2mqXKclxu58MCwLkSCV
        kind:
          type: string
          description: The operation that started the job, `upload_contents`; an open set.
          examples:
            - upload_contents
        state:
          type: string
          description: >-
            The job's state: `queued`, `running`, `completed`, `failed` or
            `canceled`; the last three are final. An open set.
          examples:
            - queued
            - running
            - completed
            - failed
            - canceled
        finished:
          type: boolean
          description: True once the state is final.
        stage:
          type: string
          description: >-
            What the job is doing now, `parsing` or `recognizing`; an open set.
            Absent on `queued` and when final.
          examples:
            - parsing
            - recognizing
        counts:
          $ref: '#/components/schemas/JobCounts'
          description: >-
            The pages parsed, failed and remaining, adding up to `pages.count`;
            zeros while the job is queued or the count unread.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The units so far on every read, the final figure once `finished`;
            zero on a cancel with no page done.
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: The record's outcome. Present once a record exists.
        retry_after_seconds:
          type: integer
          minimum: 1
          description: >-
            Seconds to wait before reading again, equal to the `Retry-After`
            header of `get_job` and `cancel_job`; inside a `JobPage`, each job's
            own wait. Absent once final.
        contents_id:
          type: string
          pattern: ^cnt_[A-Za-z0-9]{22}$
          description: >-
            The record the job made, read by `get_contents`. Present once a
            record exists.
          examples:
            - cnt_f9a1LknFzePvIKv1pEkejs
        problem:
          $ref: '#/components/schemas/Problem'
          description: >-
            Why the job failed before a record existed, without `status`, its
            `request_id` and `instance` the upload's. Present only on a job that
            failed with no record.
        created_at:
          type: string
          format: date-time
          description: When the job started, RFC 3339 in UTC.
          examples:
            - '2026-11-04T10:02:11Z'
        updated_at:
          type: string
          format: date-time
          description: When the job last changed, RFC 3339 in UTC.
          examples:
            - '2026-11-04T10:14:52Z'
        expires_at:
          type: string
          format: date-time
          description: >-
            When the job expires, 30 days after it ended, RFC 3339 in UTC.
            Absent until final.
          examples:
            - '2026-12-04T10:14:52Z'
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: >-
            The id of the call this copy of the job came back in, the same as
            that call's `Request-Id` header.
          examples:
            - req_01Qm89u0cStrgTL7bxmqKa
    Problem:
      type: object
      description: >-
        An answer that is not a result: `application/problem+json`, RFC 9457,
        one shape for every status. Read `type` to know what happened,
        `who_must_act` to know whose move it is, and `change` or `violations` to
        know what to change. `type`, `title`, `detail`, `instance`,
        `request_id`, `who_must_act` and `retryable` are always present;
        `status` on a top-level problem; every other member when it applies. A
        problem never carries a stack trace, an internal address, a secret,
        another caller's data or text from a site or a source. A source's or a
        site's failure is never a problem: it is that item's outcome.
      required:
        - type
        - title
        - detail
        - instance
        - request_id
        - who_must_act
        - retryable
      properties:
        type:
          type: string
          format: uri
          description: >-
            An absolute URI that names the problem and leads to a page about its
            fix: `https://api.getclean.ai/problems/<name>`, the name being the
            last segment. Compare on it; it is kept for good. `about:blank` is
            used on 405 and 406 only, with the status's reason phrase as the
            title. Every type, with its status, whose move it is and its title:


            | Type | Status | Who acts | Title |

            |---|---|---|---|

            | `invalid-request` | 400 | caller | The request is invalid |

            | `page-token-invalid` | 400 | caller | The page token is invalid |

            | `unauthorized` | 401 | caller | The key is missing or rejected |

            | `insufficient-scope` | 403 | caller for an access token, account
            owner for an API key | The key lacks a scope this call needs |

            | `policy-limit-exceeded` | 403 | account owner | The key's policy
            forbids this |

            | `datasource-access-required` | 403 | account owner | The
            datasource needs a registered login |

            | `credit-exhausted` | 403 | account owner | The credit is exhausted
            |

            | `run-budget-exhausted` | 403 | account owner | The run's budget is
            exhausted |

            | `key-budget-exhausted` | 403 | account owner | The key's budget is
            exhausted |

            | `not-found` | 404 | caller | Not found |

            | `idempotency-key-in-flight` | 409 | caller, after the wait | The
            same request is still running |

            | `record-without-content` | 409 | caller | The record has no
            content |

            | `contents-expired` | 410 | caller | The record has expired |

            | `search-expired` | 410 | caller | The search has expired |

            | `job-expired` | 410 | caller | The job has expired |

            | `body-too-large` | 413 | caller | The body is too large |

            | `unsupported-media-type` | 415 | caller | The media type is not
            supported |

            | `invalid-field` | 422 | caller | A field is invalid |

            | `destination-refused` | 422 | caller | The destination is refused
            |

            | `model-work-refused` | 422 | caller | Model work is refused by the
            request |

            | `cost-exceeds-cap` | 422 | caller | The cost cap is below the
            smallest call |

            | `version-withdrawn` | 422 | caller | The version is no longer
            served |

            | `records-incomparable` | 422 | caller | The records cannot be
            compared |

            | `idempotency-key-reused` | 422 | caller | The idempotency key was
            reused with another body |

            | `no-datasource-can-run` | 422 | caller | No datasource can run
            this search |

            | `datasource-unknown` | 422 | caller | The datasource is unknown |

            | `datasource-not-searchable` | 422 | caller | The datasource has no
            search |

            | `domain-set-unknown` | 422 | caller | The domain set is unknown |

            | `rate-limit-exceeded` | 429 | caller, after the wait | The rate
            limit is exceeded |

            | `concurrency-limit-exceeded` | 429 | caller, after the wait | Too
            many calls are in flight |

            | `legal-block` | 451 | caller | Withheld under a legal demand |

            | `about:blank` | 405, 406 | caller | the status's reason phrase |

            | `internal-error` | 500 | service | The service failed |

            | `gateway-error` | 502 | service | A step behind the service failed
            |

            | `overloaded` | 503 | service | The service is overloaded |

            | `gateway-timeout` | 504 | service | A step behind the service
            timed out |
          examples:
            - https://api.getclean.ai/problems/invalid-request
            - https://api.getclean.ai/problems/page-token-invalid
            - https://api.getclean.ai/problems/unauthorized
            - https://api.getclean.ai/problems/insufficient-scope
            - https://api.getclean.ai/problems/policy-limit-exceeded
            - https://api.getclean.ai/problems/datasource-access-required
            - https://api.getclean.ai/problems/credit-exhausted
            - https://api.getclean.ai/problems/run-budget-exhausted
            - https://api.getclean.ai/problems/key-budget-exhausted
            - https://api.getclean.ai/problems/not-found
            - https://api.getclean.ai/problems/idempotency-key-in-flight
            - https://api.getclean.ai/problems/record-without-content
            - https://api.getclean.ai/problems/contents-expired
            - https://api.getclean.ai/problems/search-expired
            - https://api.getclean.ai/problems/job-expired
            - https://api.getclean.ai/problems/body-too-large
            - https://api.getclean.ai/problems/unsupported-media-type
            - https://api.getclean.ai/problems/invalid-field
            - https://api.getclean.ai/problems/destination-refused
            - https://api.getclean.ai/problems/model-work-refused
            - https://api.getclean.ai/problems/cost-exceeds-cap
            - https://api.getclean.ai/problems/version-withdrawn
            - https://api.getclean.ai/problems/records-incomparable
            - https://api.getclean.ai/problems/idempotency-key-reused
            - https://api.getclean.ai/problems/no-datasource-can-run
            - https://api.getclean.ai/problems/datasource-unknown
            - https://api.getclean.ai/problems/datasource-not-searchable
            - https://api.getclean.ai/problems/domain-set-unknown
            - https://api.getclean.ai/problems/rate-limit-exceeded
            - https://api.getclean.ai/problems/concurrency-limit-exceeded
            - https://api.getclean.ai/problems/legal-block
            - about:blank
            - https://api.getclean.ai/problems/internal-error
            - https://api.getclean.ai/problems/gateway-error
            - https://api.getclean.ai/problems/overloaded
            - https://api.getclean.ai/problems/gateway-timeout
        title:
          type: string
          description: The type's published title, as the table under `type` gives it.
          examples:
            - A field is invalid
        status:
          type: integer
          description: >-
            The HTTP status. Present on a top-level problem; absent on a problem
            nested in a batch result or a job, where it could not equal the
            response's status.
        detail:
          type: string
          description: >-
            One sentence that names what went wrong, written for a person to
            read. Always present. A credential is never echoed.
          examples:
            - formats holds a value outside its set.
        instance:
          type: string
          format: uri
          description: >-
            The URI of this one occurrence:
            `https://api.getclean.ai/requests/<request_id>`, with
            `/items/<index>` appended for a problem nested in a batch result.
            Unique per occurrence. It is an identifier and is not served as a
            page.
          examples:
            - https://api.getclean.ai/requests/req_01JSUEOJ23EQgBxGjfSpcD
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: >-
            This call's id, the same as the `Request-Id` header. A nested
            problem carries the call's id too.
          examples:
            - req_01JSUEOJ23EQgBxGjfSpcD
        who_must_act:
          type: string
          description: >-
            Whose move it is: `caller`, you; `account_owner`, the person who
            holds the account; `service`, getclean. A closed set. A site's or a
            source's failure is never a problem, so no value names them.
          enum:
            - caller
            - account_owner
            - service
        retryable:
          type: boolean
          description: >-
            True on the six types a retry can help: `idempotency-key-in-flight`,
            `rate-limit-exceeded`, `concurrency-limit-exceeded`, `overloaded`,
            `gateway-error` and `gateway-timeout`. False on every other type.
        retry_after_seconds:
          type: integer
          minimum: 1
          description: >-
            Seconds to wait before asking again, equal to the `Retry-After`
            header. Present when known.
        change:
          $ref: '#/components/schemas/ProblemChange'
          description: >-
            The fix as data: the field to change, the values or range it may
            take, or the operation to call instead. Present when a fix is data.
        violations:
          type: array
          description: >-
            Every fault of the request at once, each with where it is. Present
            on `invalid-field`, `model-work-refused` and `invalid-request`.
          items:
            $ref: '#/components/schemas/Violation'
        balance:
          $ref: '#/components/schemas/Money'
          description: The prepaid credit left. Present on `credit-exhausted`.
        amount_needed:
          $ref: '#/components/schemas/Money'
          description: >-
            What the limit that binds lacks for the smallest call: the call's
            price less what the limit holds. A balance of 0.0020 against a call
            of 0.0050 gives 0.0030. Present on `credit-exhausted`,
            `run-budget-exhausted` and `key-budget-exhausted`.
        funding_url:
          type: string
          format: uri
          description: >-
            The account owner's page for that balance or budget at
            `https://app.getclean.ai`. Present on `credit-exhausted`,
            `run-budget-exhausted` and `key-budget-exhausted`.
        minimum_cap:
          $ref: '#/components/schemas/Money'
          description: >-
            The smallest call's price, the least cap that would run it. Present
            on `cost-exceeds-cap`, and on `policy-limit-exceeded` when the key's
            cap is the limit.
        run_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: What is left of the run's budget. Present on `run-budget-exhausted`.
        key_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: What is left of the key's budget. Present on `key-budget-exhausted`.
        demand:
          type: string
          description: The legal demand made on getclean. Present on `legal-block`.
        demanded_by:
          type: string
          description: Who made the demand. Present on `legal-block`.
        applies_to:
          type: string
          description: What the demand covers. Present on `legal-block`.
        expired_at:
          type: string
          format: date-time
          description: >-
            When the record or the job expired, RFC 3339 in UTC. Present on
            `contents-expired`, `search-expired` and `job-expired`.
        scopes_required:
          type: array
          description: >-
            Every scope the call needs, among `contents:fetch`, `contents:read`,
            `contents:model`, `contents:delete`, `jobs:read`, `jobs:cancel`,
            `limits:read`, `search:run` and `search:read`, an open set. Present
            on `insufficient-scope`.
          items:
            type: string
            examples:
              - contents:fetch
              - contents:read
              - contents:model
              - contents:delete
              - jobs:read
              - jobs:cancel
              - limits:read
              - search:run
              - search:read
    Outcome:
      type: object
      description: >-
        What happened to one piece of work, first in every answer. A record's
        outcome is the fact of the call that made it, and no later read rewrites
        it.
      required:
        - kind
        - reason
      properties:
        kind:
          type: string
          description: >-
            What kind of thing happened, one of five: `delivered`, everything
            asked for came, or the map of sections came in place of text that
            did not fit; `partial`, the work stopped in the middle and what was
            done is kept; `failed`, the source did not give a page; `refused`, a
            rule stopped the read; `needs_person`, a person must act before this
            can work. A closed set.
          enum:
            - delivered
            - partial
            - failed
            - refused
            - needs_person
        reason:
          type: string
          description: >-
            Why it happened. An open set whose published values are below; each
            line says what the reason means and what may work next, and
            `message` carries that sentence when the reason has one.


            The contents family, the record of one source:


            | Reason | Kind | Means | What may work next |

            |---|---|---|---|

            | `whole` | delivered | everything asked for fit | |

            | `sections_only` | delivered | the text did not fit
            `max_characters`, so the map of sections came instead |
            `get_section` on a row, free |

            | `matching_sections` | delivered | the text did not fit; the
            sections holding your highlights came | `get_section` for the rest |

            | `unchanged` | delivered | the page matches your
            `baseline_fingerprint`; no text is sent, the fetch's price is billed
            | |

            | `pages_failed` | partial | some pages of a document could not be
            parsed; `pages.failed_pages` names them | |

            | `cost_capped` | partial | the parse stopped at `max_cost`, the
            key's cap or the balance; `message` says which | a larger
            `max_cost`, or the account owner funds the account or raises the cap
            |

            | `budget_capped` | partial | the parse stopped at the run's or the
            key's budget | the account owner raises the budget |

            | `time_capped` | partial | a document at a URL did not finish
            within `wait_seconds`, or a job passed its bound | `upload_contents`
            with the `url`, which parses it whole as a job |

            | `canceled` | partial | the job was canceled with pages already
            parsed; they are kept | |

            | `dns_timeout`, `connection_refused`, `connection_timeout`,
            `connection_terminated`, `tls_protocol_error`,
            `http_response_timeout`, `http_response_incomplete` | failed | the
            fetch failed on the way to the site, named as RFC 9209 names it | a
            retry later may work |

            | `dns_error`, `tls_certificate_error` | failed | the site's name
            did not resolve, or its certificate failed | the same request will
            not work |

            | `not_found` | failed | the site answered 404 or 410 | the same
            request will not work |

            | `access_denied` | failed | the site answered 401 or 403 | the same
            request will not work |

            | `payment_required` | failed | the site asked a price at the
            request, or answered 402, and no `max_source_price` covered it;
            `cost.source_price` is the price asked | a `max_source_price` |

            | `rate_limited` | failed | the site answered 429 | a retry later
            may work |

            | `server_error` | failed | the site answered 5xx | a retry later
            may work |

            | `http_error` | failed | another status that is not a page | the
            same request will not work |

            | `challenge_served` | failed | 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` |

            | `blocked` | failed | the site refused the visitor with a block
            page | the same request will not work |

            | `region_restricted` | failed | the page says it is not offered in
            the visitor's country | another `subject_country` |

            | `deadline` | failed | nothing readable by `wait_seconds` | a
            larger `wait_seconds` |

            | `empty` | failed | no text, no links and nothing to recognize |
            the same request will not work |

            | `corrupt_document` | failed | the document could not be opened |
            the same request will not work |

            | `no_history` | failed | no archive copy at or before the end of
            `as_of_date`; `source.archives_consulted` names the archives asked |
            the same date will not work |

            | `too_large` | refused | the page or document passed the largest
            size taken whole; for a document, `pages.count` and the outline
            still come | the same request will not work |

            | `destination_refused` | refused | the address resolved to, or a
            redirect reached, a place that is not globally reachable | the same
            request will not work |

            | `domain_not_allowed` | refused | a redirect reached a host outside
            the key's domain policy | the same request will not work under this
            key's policy |

            | `unsupported_media_type` | refused | a document type not taken, a
            container or a media file; or, on the upload, a `url` that serves a
            web page, where `fetch_contents` is the call | the same request will
            not work |

            | `password_protected` | refused | the document is locked | a person
            with the password |

            | `robots_disallowed` | refused | the site's robots file forbids
            getclean by its published name | the same request will not work |

            | `robots_unreachable` | refused | the robots file answered 5xx or
            not at all, which RFC 9309 reads as a full disallow | a retry later
            may work |

            | `legal_block` | refused | the site answered 451;
            `source.blocked_by` carries its link | another source, never another
            `subject_country` |

            | `sign_in_needed` | needs_person | a sign-in page stood where the
            page should be | a person signs in and uploads the saved page with
            `captured_url` |

            | `paywalled` | needs_person | a purchase wall stood where the page
            should be | a person |


            The search family, the search as a whole and each source's receipt:


            | Reason | Kind | Means | What may work next |

            |---|---|---|---|

            | `candidates` | delivered | one or more results | |

            | `none` | delivered | nothing matched; the receipt says what was
            searched | other wordings |

            | `corrected_question` | delivered | every result came for a wording
            getclean corrected; `interpretation.wordings` shows the correction |
            |

            | `sources_missing` | partial | a source or a wording gave no list
            while others did | a retry later may work for that source |

            | `rerank_missing` | partial | the deadline or the ceiling cut the
            reranking; the merged order came and `relevance_score` is null | a
            larger `wait_seconds` or `max_cost` |

            | `fetches_missing` | partial | some inline fetches did not finish
            or were cut; the notice `fetch_not_finished` names the candidates |
            `fetch_contents` on each |

            | `not_accepted_by_source` | failed | every source refused the
            question as written; a source's own words stand in `source_text` |
            another wording |

            | `source_unreachable` | failed | every source was down | a retry
            later may work |

            | `login_expired` | needs_person | a registered login expired | the
            account owner renews the login |

            | `fee_through_form` | needs_person | the source charges only
            through a form | a person |


            In a source's receipt, `datasources_searched[].outcome`, the failed
            reasons of the first table name what happened to that one source,
            with `deadline` for a source that had not answered at `wait_seconds`
            and `payment_required` for a fee above `max_source_price`;
            `legal_block` and `domain_not_allowed` refuse a source withheld by
            law or outside the key's domain policy.
          examples:
            - whole
            - sections_only
            - matching_sections
            - unchanged
            - pages_failed
            - cost_capped
            - budget_capped
            - time_capped
            - canceled
            - dns_error
            - dns_timeout
            - connection_refused
            - connection_timeout
            - connection_terminated
            - tls_protocol_error
            - tls_certificate_error
            - http_response_timeout
            - http_response_incomplete
            - not_found
            - access_denied
            - payment_required
            - rate_limited
            - server_error
            - http_error
            - challenge_served
            - blocked
            - region_restricted
            - deadline
            - empty
            - corrupt_document
            - no_history
            - too_large
            - destination_refused
            - domain_not_allowed
            - unsupported_media_type
            - password_protected
            - robots_disallowed
            - robots_unreachable
            - legal_block
            - sign_in_needed
            - paywalled
            - candidates
            - none
            - corrected_question
            - sources_missing
            - rerank_missing
            - fetches_missing
            - not_accepted_by_source
            - source_unreachable
            - login_expired
            - fee_through_form
        message:
          type: string
          description: >-
            One sentence with the particulars a reason has, the limit that
            stopped the work, the protocol that asked a price, the operation to
            use instead, and on a reason that has retry guidance, that
            guidance's sentence. Present when the reason has any.
    Notice:
      type: object
      description: >-
        A fact to read before the result, never an error: something was cut,
        left out, replaced or found that changes how you read what follows.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            What the notice tells you; an open set whose published values are
            below. A notice kept with the record is a fact of the record and
            comes back first on every answer about it, with `held` true; the
            others belong to this answer alone.


            | Code | Made by | Means |

            |---|---|---|

            | `highlight_not_found` | the fetch, the upload, the batch,
            `highlight_contents` | one of your `highlights` strings was not
            found and nothing bears on it, or `deterministic_only` kept the
            judging step out; one notice per string, `pointer` naming it, as
            `/highlights/2`; kept when the fetch made it |

            | `highlights_cut` | the same | more than 50 occurrences were found;
            the first 50 in document order came; kept |

            | `sections_cut` | the fetch, the upload, the batch, `get_contents`,
            `get_section` | levels of the map were left out; `get_section` lists
            them |

            | `links_cut` | the same | the link index was cut at 1,000, or in a
            batch by `max_total_characters`; `list_links` has the rest |

            | `total_characters_cut` | the batch, the search's inline fetch |
            this record came as `sections_only` because the whole answer's text
            bound was reached; `get_contents` returns its text free unless
            `retention` is `none` |

            | `hidden_text_cut` | the fetch, the upload, the batch | a hidden
            text item was cut at 1,000 characters, or the list at 50 items; kept
            |

            | `structured_data_cut` | the same | the page's structured data
            passed 64 KB; kept |

            | `block_over_limit` | `list_blocks` | one block larger than
            `max_characters` came whole, alone on its page |

            | `page_size_lowered` | every paged answer | `page_size` was above
            the maximum and was lowered, never refused |

            | `size_limit` | the fetch, the upload, the batch | the page or
            document passed the largest size taken whole, so the outcome is
            `too_large`; kept |

            | `conversion_mismatch` | the same | getclean's own check of the
            text against the page did not pass, so read the content with care;
            the message carries the two overlap figures it compared; kept |

            | `ad_blocker_failed` | the fetch, the batch | the advertising
            filter did not run on this read, so advertising may stand among the
            content; kept |

            | `not_settled` | the fetch, the batch | the page was still changing
            when `wait_seconds` ran out and was measured as it stood; kept |

            | `unread_region` | the fetch, the upload, the batch | a region that
            cannot be read as text covers part of the main content; the message
            names its kind and size; kept |

            | `no_main_content` | the same | no main content was found, so the
            whole page came under `scope: whole_page`; kept |

            | `paywall_declared` | the fetch, the batch, an uploaded HTML file;
            repeated by `compare_contents` | the page declares its content not
            free, so what came may be a teaser; kept |

            | `redirected` | the fetch, the upload by `url`, the batch | the
            final URL differs from the one asked beyond the scheme, the host's
            case, a trailing slash and tracking parameters; kept |

            | `requests_blocked` | the fetch, the batch | the page's own
            requests to addresses that are not globally reachable were blocked
            and the page went on; the count in the message; kept |

            | `field_not_applicable` | the fetches, the reads of a record, the
            model steps, the search | a field did not apply to this work and was
            left out; `field` names it |

            | `cost_cut` | the fetch, the upload, the batch,
            `highlight_contents` | an extra was cut by `max_cost`, the key's cap
            or the balance; the message says which, `field` names the extra;
            kept on a record |

            | `budget_cut` | the same | an extra was cut by the run's or the
            key's budget; the message says which; kept on a record |

            | `time_cut` | the fetch, the upload, the batch | a model step or
            the screenshot was cut by `wait_seconds` and not billed; kept |

            | `step_failed` | the fetch, the upload, the batch,
            `highlight_contents` | a model step or the screenshot failed or
            passed its bound and was not billed; kept |

            | `model_link_removed` | the fetch, the upload, the batch,
            `fill_schema`, `summarize_contents` | a link or an image a model
            wrote was removed from `summary` or `schema_values`; kept |

            | `recognition_uncertain` | the fetch, the upload, the batch | pages
            were recognized below the published confidence bar; the message
            names them; kept |

            | `tracked_changes` | the same | the document carries tracked
            changes, shown as accepted; the count in the message; kept |

            | `upload_to_finish` | the fetch, the batch | a document at a URL
            was cut by time; `upload_contents` with the `url` parses it whole as
            a job; kept |

            | `fingerprint_incomparable` | the fetch, the upload, the batch,
            `compare_contents` | the fingerprint came from another `scope`,
            version, configuration or kind of source, so the fetch ran whole; on
            a comparison, the kind of source or the configuration differs and
            the comparison ran; kept on a fetch's or a batch's record |

            | `fingerprint_unknown` | the fetch, the upload, the batch | the
            `baseline_fingerprint` matches no record this account keeps, so the
            fetch ran whole at the full price; kept |

            | `marks_not_read` | the same | the document carries no structure
            for its formatting, so bold, italics and strikethroughs could not be
            read; kept |

            | `content_not_rendered` | the same | a page holds handwriting, a
            drawing, a formula without structure or a blacked-out region, which
            came flattened or not at all; a published code this version does not
            make, such content coming with no notice and `pages.pictured`
            staying `[]` |

            | `archive_unreachable` | the fetch, the batch | an archive did not
            answer the as-of lookup, so `archives_consulted` lacks it; kept |

            | `default_set_by_policy` | the fetch, the upload, the batch,
            `highlight_contents`, the search | a default was replaced by the
            key's policy, as `deterministic_only` under a policy that forbids
            model work; kept on a record and on a search |

            | `version_retiring` | every answer with notices, except a job, the
            job list and the catalog | the answer was made under a version
            within `bounds.contents.version_notice_days` of its retirement |

            | `characters_removed` | the MCP server only | invisible characters,
            markup comments or hidden words were removed from the text, so the
            cleaned text no longer hashes to `fingerprint` |

            | `query_corrected` | the search, the search batch | a corrected
            wording ran beside or instead of yours; `interpretation.wordings`
            shows it; kept |

            | `filter_emulated` | the same | a source without a filter had it
            applied afterwards by getclean; the message says how; kept |

            | `window_after_as_of_date` | the same | `published_from` begins
            after `as_of_date`, so no page can match; kept |

            | `fetch_not_finished` | the same | an inline fetch was not started
            by the deadline, or its URL is one the key's policy refuses, so its
            candidate carries no record; kept |
          examples:
            - highlight_not_found
            - highlights_cut
            - sections_cut
            - links_cut
            - total_characters_cut
            - hidden_text_cut
            - structured_data_cut
            - block_over_limit
            - page_size_lowered
            - size_limit
            - conversion_mismatch
            - ad_blocker_failed
            - not_settled
            - unread_region
            - no_main_content
            - paywall_declared
            - redirected
            - requests_blocked
            - field_not_applicable
            - cost_cut
            - budget_cut
            - time_cut
            - step_failed
            - model_link_removed
            - recognition_uncertain
            - tracked_changes
            - upload_to_finish
            - fingerprint_incomparable
            - fingerprint_unknown
            - marks_not_read
            - content_not_rendered
            - archive_unreachable
            - default_set_by_policy
            - version_retiring
            - characters_removed
            - query_corrected
            - filter_emulated
            - window_after_as_of_date
            - fetch_not_finished
        message:
          type: string
          description: >-
            One sentence with the particulars: what was cut, by which limit, how
            much, or where.
        field:
          type: string
          description: The request field the notice is about. Present when there is one.
        pointer:
          type: string
          format: json-pointer
          description: >-
            A JSON Pointer into the request the notice answers: the fetch's
            request for a notice kept with the record, this call's for its own.
            Present when there is one.
          examples:
            - /highlights/1
        datasource_id:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: The source the notice is about. Present on a search only.
          examples:
            - web
        held:
          type: boolean
          description: >-
            True on a notice kept with the record, a fact of the work that comes
            back on every later answer about it. On the fetch's own answer every
            notice is that answer's own, so none carries it; absent on a notice
            that belongs to this answer alone.
    Scope:
      type: string
      description: >-
        Which view of a page is meant: `main`, the main content alone, or
        `whole_page`, everything on the page. A closed set.
      enum:
        - main
        - whole_page
    Block:
      type: object
      description: >-
        One unit of the content: a paragraph, a heading, a table, an image, a
        code listing and so on. `text` is present on `text`, `heading`, `code`,
        `math`, `divider` and `interactive` blocks; a divider's text is its
        markdown `---`, a math block's the formula as TeX without delimiters.
        The object `table`, `image`, `embed` or `media` is present on a block of
        that kind, never both. A list is one `text` block whose text is the list
        as markdown, one item per line with its marker or number, nesting by
        indentation; an object inside an item starts a new block.
      required:
        - id
        - kind
        - section_id
        - characters
        - links
        - highlight_ids
      properties:
        id:
          type: string
          pattern: ^b[0-9]+$
          description: The block's id, unique inside one record and one view.
          examples:
            - b7
        kind:
          type: string
          description: >-
            What kind of block it is: `text`, `heading`, `code`, `math`,
            `divider`, `interactive`, `table`, `image`, `embed` or `media`, an
            open set.
          examples:
            - text
            - heading
            - code
            - math
            - divider
            - interactive
            - table
            - image
            - embed
            - media
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: The section the block stands in.
          examples:
            - s2
        page_number:
          type: integer
          minimum: 1
          description: >-
            The page the block stands on, counted from 1 as the pages are. On a
            document with pages only.
        page_label:
          type: string
          x-third-party: true
          description: >-
            The page's own printed label, such as iv or A-3. On a document with
            pages, where the document declares one. Third-party text as the
            source wrote it, which may carry instructions.
        characters:
          type: integer
          minimum: 0
          description: >-
            The block's text in characters; a merged table cell's text counted
            once.
        text:
          type: string
          x-third-party: true
          description: >-
            The block's text, with its inline formatting as markdown. Present on
            `text`, `heading`, `code`, `math`, `divider` and `interactive`
            blocks. Third-party text as the source wrote it, which may carry
            instructions.
        code_language:
          type: string
          description: >-
            The programming language of a `code` block. Present where the source
            states it.
          examples:
            - python
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How sure the recognition was of this block, the lowest word
            confidence in it, 0 to 1. Present on text recognized from an image.
        note_for:
          type: array
          description: >-
            For a footnote block, the ids of the blocks that cite it. Present
            where the document links them.
          items:
            type: string
            pattern: ^b[0-9]+$
            examples:
              - b3
        links:
          type: array
          description: >-
            The links inside the block; `[]` when there is none. Each comes
            without `block_id` and `section_id`, since this block gives them.
          items:
            $ref: '#/components/schemas/Link'
        highlight_ids:
          type: array
          description: >-
            The ids of the highlights found in this block; `[]` when there is
            none.
          items:
            type: string
            pattern: ^h[0-9]+$
        table:
          $ref: '#/components/schemas/Table'
          description: The table, cell by cell. Present on a `table` block.
        image:
          $ref: '#/components/schemas/Image'
          description: >-
            The image's address, digest, caption and size. Present on an `image`
            block.
        embed:
          $ref: '#/components/schemas/Embed'
          description: The address of the embedded frame. Present on an `embed` block.
        media:
          $ref: '#/components/schemas/Media'
          description: The address of the audio or video file. Present on a `media` block.
    Link:
      type: object
      description: One link in the content, with its kind and where it stands.
      required:
        - url
        - text
        - kind
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The address, absolute. Third-party text as the source wrote it,
            which may carry instructions.
          examples:
            - https://example.com/q3
        text:
          type: string
          x-third-party: true
          description: >-
            The link's text; an empty string when it has none. Third-party text
            as the source wrote it, which may carry instructions.
        kind:
          type: string
          description: >-
            What the link points to, read from its address alone, so a guess:
            `page`, another page; `file`, a file such as a PDF; `fragment`, a
            place on this page; `mail`, an email address; `phone`, a phone
            number; `feed`, an RSS or Atom feed; `other`, anything else. An open
            set. No request is made per link, so a link carries no size or
            served type.
          examples:
            - page
            - file
            - fragment
            - mail
            - phone
            - feed
            - other
        external:
          type: boolean
          description: >-
            True when the link leaves the site, judged against the final URL's
            registrable domain. Absent on kinds without a host.
        target_block_id:
          type: string
          pattern: ^b[0-9]+$
          description: >-
            The block a `fragment` link points to. Present when it resolves
            inside the record.
          examples:
            - b7
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: >-
            The block that holds the link. Present everywhere but inside
            `Block.links`, where the block itself says it.
          examples:
            - b7
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section that holds the link. Present everywhere but inside
            `Block.links`.
          examples:
            - s2
    Screenshot:
      type: object
      description: A picture of the whole page at the width it was read at, as PNG.
      required:
        - digest
        - width_px
        - height_px
      properties:
        url:
          type: string
          format: uri
          description: >-
            Where to get the picture, a URL getclean serves for as long as the
            record lives, under `retention` `hold`.
        data_base64:
          type: string
          contentEncoding: base64
          contentMediaType: image/png
          description: >-
            The PNG bytes in base64, under `retention` `none`, where nothing is
            stored to serve; at most `bounds.contents.screenshot_bytes`.
        digest:
          type: string
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: >-
            The sha-256 of the PNG bytes in RFC 9530 form, so the picture can be
            proved unchanged.
          examples:
            - 'sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:'
        width_px:
          type: integer
          minimum: 0
          description: The width in pixels.
        height_px:
          type: integer
          minimum: 0
          description: The height in pixels.
    Section:
      type: object
      description: >-
        One row of the map: a heading and everything under it, down to the next
        heading of the same or a higher level.
      required:
        - id
        - title
        - level
        - characters
        - basis
      properties:
        id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section's id, unique inside one record and one view. `s0` is the
            text before the first heading; on a page without headings it is the
            whole document.
          examples:
            - s2
        title:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The heading's text; null when the section has no heading.
            Third-party text as the source wrote it, which may carry
            instructions.
        level:
          type: integer
          minimum: 0
          description: >-
            The heading's level: 0 for the text before the first heading, 1 for
            a top heading, and so on down.
        characters:
          type: integer
          minimum: 0
          description: >-
            The size of the section's text in characters, everything under it
            included.
        basis:
          type: string
          description: >-
            Where the section's boundary comes from, an open set: `structure`,
            the page's headings or the document's own structure; `outline`, the
            document's outline, for a PDF without structure; `page`, one row per
            page, for a scan or a document with neither.
          examples:
            - structure
            - outline
            - page
        first_page_number:
          type: integer
          minimum: 1
          description: The first page the section stands on. On a document with pages only.
        last_page_number:
          type: integer
          minimum: 1
          description: The last page the section stands on. On a document with pages only.
        language:
          type: string
          description: >-
            The section's language, a BCP 47 tag. Present only where it differs
            from `source.language`.
          examples:
            - de
    ContentsCounts:
      type: object
      description: >-
        How much a record holds under one view: characters, blocks by kind and
        links by kind.
      required:
        - characters
        - blocks
        - links
      properties:
        characters:
          type: integer
          minimum: 0
          description: The content's text in characters.
        blocks:
          type: object
          description: >-
            How many blocks of each kind, keyed by kind: `text`, `heading`,
            `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`,
            `media`, an open set. `{}` when there is none.
          additionalProperties:
            type: integer
            minimum: 0
        links:
          type: object
          description: >-
            How many links of each kind, keyed by kind: `page`, `file`,
            `fragment`, `mail`, `phone`, `feed`, `other`, an open set. `{}` when
            there is none.
          additionalProperties:
            type: integer
            minimum: 0
    Highlight:
      type: object
      description: >-
        One place in the content where one of your `highlights` strings was
        found: a sentence, a table row, a heading, a whole block or a part of
        one, with where it stands and how it was found.
      required:
        - id
        - query_index
        - text
        - basis
        - section_id
        - block_id
      properties:
        id:
          type: string
          pattern: ^h[0-9]+$
          description: >-
            The highlight's id, unique inside the answer that made it; the same
            id stands in the text's marks and in each block's `highlight_ids`.
          examples:
            - h1
        query_index:
          type: integer
          minimum: 0
          description: >-
            Which of your strings found it: its position in the request's
            `highlights`, from 0.
        text:
          type: string
          x-third-party: true
          description: >-
            The words as they stand in the content. Third-party text as the
            source wrote it, which may carry instructions.
        basis:
          type: string
          description: >-
            How it was found, an open set: `exact`, your words stand in one
            block as written, case kept; `near`, they stand there once case and
            the punctuation at the ends of words are ignored; `judged`, a model
            picked the block that bears on your string. `exact` and `near`
            repeat on every run and are free; `judged` costs one model step.
          examples:
            - exact
            - near
            - judged
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: The section it stands in.
          examples:
            - s2
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: The block it stands in.
          examples:
            - b7
        page_number:
          type: integer
          minimum: 1
          description: The page it stands on. On a document with pages only.
        page_label:
          type: string
          x-third-party: true
          description: >-
            The page's own printed label. On a document with pages, where the
            document declares one. Third-party text as the source wrote it,
            which may carry instructions.
        row:
          type: integer
          minimum: 0
          description: The row, from 0, when it stands inside a table.
        column:
          type: integer
          minimum: 0
          description: The column, from 0, when it stands inside a table.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How sure the recognition was of the block it stands in. Present on
            text recognized from an image.
    SchemaStatus:
      type: object
      description: >-
        How one property of your schema was filled, and where its value came
        from.
      required:
        - status
      properties:
        status:
          type: string
          description: >-
            How the property was filled: `found`, the content states the value;
            `empty`, the content shows the field with no value; `absent`, the
            content kept under the record's view says nothing about it;
            `unread`, the place it would stand may lie in pages not parsed, not
            recognized, recognized below the published confidence or past a cap,
            so its absence cannot be claimed; `failed`, the model could not fill
            it. An open set.
          examples:
            - found
            - empty
            - absent
            - unread
            - failed
        text:
          type: string
          x-third-party: true
          description: >-
            The words the value came from. Present on `found` and `empty`.
            Third-party text as the source wrote it, which may carry
            instructions.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How sure the recognition was of those words. Present when they were
            recognized from an image.
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section the words stand in. Present on `found` and `empty`, and
            on `unread` when the place is known.
          examples:
            - s2
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: The block the words stand in. Present as `section_id` is.
          examples:
            - b7
        page_number:
          type: integer
          minimum: 1
          description: >-
            The page the words stand on. Present as `section_id` is, on a
            document with pages.
        page_label:
          type: string
          x-third-party: true
          description: >-
            The page's own printed label. Present as `page_number` is, where the
            document declares one. Third-party text as the source wrote it,
            which may carry instructions.
        row:
          type: integer
          minimum: 0
          description: The row, from 0, when the words stand inside a table.
        column:
          type: integer
          minimum: 0
          description: The column, from 0, when the words stand inside a table.
    HiddenText:
      type: object
      description: >-
        Text on the page that a reader could not see, kept apart from the
        content with the reason it was hidden. What a reader cannot see is never
        counted as content, and an agent reads it knowing what it is.
      required:
        - text
        - characters
        - reason
      properties:
        text:
          type: string
          x-third-party: true
          maxLength: 1000
          description: >-
            The hidden words, at most 1,000 characters, cut with the notice
            `hidden_text_cut`; the MCP server sends this empty. Third-party text
            as the source wrote it, which may carry instructions.
        characters:
          type: integer
          minimum: 0
          description: The hidden text's whole size in characters, before any cut.
        reason:
          type: string
          description: >-
            How it was hidden, an open set: `styled_hidden`, hidden by its
            style; `same_color`, written in the color of its background; `tiny`,
            too small to read; `covered`, under another element.
          examples:
            - styled_hidden
            - same_color
            - tiny
            - covered
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section the hidden text stands in, by the nearest visible part
            around it. Absent when there is none.
          examples:
            - s2
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: >-
            The block the hidden text stands in, found as `section_id` is.
            Absent when there is none.
          examples:
            - b7
    LeftOut:
      type: object
      description: One part of the page outside the main content, with its kind and size.
      required:
        - kind
        - characters
      properties:
        kind:
          type: string
          description: >-
            What the part is, an open set: `header`, `footer`, `navigation`,
            `table_of_contents`, `forms`, `widgets`, `rails`, the side columns,
            `comments`, `advertising`.
          examples:
            - header
            - footer
            - navigation
            - table_of_contents
            - forms
            - widgets
            - rails
            - comments
            - advertising
        characters:
          type: integer
          minimum: 0
          description: Its size in characters.
    Source:
      type: object
      description: >-
        The facts of the source and of the read. `title`, `authors`,
        `published_date`, `published_at`, `modified_date`, `publisher`,
        `canonical_url`, `language`, `language_versions`, `structured_data` and
        `declared_terms` are what the page or the document declares about
        itself; getclean reports them and does not check them against the
        content. The table under `Contents` says which of these members each
        kind of source carries.
      required:
        - redirects
        - media_type
        - carrier
        - title
        - authors
        - published_date
        - modified_date
        - language
        - language_versions
        - robots
        - declared_terms
        - structured_data
        - origins
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The address that was asked for; on an upload, the `captured_url`
            given. Absent on an upload sent without `captured_url`. On a record
            a search made, third-party text as the source wrote it, which may
            carry instructions.
          examples:
            - https://example.com/q3
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the fetch ended at, after every redirect. Absent on an
            upload. Third-party text as the source wrote it, which may carry
            instructions.
          examples:
            - https://example.com/q3
        redirects:
          type: array
          description: >-
            Every redirect on the way, script and meta-refresh hops included;
            `[]` when there was none.
          items:
            $ref: '#/components/schemas/Redirect'
        status_code:
          type: integer
          description: >-
            The HTTP status of the final response. Absent when no response came,
            and on an upload.
        media_type:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The `Content-Type` the server sent or, for an upload, the type read
            from the bytes; null when no response or no type came. Third-party
            text as the source wrote it, which may carry instructions.
        carrier:
          type: string
          description: >-
            The kind of source, an open set: `web`, a live page; `archive`, an
            archive's copy read under `as_of_date`; `upload`, bytes you sent.
          examples:
            - web
            - archive
            - upload
        archive:
          $ref: '#/components/schemas/Archive'
          description: >-
            The archive copy that was read, with the archive's name, the
            capture's time and its address. On an archive copy only.
        archives_consulted:
          type: array
          description: >-
            The archives of `Limits.archives` that answered the lookup, by name.
            On every fetch under `as_of_date`; one that did not answer is named
            by the notice `archive_unreachable`.
          items:
            type: string
        next_capture_at:
          type: string
          format: date-time
          description: >-
            When the next capture after this one was taken, so an agent can step
            forward capture by capture. On a fetch under `as_of_date`, when a
            later capture exists.
        filename:
          type: string
          description: The file's name as it was sent. On an upload only.
        document_digest:
          type: string
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: >-
            The sha-256 of the document's bytes in RFC 9530 form. Compare it
            with the file you hold to be sure the right document was parsed. On
            a document only.
          examples:
            - 'sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:'
        title:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The title as the source declares it; null when none came.
            Third-party text as the source wrote it, which may carry
            instructions.
        authors:
          type: array
          x-third-party: true
          description: >-
            The authors as the source declares them; `[]` when none. Third-party
            text as the source wrote it, which may carry instructions.
          items:
            type: string
        publisher:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The publisher as the page declares it; null when not declared.
            Absent on an upload. Third-party text as the source wrote it, which
            may carry instructions.
        canonical_url:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The address the publisher names as the original, as declared; null
            when not declared. Absent on an upload. Third-party text as the
            source wrote it, which may carry instructions.
        published_date:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The date of publication as the source declares it, a full date; null
            when none. A document's own dates often record when the file was
            made.
        published_date_precision:
          $ref: '#/components/schemas/DatePrecision'
          description: >-
            How exact `published_date` is, `day`, `month` or `year`. Absent when
            the date is null.
        published_date_basis:
          type: string
          description: >-
            Where the date was read, an open set: `structured_data`, `meta_tag`,
            `byline`, `url` or `document_properties`. Absent when the date is
            null.
          examples:
            - structured_data
            - meta_tag
            - byline
            - url
            - document_properties
        published_at:
          type: string
          format: date-time
          description: >-
            The moment of publication in UTC. Present when the page states a
            time with its zone.
        modified_date:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The date of the last change as the source declares it, a full date;
            null when none.
        language:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The language the page declares, as a BCP 47 tag; null when none
            came. Third-party text as the source wrote it, which may carry
            instructions.
        language_versions:
          type: array
          description: >-
            The page's own versions in other languages, as it declares them;
            `[]` when it declares none.
          items:
            $ref: '#/components/schemas/LanguageVersion'
        profile:
          $ref: '#/components/schemas/SourceProfile'
          description: >-
            Who publishes the source, as getclean identifies it. On a web page,
            an archive copy or a document at a URL; absent on an upload.
        access_kind:
          type: string
          description: >-
            The access the fetch ran under, an open set: `open`, no login;
            `registered`, a login registered for a datasource. Absent on an
            upload.
          examples:
            - open
            - registered
        datasource_id:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: >-
            The datasource whose registered login served the fetch. Present when
            `access_kind` is `registered`.
          examples:
            - web
        captured_at:
          type: string
          format: date-time
          description: >-
            When you took the capture, as you stated it. On an upload sent with
            `captured_at` only.
        robots:
          type: string
          description: >-
            What the site's robots file says for getclean by its published name,
            an open set: `allowed`, `disallowed`, `absent`, `unreachable`;
            `not_applicable` on an upload.
          examples:
            - allowed
            - disallowed
            - absent
            - unreachable
            - not_applicable
        declared_terms:
          type: array
          description: >-
            The terms the source declares about its use, each as found and as
            read, reported and never judged; `[]` when none.
          items:
            $ref: '#/components/schemas/DeclaredTerm'
        structured_data:
          type: array
          x-third-party: true
          description: >-
            The page's own structured data, its JSON-LD objects as stated, at
            most 64 KB together, cut with the notice `structured_data_cut`; `[]`
            when none. Third-party text as the source wrote it, which may carry
            instructions.
          items:
            type: object
        origins:
          type: array
          description: >-
            The other sites the page reached while it was read, each once, with
            how; `[]` when none.
          items:
            $ref: '#/components/schemas/Origin'
        blocked_by:
          type: string
          x-third-party: true
          description: >-
            The notice page the site named in its `Link rel="blocked-by"`
            header. On a `legal_block` record only. Third-party text as the
            source wrote it, which may carry instructions.
          examples:
            - https://example.com/legal/notice
        visitor:
          $ref: '#/components/schemas/Visitor'
          description: >-
            From where the site was read: the country, the language asked for
            and the kind of network. Absent on an archive copy or an upload.
    DocumentPages:
      type: object
      description: >-
        The pages of a document: how many there are, how many were parsed, which
        failed, which were read from an image. The pages not yet parsed are
        `count` less `parsed_count` less the failed pages.
      required:
        - count
        - parsed_count
        - failed_pages
        - recognized
        - pictured
      properties:
        count:
          type: integer
          minimum: 0
          description: >-
            How many pages the document has. On a format without pages, a
            spreadsheet or a plain text file, the equivalent by characters,
            `bounds.contents.document_page_characters` characters of text
            counting as one page, rounded up. The bill counts `parsed_count`.
        parsed_count:
          type: integer
          minimum: 0
          description: How many pages were parsed; the bill counts these.
        failed_pages:
          type: array
          description: The pages that could not be parsed, by number; `[]` when none.
          items:
            type: integer
            minimum: 1
        recognized:
          type: array
          description: >-
            The pages that had no text layer and were read from their image;
            `[]` when none.
          items:
            $ref: '#/components/schemas/RecognizedPage'
        pictured:
          type: array
          description: >-
            The pages that hold content the text cannot carry, handwriting, a
            drawing, a formula or a blacked-out region; `[]` in this version,
            which does not detect them.
          items:
            $ref: '#/components/schemas/PicturedPage'
    Execution:
      type: object
      description: >-
        How the answer was made: the version, its configuration, the model steps
        that ran and the time it took.
      required:
        - version
        - configuration
        - models
        - elapsed_seconds
      properties:
        version:
          type: string
          description: >-
            getclean's version, the value `pinned_version` pins and
            `Limits.current_version` names.
          examples:
            - 1.0.0
        configuration:
          type: string
          description: >-
            The read configuration as one published string, fixed with the
            version by `pinned_version`. Under one version and one configuration
            the same page, or the same bytes, give the same text and the same
            ids.
          examples:
            - cfg-2026-11
        models:
          type: array
          description: >-
            Every model step, and every versioned recognition step, that ran in
            making this answer, each with its version; `[]` when none ran.
          items:
            $ref: '#/components/schemas/ModelStep'
        elapsed_seconds:
          type: number
          minimum: 0
          description: The seconds the work took.
        time_stamp:
          $ref: '#/components/schemas/TimeStamp'
          description: >-
            A trusted time over the record's fingerprint and the screenshot's
            digest. Not sent in this version.
    Cost:
      type: object
      description: >-
        The money of one call, or of one part of it. `actual` is what you paid,
        `ceiling` the most this call could have cost, `units` what was counted.
        On an answer that sums parts, a search with inline fetches or a batch,
        `source_price` is the sum of the prices every part was asked, and
        whether each was paid is read from that part's own `cost` and outcome.
      required:
        - actual
        - units
        - replayed
      properties:
        ceiling:
          $ref: '#/components/schemas/Money'
          description: >-
            The ceiling applied: the lowest of the request's `max_cost`, the
            key's cap, the run's budget, the key's budget and the balance; on an
            operation that takes no `max_cost`, the step's price. Present on
            every call that can bill.
        actual:
          $ref: '#/components/schemas/Money'
          description: What was billed, a source's price included.
        units:
          type: object
          description: >-
            How many of each unit were billed, keyed by unit name: `contents`,
            `model_steps`, `screenshots`, `document_pages`, `recognized_pages`,
            `searches` and `datasource_queries`, an open set. `{}` when nothing
            was billed.
          additionalProperties:
            type: integer
            minimum: 0
        source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The price a site or a source asked for this work. getclean pays no
            site for a page, so a page that asked a price ends
            `payment_required`, with the price here. Present whenever a price
            was asked.
        run_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: >-
            What is left of the run's budget after this call. Present when the
            run has a budget.
        key_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: >-
            What is left of the key's budget after this call. Present when the
            key has a budget.
        replayed:
          type: boolean
          description: >-
            True when this answer is the first answer returned again under the
            same idempotency key; nothing was billed again.
    RawHtml:
      type: object
      description: >-
        The page's bytes exactly as the server sent them, decompressed, before
        any script ran; on an archive copy, as the archive served them. The
        served bytes and their digest let you show later exactly what the server
        sent.
      required:
        - digest
        - bytes
        - media_type
      properties:
        url:
          type: string
          format: uri
          description: >-
            Where to get the bytes, a URL getclean serves for as long as the
            record lives, under `retention` `hold`.
        data_base64:
          type: string
          contentEncoding: base64
          x-third-party: true
          description: >-
            The bytes in base64, under `retention` `none`, where nothing is
            stored to serve; at most `bounds.contents.page_bytes`. Never altered
            by any client, since the digest covers the bytes as served.
            Third-party text as the source wrote it, which may carry
            instructions.
        digest:
          type: string
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: The sha-256 of the bytes in RFC 9530 form.
          examples:
            - 'sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:'
        bytes:
          type: integer
          minimum: 0
          description: How many bytes.
        media_type:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The `Content-Type` the server sent; null when none came. Third-party
            text as the source wrote it, which may carry instructions.
    JobCounts:
      type: object
      description: >-
        The pages of a job; the three add up to `pages.count`, on which a format
        without pages counts `bounds.contents.document_page_characters`
        characters as one page.
      required:
        - parsed_count
        - failed_count
        - remaining_count
      properties:
        parsed_count:
          type: integer
          minimum: 0
          description: Pages parsed without failure; the bill counts these.
        failed_count:
          type: integer
          minimum: 0
          description: Pages that could not be parsed.
        remaining_count:
          type: integer
          minimum: 0
          description: Pages not yet parsed.
    ProblemChange:
      type: object
      description: The fix as data. Each member is present when it applies.
      properties:
        field:
          type: string
          description: >-
            The field to change: a field of the operation `operation` names when
            it is present, else of this request.
          examples:
            - page_token
        allowed_values:
          type: array
          description: The values the field may take.
          items:
            type: string
        bounds:
          $ref: '#/components/schemas/Bound'
          description: The range the field may take.
        operation:
          type: string
          description: >-
            The operation to call instead, by its id, one of this contract's 22
            operation ids, `fetch_contents` for one; an open set.
          examples:
            - fetch_contents
            - upload_contents
            - fetch_contents_batch
            - get_contents
            - get_section
            - list_blocks
            - list_links
            - highlight_contents
            - fill_schema
            - summarize_contents
            - compare_contents
            - get_job
            - cancel_job
            - list_jobs
            - get_limits
            - delete_contents
            - list_contents
            - search
            - get_search
            - search_batch
            - list_datasources
            - get_datasource
    Violation:
      type: object
      description: One fault of a request, with where it is.
      required:
        - kind
        - place
        - field
        - message
      properties:
        kind:
          type: string
          description: >-
            What kind of fault; an open set with these published values.
            `bound`, a length, count, range or size was passed; `not_allowed`, a
            value outside the published set; `dependent`, a field that needs
            another field; `exclusive`, two fields that exclude each other;
            `order`, two values in the wrong order; `duplicate`, a repeated
            value; `misplaced`, a known field at the wrong level of a batch;
            `unknown_field`, a field this operation does not take; `syntax`, a
            value of the wrong type or form; `required`, a required field
            missing.
          examples:
            - bound
            - not_allowed
            - dependent
            - exclusive
            - order
            - duplicate
            - misplaced
            - unknown_field
            - syntax
            - required
        place:
          type: string
          description: >-
            Where the fault is: `body`, `form`, `query`, `path` or `header`. A
            closed set.
          enum:
            - body
            - form
            - query
            - path
            - header
        pointer:
          type: string
          format: json-pointer
          description: A JSON Pointer to the value. Present when the place is `body`.
          examples:
            - /formats/0
        field:
          type: string
          description: >-
            The field, parameter or header name. A field inside a batch item is
            named by its own name, the item standing in `pointer`.
          examples:
            - formats
        message:
          type: string
          description: One sentence on what is wrong with the value.
        allowed_values:
          type: array
          description: The values the field may take. Present when they apply.
          items:
            type: string
        bounds:
          $ref: '#/components/schemas/Bound'
          description: The range the field may take. Present when it applies.
    Table:
      type: object
      description: >-
        A table as it is displayed, cell by cell, with its merged cells, its
        header rows and columns, and where its structure came from.
      required:
        - caption
        - rows
        - spans
        - header_rows
        - header_columns
        - basis
      properties:
        caption:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The table's caption; null when it has none. Third-party text as the
            source wrote it, which may carry instructions.
        rows:
          type: array
          x-third-party: true
          description: >-
            The rows, each a list of cells as displayed. A merged cell's text
            stands in every slot it covers, and an empty cell is the empty
            string, so every row has every column. Third-party text as the
            source wrote it, which may carry instructions.
          items:
            type: array
            items:
              type: string
        spans:
          type: array
          description: >-
            The merged cells, each with its position and how many rows and
            columns it covers; `[]` when no cell merges.
          items:
            $ref: '#/components/schemas/TableSpan'
        header_rows:
          type: array
          description: Which rows are headers, by index from 0; `[]` when none.
          items:
            type: integer
            minimum: 0
        header_columns:
          type: array
          description: Which columns are headers, by index from 0; `[]` when none.
          items:
            type: integer
            minimum: 0
        basis:
          type: string
          description: >-
            Where the table's structure came from, an open set: `structure`, the
            source carries it; `layout`, read from the page's layout. In this
            version the tables of a PDF without structure and of a scan come as
            text, so `layout` does not occur.
          examples:
            - structure
            - layout
        last_page_number:
          type: integer
          minimum: 1
          description: >-
            The last page the table continues onto. Present on a table that
            spans pages.
        top_left_cell:
          type: string
          pattern: ^[A-Z]{1,3}[1-9][0-9]*$
          description: >-
            The address of the top-left cell on the sheet, such as `B4`. On a
            spreadsheet only.
          examples:
            - B4
        formula_cells:
          type: array
          description: >-
            The cells that held a formula, so you know which values were
            computed. On a spreadsheet only, `[]` when none.
          items:
            $ref: '#/components/schemas/CellAddress'
        cell_confidences:
          type: array
          description: >-
            How sure the recognition was of each cell. Present on a table read
            from a scan; in this version no table is read from a scan, so it
            does not occur.
          items:
            $ref: '#/components/schemas/CellConfidence'
    Image:
      type: object
      description: An image in the content.
      required:
        - digest
        - alt
        - caption
        - width_px
        - height_px
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            Where to get the image: its own address as the page gives it, or a
            URL getclean serves for an image inside a document. Absent on a
            document's image under `retention` `none`. On a web image,
            third-party text as the source wrote it, which may carry
            instructions; on a document's image, getclean's own URL.
          examples:
            - https://example.com/q3/chart.png
        digest:
          type:
            - string
            - 'null'
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: >-
            The sha-256 of the image's bytes in RFC 9530 form, so two images can
            be told equal; null when the bytes were not loaded.
          examples:
            - 'sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:'
        alt:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The image's alternative text; null when it has none. Third-party
            text as the source wrote it, which may carry instructions.
        caption:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The caption the source ties to the image; null when there is none.
            Third-party text as the source wrote it, which may carry
            instructions.
        width_px:
          type: integer
          minimum: 0
          description: >-
            The width as the page shows it, in CSS pixels, rounded; the image's
            own pixel width in a document.
        height_px:
          type: integer
          minimum: 0
          description: The height, measured as `width_px` is.
    Embed:
      type: object
      description: A frame from another site, embedded in the page.
      required:
        - url
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The frame's address. Third-party text as the source wrote it, which
            may carry instructions.
          examples:
            - https://example.com/q3
    Media:
      type: object
      description: An audio or video file in the content.
      required:
        - url
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The media file's address. Third-party text as the source wrote it,
            which may carry instructions.
          examples:
            - https://example.com/q3
    Redirect:
      type: object
      description: One redirect on the way to the final address.
      required:
        - url
        - status_code
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The address this hop led to. Third-party text as the source wrote
            it, which may carry instructions.
          examples:
            - https://example.com/q3
        status_code:
          type:
            - integer
            - 'null'
          description: >-
            The HTTP status that made the hop; null on a script or meta-refresh
            hop.
    Archive:
      type: object
      description: The archive copy a fetch under `as_of_date` read.
      required:
        - display_name
        - captured_at
        - url
      properties:
        display_name:
          type: string
          description: The archive's name, as `Limits.archives` lists it.
          examples:
            - Wayback Machine
        captured_at:
          type: string
          format: date-time
          description: When the archive took the capture, RFC 3339 in UTC.
        url:
          type: string
          x-third-party: true
          description: >-
            The capture's address at the archive. Third-party text as the source
            wrote it, which may carry instructions.
          examples:
            - https://example.com/q3
    DatePrecision:
      type: string
      description: How exact a published date is; `day`, `month` or `year`. A closed set.
      enum:
        - day
        - month
        - year
    LanguageVersion:
      type: object
      description: One of the page's own language versions, as the page declares them.
      required:
        - url
        - language
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The version's address. Third-party text as the source wrote it,
            which may carry instructions.
          examples:
            - https://example.com/q3
        language:
          type: string
          description: The version's language, a BCP 47 tag.
          examples:
            - fr
        authoritative:
          type: boolean
          description: >-
            Whether this version binds. Present only when the page declares, in
            a form getclean reads, which versions bind: true on a binding
            version and false on the others, and true on every version where the
            source declares them equally authentic. Absent when nothing is
            declared.
    SourceProfile:
      type: object
      description: >-
        Who publishes the source, as getclean identifies it from the site's own
        declarations and from public registries: no score, no tier, no verdict.
        Identifying a publisher costs nothing extra; when getclean identifies
        one during the call, the step `source_profile` is listed in
        `execution.models`. Under `deterministic_only` only what is already
        known answers. A kind that cannot be read from the declarations is
        `unknown`, never a guess.
      required:
        - kind
        - role
        - independence
        - review
      properties:
        kind:
          type: string
          description: >-
            The kind of publisher; an open set with these published values, by
            sector. Public: `state`, `court`, `regulator`, `statistics_office`,
            `intergovernmental`, `standards_body`. Knowledge: `academic`,
            `scholarly_publisher`, `archive`, `reference`. Media: `press`,
            `information_provider`. Economy: `company`, `professional_practice`,
            `trade_body`, `marketplace`. Society: `civil_society`, `political`,
            `religious`, `education`, `healthcare`, `cultural`. Individual:
            `individual`, `community`. And `unknown`.
          examples:
            - state
            - court
            - regulator
            - statistics_office
            - intergovernmental
            - standards_body
            - academic
            - scholarly_publisher
            - archive
            - reference
            - press
            - information_provider
            - company
            - professional_practice
            - trade_body
            - marketplace
            - civil_society
            - political
            - religious
            - education
            - healthcare
            - cultural
            - individual
            - community
            - unknown
        role:
          type: string
          description: >-
            What the item is as a source: `primary`, `secondary` or `tertiary`
            in the usual sense of research, else `unknown`. Read from the item's
            declared type first, then from the publisher's kind. A closed set.
          enum:
            - primary
            - secondary
            - tertiary
            - unknown
        independence:
          type: string
          description: >-
            Whether the publisher is the subject speaking about itself, `self`,
            or independent of it, `independent`, known through the subject's
            identifiers; else `unknown`. A closed set.
          enum:
            - self
            - independent
            - unknown
        review:
          $ref: '#/components/schemas/Review'
          description: >-
            Who reviewed the publication, from the venue's stated process or a
            named validator.
    DeclaredTerm:
      type: object
      description: >-
        One term a source declares about how its content may be used, reported
        as found and as read, never judged against your purpose; whether a term
        binds you is your call.
      required:
        - signal
        - as_found
        - as_parsed
      properties:
        signal:
          type: string
          description: >-
            Where the term stands, an open set: `robots_txt`, `meta_robots`,
            `x_robots_tag`, `tdm_reservation_header`, `tdmrep_file`,
            `license_link`, `license_markup`.
          examples:
            - robots_txt
            - meta_robots
            - x_robots_tag
            - tdm_reservation_header
            - tdmrep_file
            - license_link
            - license_markup
        as_found:
          type: string
          x-third-party: true
          description: >-
            The term's text as found. Third-party text as the source wrote it,
            which may carry instructions.
        as_parsed:
          type: string
          description: >-
            What the term says, as getclean reads it: `reserved`, use is
            reserved; `not_reserved`, use is not reserved; `unknown`, the term
            could not be read; `not_applicable`, the signal carries no such
            term. A closed set.
          enum:
            - reserved
            - not_reserved
            - unknown
            - not_applicable
        url:
          type: string
          x-third-party: true
          description: >-
            The address the term points to, such as a licence page. Present when
            it points to one. Third-party text as the source wrote it, which may
            carry instructions.
          examples:
            - https://example.com/q3
    Origin:
      type: object
      description: One other site the page reached while it was read.
      required:
        - origin
        - kind
      properties:
        origin:
          type: string
          x-third-party: true
          description: >-
            The site, as scheme and host. Third-party text as the source wrote
            it, which may carry instructions.
          examples:
            - https://cdn.example.com
        kind:
          type: string
          description: >-
            How it was reached, an open set: `form_action`, a form posts to it;
            `script`, a script was loaded from it; `frame`, a frame came from
            it; `fetch`, the page fetched data from it; `other`.
          examples:
            - form_action
            - script
            - frame
            - fetch
            - other
    Visitor:
      type: object
      description: >-
        From where the site was read: the country, the language asked for and
        the kind of network.
      required:
        - country
        - language
        - network
      properties:
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: The country the site was read from, ISO 3166-1 alpha-2.
          examples:
            - DE
        language:
          type: string
          description: >-
            The language asked of the site, as the `Accept-Language` header
            sent.
          examples:
            - de-DE,de;q=0.9
        network:
          type: string
          description: >-
            The kind of network the site was read from, an open set:
            `datacenter`, `residential`, `mobile`.
          examples:
            - datacenter
            - residential
            - mobile
    RecognizedPage:
      type: object
      description: One page read from its image, since it had no text layer.
      required:
        - page_number
        - confidence
      properties:
        page_number:
          type: integer
          minimum: 1
          description: The page, counted from 1.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: How sure the recognition was of the page as a whole, 0 to 1.
        image_url:
          type: string
          format: uri
          description: >-
            A picture of the page, at a URL getclean serves for as long as the
            record lives, so you can check the reading against the image. Absent
            under `retention` `none`.
    PicturedPage:
      type: object
      description: One page that holds content the text cannot carry, with a picture of it.
      required:
        - page_number
        - kind
      properties:
        page_number:
          type: integer
          minimum: 1
          description: The page, counted from 1.
        kind:
          type: string
          description: >-
            What the page holds, an open set: `handwriting`, `drawing`,
            `formula`, `redaction`.
          examples:
            - handwriting
            - drawing
            - formula
            - redaction
        image_url:
          type: string
          format: uri
          description: >-
            A picture of the page, at a URL getclean serves for as long as the
            record lives. Absent under `retention` `none`.
    ModelStep:
      type: object
      description: One step a model, or a versioned recognizer, took in making the answer.
      required:
        - step
        - version
      properties:
        step:
          type: string
          description: >-
            Which step ran: `highlights`, the judged highlights; `json_schema`,
            the schema fill; `summary`, the summary; `recognition`, text read
            from a page with no text layer; `language_detection`, the languages
            chosen for that reading; `reranking`, the search's ranking;
            `discovery`, the search's choice of sources; `source_profile`, a
            publisher identified during the call. An open set.
          examples:
            - highlights
            - json_schema
            - summary
            - recognition
            - language_detection
            - reranking
            - discovery
            - source_profile
        version:
          type: string
          description: The step's version, so a result can be placed and compared.
          examples:
            - hl-2026-10
    TimeStamp:
      type: object
      description: >-
        Proof that the record existed at a moment: an RFC 3161 time-stamp token
        over one datum, the sha-256 of the record's fingerprint followed by the
        screenshot's digest, or of the fingerprint alone when no screenshot was
        made.
      required:
        - token
        - authority
      properties:
        token:
          type: string
          contentEncoding: base64
          description: The token, in base64.
        authority:
          type: string
          description: The name of the time-stamping authority that issued it.
    Bound:
      type: object
      description: >-
        The range a field takes. Each member is present where it applies; an
        integer field has integer values.
      properties:
        min:
          type: number
          description: The least value allowed.
        max:
          type: number
          description: The greatest value allowed.
        default_value:
          type: number
          description: >-
            The value used when the field is left out. Named `default_value`,
            since `default` is a reserved word in Java and C#.
        excluded_min:
          type: number
          description: >-
            The first value of a gap inside the range, where no value is
            allowed. `max_characters` allows 0 and then 1,000 upward, so its gap
            runs from 1 to 999.
        excluded_max:
          type: number
          description: The last value of a gap inside the range, 999 for `max_characters`.
    TableSpan:
      type: object
      description: 'One merged cell of a table: where it starts and how far it reaches.'
      required:
        - row
        - column
        - row_span
        - column_span
      properties:
        row:
          type: integer
          minimum: 0
          description: The row the cell starts in, from 0.
        column:
          type: integer
          minimum: 0
          description: The column the cell starts in, from 0.
        row_span:
          type: integer
          minimum: 1
          description: How many rows the cell covers, 1 or more.
        column_span:
          type: integer
          minimum: 1
          description: How many columns the cell covers, 1 or more.
    CellAddress:
      type: object
      description: One cell of a table, by its row and its column, both counted from 0.
      required:
        - row
        - column
      properties:
        row:
          type: integer
          minimum: 0
          description: The row, from 0.
        column:
          type: integer
          minimum: 0
          description: The column, from 0.
    CellConfidence:
      type: object
      description: How sure the recognition was of one cell of a table read from a scan.
      required:
        - row
        - column
        - confidence
      properties:
        row:
          type: integer
          minimum: 0
          description: The cell's row, from 0.
        column:
          type: integer
          minimum: 0
          description: The cell's column, from 0.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: The confidence, 0 to 1.
    Review:
      type: object
      description: The review a publication states about itself.
      required:
        - kind
        - by
      properties:
        kind:
          type: string
          description: >-
            The kind of review: `peer_reviewed`, `editorial`, `audited`,
            `externally_validated`, `none` or `unknown`. A closed set.
          enum:
            - peer_reviewed
            - editorial
            - audited
            - externally_validated
            - none
            - unknown
        by:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            Who reviewed it; null when unknown. Third-party text as the source
            wrote it, which may carry instructions.
  headers:
    RequestId:
      description: >-
        This call's id, a `req_` id, on every response. The body repeats it as
        `request_id` where a body is sent. A replayed answer carries this call's
        id, never the first call's. Quote it when you ask about a call.
      required: true
      schema:
        type: string
        pattern: ^req_[A-Za-z0-9]{22}$
    RateLimit:
      description: >-
        What is left of your quota, in the form of
        `draft-ietf-httpapi-ratelimit-headers-11`, two items named as in
        `RateLimit-Policy`: `"requests";r=<left>;t=<seconds>`, the requests left
        and the seconds to the window's reset; `"concurrency";r=<left>`, the
        calls you may still have in flight. Sent on every response but a `401`.
        `get_limits` returns the same figures in the body as `rates`. A `429`
        names the policy it exceeded in `detail`: `rate-limit-exceeded` for
        requests, `concurrency-limit-exceeded` for concurrency.
      required: true
      schema:
        type: string
    RateLimitPolicy:
      description: >-
        Your key's rate policy, in the form of
        `draft-ietf-httpapi-ratelimit-headers-11`, two items:
        `"requests";q=<requests_per_minute>;w=60`, the requests allowed per
        minute; `"concurrency";q=<concurrency>;qu="concurrent-requests"`, the
        calls allowed in flight at once. Sent on every response but a `401`.
      required: true
      schema:
        type: string
    Sunset:
      description: >-
        The moment a resource is retired, as an IMF-fixdate, sent on every
        answer of that resource once its retirement is announced, RFC 8594. It
        is never used for a retiring version of getclean itself: that is
        announced by the notice `version_retiring` and by `Version.retires_at`,
        since a client that knows only RFC 8594 would read `Sunset` as the end
        of the resource.
      required: false
      schema:
        type: string
    Deprecation:
      description: >-
        The moment a resource's or an element's retirement was announced, as a
        Structured Field Date, `@` and the seconds, RFC 9745. Sent on every
        answer of that resource or element from the announcement on, beside
        `Sunset` once the end is set.
      required: false
      schema:
        type: string
    Location:
      description: >-
        The absolute URL of what the call made: the record on a `201`, the job
        on a `202`.
      required: true
      schema:
        type: string
        format: uri
    RetryAfterRequired:
      description: >-
        Seconds to wait before asking again, an integer of 1 or more, repeated
        in the body as `retry_after_seconds`. Always sent on `202`, `429` and
        `503`.
      required: true
      schema:
        type: integer
        minimum: 1
    WwwAuthenticateRequired:
      description: >-
        The `WWW-Authenticate` value of a `401`, which tells a client where to
        sign in. With no credential sent: `Bearer realm="getclean",
        resource_metadata="https://api.getclean.ai/.well-known/oauth-protected-resource"`.
        With a credential sent and rejected: the same with
        `error="invalid_token"` added, RFC 6750 section 3 and RFC 9728 section
        5.1. The document it names is the API's protected resource metadata,
        served to anyone outside the versioned paths; an agent that arrives with
        nothing follows it to the issuer and its device sign-in.
      required: true
      schema:
        type: string
    WwwAuthenticate:
      description: >-
        Sent on a `403` only when the type is `insufficient-scope`: `Bearer
        realm="getclean", error="insufficient_scope",
        resource_metadata="https://api.getclean.ai/.well-known/oauth-protected-resource"`,
        with the `scope` attribute naming every scope the call needs, the same
        list as the body's `scopes_required`. Never sent on the other `403`s.
      required: false
      schema:
        type: string
    RetryAfter:
      description: >-
        Seconds to wait before asking again, an integer of 1 or more, repeated
        in the body as `retry_after_seconds`. On a `200` of `get_job` or
        `cancel_job` it is sent only while the job is not finished; on a `409`
        only when the type is `idempotency-key-in-flight`.
      required: false
      schema:
        type: integer
        minimum: 1
    Accept:
      description: On a `415`, the media types this operation takes.
      required: true
      schema:
        type: string
    AcceptEncoding:
      description: >-
        On a `415` caused by a content coding: `gzip`, the coding JSON bodies
        take; `identity` on the upload, which takes none.
      required: false
      schema:
        type: string
    Link:
      description: >-
        On a `451`, `rel="blocked-by"`, pointing at getclean's own notice page
        for the demand: the party that implements the block, as RFC 7725 section
        4 asks, never the demanding party, which `demanded_by` names.
      required: false
      schema:
        type: string
  responses:
    Problem400:
      description: >-
        The request could not be read, or a value outside its body is wrong, so
        nothing was done. Two problem types answer `400`.

        - `invalid-request`, The request is invalid: the body did not parse, a
        path, query or header value is wrong, an id has the wrong form, or a
        required header is missing. Each fault stands in `violations` with where
        it is.

        - `page-token-invalid`, The page token is invalid: the token is unknown,
        expired, belongs to another record, or the filter changed between pages.
        `change.field` names `page_token`; drop the token and start the list
        again.


        A plain HTTP request is answered `invalid-request` over that connection,
        with `detail` naming the HTTPS URL, never a redirect.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem401:
      description: >-
        `unauthorized`, The key is missing or rejected. `WWW-Authenticate`
        carries the challenge, and `detail` says which case it is:

        - No credential sent: "No credential was sent: send Authorization:
        Bearer with an API key from https://app.getclean.ai, or sign in as
        https://auth.getclean.ai/auth.md describes."

        - A credential sent and rejected: "The credential is unknown, expired or
        revoked: refresh the token, sign in again, or use another key."

        - A credential in the query string only: "A credential in the query
        string is ignored: send it in the Authorization header as Bearer."


        The credential is never echoed. No `RateLimit` or `RateLimit-Policy`
        header is sent, since no account's quota applies.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticateRequired'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem403:
      description: >-
        The key was accepted but is not allowed to do this, by its scopes, its
        policy or its money. Six problem types answer `403`; the first is yours
        to fix when you hold an access token, and the rest are the account
        owner's.

        - `insufficient-scope`, The key lacks a scope this call needs: every
        scope the call needs is in `scopes_required` and in `WWW-Authenticate`.
        With an access token, ask the person for the scope again; with an API
        key, the account owner adds it.

        - `policy-limit-exceeded`, The key's policy forbids this: a domain, a
        setting, a minimum or a cost cap the key's policy forbids, a request
        looser than the policy, or the key's cap below the smallest call, with
        `minimum_cap`.

        - `datasource-access-required`, The datasource needs a registered login.

        - `credit-exhausted`, The credit is exhausted: `balance`,
        `amount_needed` and `funding_url`.

        - `run-budget-exhausted`, The run's budget is exhausted:
        `run_budget_remaining`, `amount_needed` and `funding_url`.

        - `key-budget-exhausted`, The key's budget is exhausted:
        `key_budget_remaining`, `amount_needed` and `funding_url`.


        `amount_needed` is what the limit that binds lacks for the smallest
        call: the call's price less what the limit holds.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticate'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem404:
      description: >-
        `not-found`, Not found: the record, job, datasource, section or block an
        id names does not exist for this account; `change.field` says which id.
        An id of another account's record gets the same `404` with the same
        body, kept or expired. A replay whose record was deleted is `404` too,
        with `detail` naming the deletion. RFC 9110 reserves `404` and `410` for
        the target resource; here `404` also answers an id named in a body or a
        query, since the thing named is what is missing, a stated departure. An
        unknown `run_id` is not a `404`: it is `422 invalid-field` in a body and
        `400 invalid-request` in a query, kind `not_allowed`, since a run is a
        setting of the key and not a resource here.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem409:
      description: >-
        The call clashes with the state of what it names. Two problem types
        answer `409`.

        - `idempotency-key-in-flight`, The same request is still running: the
        first call with this key has not answered yet. `Retry-After` and
        `retry_after_seconds` say when to ask again; ask again with the same key
        after that wait, and once the first call has answered, the same key
        returns its answer.

        - `record-without-content`, The record has no content: the record you
        named failed, was refused or needs a person, so there is no text to
        read. `change` names `fetch_contents`; this one is never retried.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem413:
      description: >-
        `body-too-large`, The body is too large. The bounds: a JSON body at most
        256 KB, a KB being 1,000 bytes; a batch body at most 4 MiB; a comparison
        body at most 8 MiB; the upload's multipart body at most 101 MiB, with
        the document part at most 100 MiB. Every bound counts the bytes as sent,
        except a gzip-coded JSON body, which counts the decoded bytes. The
        upload is checked by the declared length first and again as the document
        part passes its bound.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem415:
      description: >-
        `unsupported-media-type`, The media type is not supported: the request's
        media type, or its content coding, is not one this operation takes.
        `Accept` names the media types the operation takes; `Accept-Encoding`
        names the coding, `gzip`, when a coding caused it.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Accept:
          $ref: '#/components/headers/Accept'
        Accept-Encoding:
          $ref: '#/components/headers/AcceptEncoding'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem422:
      description: >-
        The request was read, and a field or a rule between fields refuses it;
        each is yours to fix. Eleven problem types answer `422`.

        - `invalid-field`, A field is invalid: a body value broke its bound, its
        set, its form or a rule between fields. Every violation is reported at
        once in `violations`.

        - `destination-refused`, The destination is refused: the URL's text
        names localhost, an address that is not globally reachable, or a port
        the Fetch standard lists as bad; never a resolved address.

        - `model-work-refused`, Model work is refused by the request: a model
        field was sent under the request's own `deterministic_only`; every such
        field is named in `violations`.

        - `cost-exceeds-cap`, The cost cap is below the smallest call: the
        request's `max_cost` is below the smallest call's price; `minimum_cap`
        gives the least cap that would run it.

        - `version-withdrawn`, The version is no longer served: `pinned_version`
        names a version never served or no longer served;
        `change.allowed_values` lists the versions served.

        - `records-incomparable`, The records cannot be compared: the two
        records come from another version or another scope.

        - `idempotency-key-reused`, The idempotency key was reused with another
        body.

        - `no-datasource-can-run`, No datasource can run this search: every
        source would be skipped before work.

        - `datasource-unknown`, The datasource is unknown.

        - `datasource-not-searchable`, The datasource has no search.

        - `domain-set-unknown`, The domain set is unknown: an unknown
        `set:NAME`.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            fetch_contents.invalid-field:
              summary: A formats value outside its set
              value:
                type: https://api.getclean.ai/problems/invalid-field
                title: A field is invalid
                status: 422
                detail: formats holds a value outside its set.
                instance: https://api.getclean.ai/requests/req_01JSUEOJ23EQgBxGjfSpcD
                request_id: req_01JSUEOJ23EQgBxGjfSpcD
                who_must_act: caller
                retryable: false
                violations:
                  - kind: not_allowed
                    place: body
                    pointer: /formats/0
                    field: formats
                    message: The value at the pointer is not a value of formats.
                    allowed_values:
                      - markdown
                      - html
                      - doclang
                      - json
                      - links
                      - screenshot
                      - raw_html
            upload_contents.invalid-field:
              summary: The upload's document and url sent together
              value:
                type: https://api.getclean.ai/problems/invalid-field
                title: A field is invalid
                status: 422
                detail: document and url exclude each other; send one.
                instance: https://api.getclean.ai/requests/req_01NdCq5kEHkceDpAo9MfAV
                request_id: req_01NdCq5kEHkceDpAo9MfAV
                who_must_act: caller
                retryable: false
                violations:
                  - kind: exclusive
                    place: form
                    field: url
                    message: excludes document
                  - kind: exclusive
                    place: form
                    field: document
                    message: excludes url
    Problem429:
      description: >-
        The key is calling too often, or has too many calls in flight. Two
        problem types answer `429`. `detail` names the policy exceeded;
        `Retry-After` and `retry_after_seconds` say when to ask again; the SDKs
        retry both for you.

        - `rate-limit-exceeded`, The rate limit is exceeded: more requests in
        the minute than the requests policy allows.

        - `concurrency-limit-exceeded`, Too many calls are in flight: more calls
        at once than the concurrency policy allows.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Retry-After:
          $ref: '#/components/headers/RetryAfterRequired'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem451:
      description: >-
        `legal-block`, Withheld under a legal demand: a demand made on getclean
        itself, not on a source. `demand`, `demanded_by` and `applies_to` name
        it, and `Link` with `rel="blocked-by"` points at getclean's own notice
        page. `retryable` is false. Your next step is another source, never
        another `subject_country`. A demand on a source is never an API problem:
        it is that record's or that source's outcome `legal_block`.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Link:
          $ref: '#/components/headers/Link'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem500:
      description: >-
        `internal-error`, The service failed: getclean's own failure, never a
        source's. getclean must fix it; the SDKs do not retry it. Quote the
        `Request-Id` when you report it.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem503:
      description: >-
        `overloaded`, The service is overloaded: the request could not start
        within the published queue bound, or a batch item was not started.
        `Retry-After` and `retry_after_seconds` say when to ask again; ask again
        with the same key after that wait, and once the first call has answered,
        the same key returns its answer.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Retry-After:
          $ref: '#/components/headers/RetryAfterRequired'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        An API key from https://app.getclean.ai, or an access token issued by
        https://auth.getclean.ai/realms/getclean, sent as `Authorization: Bearer
        <key>` on every call. The scopes a key carries and what a 401 and a 403
        say are on the keys and sign-in page.

````

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