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:
    post:
      operationId: fetch_contents
      summary: Fetch contents
      description: |-
        Fetch a web page or a document at a URL. You get its main content with the structure intact, in the formats you ask for, the map of its sections, the facts of the source, a fingerprint and the price, as one record that is kept for later reads.

        The record is kept 48 hours after its last call and at most 30 days from its making, and every later question about it, through `get_contents`, `get_section`, `list_blocks` and `list_links`, is answered from the same copy, free. Use `upload_contents` for a file you hold, or for a long document that must run as a job; use `search` when you have a question and no URL yet; 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 request before any work, so a missing scope is `403` before any `422`. The price is 1 `contents`, plus `document_pages` and `recognized_pages` when the URL serves a document, plus `model_steps` for each model field that ran, plus `screenshots` when one was made. An `unchanged` answer bills the same 1 `contents`. A fetch that failed, was refused or needs a person bills nothing.

        **What comes back.** `201 Created`, with `Location` naming the record, for every outcome kind: a page that could not be read is still a record, whose `outcome` says what happened and what may work next. The record reads in one order: what happened, the notices to read first, when the fetch ran, the content or the map, the facts of the source, the fingerprint, the price.

        **The idempotency key.** `Idempotency-Key` is optional here. The same key with the same body 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 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.

        **How the text fits `max_characters`.**
        - It fits: the text formats come whole; the reason is `whole`; `truncated` is false.
        - It does not fit: no text format comes; `sections`, the map, comes instead; the reason is `sections_only`; `truncated` is true. `screenshot` and `raw_html` still come.
        - It does not fit and a highlight was found: the sections that hold highlights come in document order while they fit; a section larger than what remains is cut at a block edge with its highlighted blocks inside; the map comes too, as with `max_characters: 0`, and does not count against the limit; the reason is `matching_sections`; `truncated` is true; `get_section` has the rest.
        - `max_characters: 0`: no text; the map comes; the reason is `whole`; `truncated` is false; `screenshot`, `raw_html` and `links` still come, the links within their cap.
        - The map always carries level 1 and `s0`, however many rows. Deeper levels come one whole level at a time from the top, while their rows fit `max_characters`; under `0`, while the rows number at most 200. The notice `sections_cut` says when levels were left out.
        - Two text formats each carry the whole content, so the answer is twice as long; `max_characters` bounds the content once, and each format carries it.
        - A sent `max_characters` with no text format bounds nothing and makes the notice `field_not_applicable`; the default makes none. `links`, `screenshot` and `raw_html` are outside it.
        - To learn a document's size and price for one `contents` unit, send `max_characters: 0` with `max_cost` at the smallest call's price: no page is parsed beyond the count and the outline.

        **The formats.** `block_kinds` narrows every format: the text formats and `links` hold only those blocks, and `highlights`, `json_schema` and `summary` read only those blocks; `whole` then means all of them fit; `counts` stays the page's. `scope: whole_page` makes the blocks, the sections and the counts cover the whole page, and `left_out` is `[]`. A highlight is marked `<mark id="h1">…</mark>` in `markdown` and `html` and listed in `highlight_ids` on `blocks`; nothing is marked in `doclang`, `links`, `screenshot` or `raw_html`; with no text returned, the `highlights` list still comes with its ids and places. Every occurrence of a string is a highlight, in document order, at most 50 per call, with the notice `highlights_cut` past that. `highlights`, `json_schema` and `summary` read the whole content, or the chosen blocks, whatever `max_characters` says; the bound limits what is returned, not what they read. `summary` is at most 1,500 characters, in the content's language. `summary` and `schema_values` carry no link and no image; any a model writes is removed with the notice `model_link_removed`, and a URL value is kept only when it stands in the record's links or text.

        **Each highlight string.**
        - Found `exact`: its words stand in one block, after Unicode normalization and whitespace collapse, case kept. Free.
        - Found `near`: its words stand there after case folding, with ellipses and the punctuation at the ends of words removed, punctuation inside a word kept, pieces in order, and the dotted and dotless i of Turkic scripts folded to one. Free.
        - Not found verbatim: a model picks the blocks that bear on it, `judged`. One model step per call, however many strings needed it.
        - Not found, and nothing bears on it, or `deterministic_only`: the notice `highlight_not_found`, one per string. The step's price when a model judged it, free under `deterministic_only`.

        **`deterministic_only`.** Nothing runs whose output could differ between two runs of the same input: highlights are found verbatim only; `json_schema` and `summary` are refused as `model-work-refused`, both fields named in `violations`; the publisher's kind comes only from what getclean already knows. Text recognition on a scanned page still runs and is listed, since it repeats under one version. A key whose policy forbids model work refuses `json_schema` and `summary` with `policy-limit-exceeded` and finds highlights verbatim only; `deterministic_only: false` under such a key is `policy-limit-exceeded`, since a request never loosens the key.

        **`baseline_fingerprint`.** On a page: the page is read in full and its fingerprint compared. If it matches, the answer is `unchanged`: no text, no highlights, no fill, no summary, `formats` echoed `[]`, while the record keeps the content, which `get_contents` reads. On a document at a URL: the bytes are fetched; when a record of your account issued the fingerprint you sent and its `document_digest` equals the bytes' digest, the answer is `unchanged` without a parse; otherwise the parse runs and bills its pages, and a matching content fingerprint then answers `unchanged`. If no record of your account issued the fingerprint, you get the notice `fingerprint_unknown`, and the fetch runs whole at the full price. A fingerprint matches only under the scope, the version, the configuration and the kind of source that made it; one issued under another makes the notice `fingerprint_incomparable`, naming which, and the fetch runs whole at the full price. A fingerprint of a record no longer kept is `fingerprint_unknown` too, so an agent that comes back after its record expired pays the full price and compares fingerprints itself.

        **`as_of_date`.** The record is an archive copy: `source.carrier` is `archive`, `source.archive` names the copy, and `source.archives_consulted` names the archives of `Limits.archives` that answered. The copy is the latest capture at or before 23:59:59 UTC of that day whose archived status was 2xx, so a capture later on that day may come, `archive.captured_at` showing when; an agent that needs the state before an event asks for the day before. `source.next_capture_at` comes when a later capture exists, so an agent steps forward capture by capture. No such copy is `no_history`. `subject_country`, `subject_language`, `screenshot` and `max_source_price` are not applied to an archive copy, a notice each.

        **`screenshot` and `raw_html`.** The screenshot is of the live page only: the whole page at its full width, as PNG, with its digest, by a URL getclean serves for as long as the record lives. It ignores `scope` and `block_kinds`. It is taken on a second visit to the page, which may be served another page. `raw_html` is the page's bytes exactly as the server sent them, decompressed, before any script ran, on an archive copy as the archive served them, with their digest, their size and the `Content-Type` sent; by a URL under `retention` `hold`, inline as `data_base64` under `none`. It ignores `scope`, `block_kinds` and `max_characters`, and it is free. The served bytes and their digest let you show later exactly what the server sent.

        **A document at the URL.** It is parsed inside the fetch. Past `wait_seconds` the pages parsed come back `partial`, `time_capped`, with the notice `upload_to_finish`; past `max_cost` they come back `partial`, `cost_capped`. `pages.count` and the outline come even when no page was parsed.

        **Money, country and version.** `max_cost` is reserved at the start against the ceiling: the lowest of `max_cost`, the key's cap, the run's budget, the key's budget and the balance. It is spent in one order, the read of the page or of the document's pages first, then `json_schema`, `highlights`, `summary` and `screenshot`. When the ceiling, a budget or the deadline cannot cover everything, the extras are cut from the end, each cut a notice naming the field, and the pages are stopped last, the record `partial`. A run's or a key's budget that stops a parse is `budget_capped`, with the notice `budget_cut`. `max_source_price`: getclean pays no site, whatever the value; a site that asks a price ends `failed`, `payment_required`, with the price in `cost.source_price` and the protocol named in the message. `subject_country` is the country the page is read from; a page that says it is not offered there is `region_restricted`, and a site that refuses the visitor with a block page is `blocked`. `pinned_version`: `execution.version` equals it.

        **Fields that do not apply to some sources.** Each is a notice `field_not_applicable` naming the field, never a refusal, so a client that always sends a field still works on every source:
        - `doclang`, `screenshot`, `raw_html` or `scope: whole_page` on a URL that serves a document;
        - `recognition_languages` on a web page;
        - `subject_country`, `subject_language`, `screenshot` or `max_source_price` with `as_of_date`;
        - a sent `max_characters` with no text format;
        - `block_kinds` with nothing to narrow.

        The table under `Contents` says which members each kind of source carries.

        **Refused before any work**, every violation of the body reported at once in `violations`:
        - `scope`, a `formats` value, a `block_kinds` value or `retention` outside its set: `invalid-field`, `not_allowed`.
        - A duplicate in `formats` or `block_kinds`: `duplicate`. An empty `block_kinds` list: `bound`; send `formats: []` for the facts alone.
        - `max_characters` between 1 and 999: `bound`.
        - `json_schema` or `summary` under the request's `deterministic_only`: `model-work-refused`, both fields named.
        - `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`, with `minimum_cap`.
        - A scheme other than http or https, a password in the URL's userinfo, or a malformed `baseline_fingerprint`: `syntax`.
        - localhost, an address that is not globally reachable, or a port the Fetch standard lists as bad: `destination-refused`.
        - A host outside the key's domain policy, or a URL the key's `policy.refuse_credential_urls` refuses: `403 policy-limit-exceeded`.
        - A `subject_country` getclean cannot read from: `not_allowed`, with the countries it can read from in `allowed_values`.
        - A `json_schema` that is not valid JSON Schema 2020-12: `syntax`. 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`.
        - A missing `url`: `required`. Any other bound passed: `bound`. An unknown field: `unknown_field`.
        - `pinned_version` not served, never or no longer: `version-withdrawn`, with the versions served.

        The one exclusive pair is `deterministic_only` against `json_schema` and `summary`. No dependent field refuses; `block_kinds` with nothing to narrow is a notice. Every other pair is independent.

        **Notices this operation makes.** `highlight_not_found`, `highlights_cut`, `sections_cut`, `links_cut`, `hidden_text_cut`, `structured_data_cut`, `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`, `archive_unreachable`, `default_set_by_policy`, `version_retiring`. `content_not_rendered` is a published code 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; `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.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/Traceparent'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchContentsRequest'
            examples:
              fetch_contents.delivered:
                summary: A page fetched with two highlights and a summary
                value: {"url": "https://example.com/q3", "highlights": ["Revenue rose 12%", "what drove the margin"], "summary": true}
              fetch_contents.failed:
                summary: A failed fetch, a bot challenge where the page should be
                value: {"url": "https://shop.example/offer"}
      responses:
        '201':
          description: >-
            The record, `Contents`, for every outcome kind, with `Location` naming it; a fetch that failed, was refused or needs a person is a record too, its `outcome` saying what happened.
          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/Contents'
              examples:
                fetch_contents.delivered:
                  summary: A page fetched with two highlights and a summary
                  value: {"id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "outcome": {"kind": "delivered", "reason": "whole"}, "notices": [], "fetched_at": "2026-11-04T08:40:12Z",
                    "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "record_scope": "main", "formats": ["markdown"], "truncated": false,
                    "markdown": "# Quarterly results\n\n<mark id=\"h1\">Revenue rose 12%</mark> to … <mark id=\"h2\">Margin expanded on lower input costs and mix.</mark> …",
                    "counts": {"characters": 6210, "blocks": {"heading": 4, "text": 22, "table": 1}, "links": {"page": 9}},
                    "highlights": [{"id": "h1", "query_index": 0, "text": "Revenue rose 12%", "basis": "exact", "section_id": "s1", "block_id": "b3"},
                      {"id": "h2", "query_index": 1, "text": "Margin expanded on lower input costs and mix.", "basis": "judged", "section_id": "s2", "block_id": "b9"}],
                    "summary": "Revenue rose 12% in the quarter, driven by volume in Europe; margin expanded on lower input costs and mix; guidance was raised.",
                    "hidden_text": [], "left_out": [{"kind": "navigation", "characters": 1480}],
                    "source": {"url": "https://example.com/q3", "final_url": "https://example.com/q3", "redirects": [], "status_code": 200, "media_type": "text/html",
                      "carrier": "web", "access_kind": "open", "title": "Quarterly results", "authors": [], "published_date": "2026-10-28", "published_date_precision": "day",
                      "published_date_basis": "structured_data", "modified_date": null, "publisher": "Example Corp", "canonical_url": null, "language": "en",
                      "language_versions": [], "profile": {"kind": "company", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "robots": "allowed", "declared_terms": [], "structured_data": [{"@type": "NewsArticle", "headline": "Quarterly results"}],
                      "origins": [{"origin": "https://cdn.example.com", "kind": "script"}], "visitor": {"country": "DE", "language": "de-DE,de;q=0.9", "network": "datacenter"}},
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "highlights", "version": "hl-2026-10"}, {"step": "summary", "version": "sum-2026-10"}], "elapsed_seconds": 7.1},
                    "cost": {"ceiling": {"amount": "0.0500", "currency": "USD"}, "actual": {"amount": "0.0090", "currency": "USD"}, "units": {"contents": 1, "model_steps": 2}, "replayed": false},
                    "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-06T08:40:12Z", "request_id": "req_01JzsALAAlsNsdoVz1EElr"}
                fetch_contents.failed:
                  summary: A failed fetch, a bot challenge where the page should be
                  value: {"id": "cnt_7Qp2cdxxK32qkfIDrqRUE2", "outcome": {"kind": "failed", "reason": "challenge_served", "message": "A bot challenge stood where the page should be; a retry later may work on sites that do not challenge every new visitor, or a person opens the URL and uploads the saved page with captured_url."}, "notices": [], "fetched_at": "2026-11-04T08:41:03Z", "truncated": false,
                    "source": {"url": "https://shop.example/offer", "final_url": "https://shop.example/offer", "redirects": [], "status_code": 403, "media_type": "text/html", "carrier": "web", "access_kind": "open",
                      "title": "Just a moment", "authors": [], "published_date": null, "modified_date": null, "publisher": null, "canonical_url": null, "language": "en", "language_versions": [],
                      "profile": {"kind": "marketplace", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "robots": "allowed", "declared_terms": [], "structured_data": [], "origins": [{"origin": "https://challenges.example", "kind": "script"}], "visitor": {"country": "DE", "language": "de-DE,de;q=0.9", "network": "datacenter"}},
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [], "elapsed_seconds": 2.4},
                    "cost": {"ceiling": {"amount": "0.0500", "currency": "USD"}, "actual": {"amount": "0.0000", "currency": "USD"}, "units": {}, "replayed": false},
                    "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-06T08:41:03Z", "request_id": "req_01KXuaBXEPybVuXmnCI9Bl"}
        '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'}
    get:
      operationId: list_contents
      summary: List contents
      description: |-
        List the records the account keeps, newest first, free. Each item is a `ContentsCompact`: the record's id, outcome, source and dates, with no text, no map, no model work and no cost, and its `execution` as stored.

        Use it to see which pages the account already has before fetching one again; `get_contents` reads one record whole. Every filter you send must match. The list does not move any record's `expires_at`.

        **What it costs.** The key needs `contents:read`. The call is free. The answer is `200` with `ContentsPage`.

        **Paging.** `page_size` from 1, default 50, maximum 200; a value above the maximum is lowered with the notice `page_size_lowered` and never refused; a value below 1 is refused `bound`. `page_token` is opaque, bound to its query, alive 24 hours; `next_page_token` is absent on the last page, and a page that carries it holds at least one record. A changed filter between pages, `page_size` excepted, or an unknown, expired or another list's token, is `400 page-token-invalid` with `change.field` naming `page_token`: drop the token and start again. A record made while you page may make an item repeat; when you merge pages, keep one entry per `id`.

        **Refused before any work.** A value outside its set or range, `page_size` above its maximum excepted, which is lowered: `400 invalid-request`, `not_allowed` or `bound`, each with where it is. A `run_id` of the wrong form: `400 invalid-request`, `syntax`; an unknown run: `400 invalid-request`, `not_allowed`, since a run is a setting of the key and not a resource here. A token of another list: `400 page-token-invalid`. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `page_size_lowered`, `version_retiring`.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: url
          in: query
          required: false
          description: >-
            Only records whose `source.url` equals it, or starts with it when it ends in `*`, the one place a `*` may stand; the scheme and the host are compared in lower case. At most 2,048 characters. Default none.
          schema:
            type: string
            minLength: 1
            maxLength: 2048
            examples: ['https://example.com/*']
        - name: carrier
          in: query
          required: false
          description: >-
            Only records of this kind of source: `web`, a live page; `archive`, an archive's copy read under `as_of_date`; `upload`, bytes you sent. An open set. Default none.
          schema:
            type: string
            minLength: 1
            examples: [web, archive, upload]
        - name: run_id
          in: query
          required: false
          description: >-
            Only records of this run, an existing run of the key. Default none.
          schema:
            type: string
            pattern: '^run_(default|[A-Za-z0-9]{22})$'
            examples: [run_default]
        - name: page_size
          in: query
          required: false
          description: >-
            At most this many records on the page, from 1; default 50; the maximum, 200, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            The next page, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, never built by the caller. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            One page of the records the account keeps, newest first, each compact and without text; `next_page_token` while more remain.
          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/json:
              schema:
                $ref: '#/components/schemas/ContentsPage'
              examples:
                list_contents.first-page:
                  summary: A list with one record, about one site
                  value: {"contents": [{"id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "outcome": {"kind": "delivered", "reason": "whole"}, "notices": [], "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "record_scope": "main", "formats": [], "truncated": false, "counts": {"characters": 6210, "blocks": {"heading": 4, "text": 22, "table": 1}, "links": {"page": 9}},
                      "source": {"url": "https://example.com/q3", "final_url": "https://example.com/q3", "title": "Quarterly results", "published_date": "2026-10-28"},
                      "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "highlights", "version": "hl-2026-10"}, {"step": "summary", "version": "sum-2026-10"}], "elapsed_seconds": 7.1}, "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-06T08:40:12Z"}],
                    "notices": [], "request_id": "req_01Sof5z2SAa45Wc4HZYpfe"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/contents/{contents_id}:
    get:
      operationId: get_contents
      summary: Get contents
      description: |-
        Read a record you already have, free: the same copy in any format, at any size, under either view, with the model work the fetch made.

        Give it the `cnt_` id an earlier `fetch_contents`, `upload_contents` or `search` returned. Nothing is fetched from the web; the answer comes from the copy getclean kept. Use `fetch_contents` for a URL; use `get_section`, `list_blocks` and `list_links` to read one part of the record at a time.

        **What it costs.** The key needs `contents:read`. The call is free, so the record carries no `cost` on this answer.

        **What comes back.** `200` with `Contents`. The call moves the record's `expires_at` 48 hours ahead, never past 30 days from the record's making.
        - The record's facts come as stored: `outcome`, `fetched_at`, `fingerprint`, `record_scope`, `source`, `pages`, `execution`, `retention`, `screenshot`, `raw_html`, and the fetch's `highlights`, `summary`, `schema_values` and `schema_statuses`.
        - This answer's own: `scope`, the view delivered; `truncated`; `formats`; its notices after the record's own; `request_id`; `expires_at`.
        - Under the record's own view, `counts`, `hidden_text` and `left_out` are the record's as stored; under the other view they describe that view.
        - The text fits or does not fit under this call's `max_characters` as `fetch_contents` says; `truncated` says which. The record's `outcome` is never rewritten.
        - The model work the fetch made comes back free, the marks placed where a highlighted block appears in the text returned. A new question is a call to `highlight_contents`, `fill_schema` or `summarize_contents`.
        - `scope: whole_page` on a record fetched under `main` gives the whole page from the same read, free. The `fingerprint` stays that of `record_scope`; `counts` cover the page and `left_out` is `[]`; the section and block ids are the whole-page view's, and the fetch's highlights carry that view's ids. A document has one view, so `whole_page` on a document record makes the notice `field_not_applicable`.
        - A record without content, failed, refused or needs a person, comes back as stored; the query's parameters make no notice, since nothing was asked of the text. An `unchanged` record keeps its content and is answered.
        - `doclang` on a document that is not HTML is left out with the notice `field_not_applicable`.

        **Refused before any work.**
        - A value outside its set, `max_characters` between 1 and 999, a duplicate or an empty list: `400 invalid-request`, `not_allowed`, `bound` or `duplicate`, each with where it is.
        - An id of the wrong kind: `400 invalid-request`, before any lookup.
        - An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `sections_cut`, `links_cut`, `field_not_applicable`, `version_retiring`, after the record's own notices.

        **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.
        - 404 `not-found`, Not found: an unknown or another account's record.
        - 410 `contents-expired`, The record has expired: for 30 days after it expired, to the owning account only, with `expired_at` and `change` naming `fetch_contents` and `url`; then `404`.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record to read, a `cnt_` id as `fetch_contents`, `upload_contents` or `search` returned it.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_5Gh7cdyeVQ6qoJhBFE31L1
        - name: max_characters
          in: query
          required: false
          description: >-
            The most text to return, in characters. `0` returns no text but the map of sections and the facts. Default 20,000; `0`, or 1,000 to 1,000,000; a value between 1 and 999 is refused `bound`.
          schema:
            type: integer
            minimum: 0
            maximum: 1000000
            default: 20000
        - name: scope
          in: query
          required: false
          description: >-
            Which view to return: `main`, the main content alone, or `whole_page`, everything on the page from the same read. Default the record's own view, `record_scope`. A document has one view, so `whole_page` on a document record makes the notice `field_not_applicable`.
          schema:
            $ref: '#/components/schemas/Scope'
        - name: formats
          in: query
          required: false
          style: form
          explode: true
          description: >-
            The formats to return, 1 to 5 of these, one value per repeated key: `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 a page or an HTML file only; `json`, as `Block` objects; `links`, every link with its kind. Default `markdown`. `screenshot` and `raw_html` are not values here; the ones the fetch made come with every answer. An open set; a key sent with an empty value is an empty list, refused `bound`, and a repeated value is refused `duplicate`.
          schema:
            type: array
            minItems: 1
            maxItems: 5
            uniqueItems: true
            default: [markdown]
            items:
              type: string
              minLength: 1
              examples: [markdown, html, doclang, json, links]
              description: >-
                One of the formats the field lists.
        - name: block_kinds
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Keep only blocks of these kinds, in every format: 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`, an open set, one value per repeated key. Default: every kind.
          schema:
            type: array
            minItems: 1
            maxItems: 10
            uniqueItems: true
            items:
              type: string
              minLength: 1
              description: >-
                One of the block kinds the field lists.
      responses:
        '200':
          description: >-
            The record, `Contents`, read from the copy getclean keeps: the record's facts as stored, this answer's `scope`, `truncated` and `formats`, and no `cost`.
          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/json:
              schema:
                $ref: '#/components/schemas/Contents'
              examples:
                get_contents.delivered:
                  summary: A record you already have, read whole under a larger max_characters than its fetch allowed
                  value: {"id": "cnt_5Gh7cdyeVQ6qoJhBFE31L1", "outcome": {"kind": "delivered", "reason": "sections_only"}, "notices": [], "fetched_at": "2026-11-04T08:50:30Z",
                    "fingerprint": "sha-256=:Vn2VtrGw48PmhVZSc0+War4NLekU3Ecg5FLbdwF1nMM=:", "scope": "main", "record_scope": "main", "formats": ["markdown"], "truncated": false,
                    "markdown": "# Annual report 2025\n\n…the whole text under max_characters 200000…",
                    "counts": {"characters": 61200, "blocks": {"heading": 14, "text": 120, "table": 6}, "links": {"page": 40}},
                    "hidden_text": [], "left_out": [{"kind": "navigation", "characters": 1480}],
                    "source": {"url": "https://example.com/annual-2025", "final_url": "https://example.com/annual-2025", "redirects": [], "status_code": 200, "media_type": "text/html", "carrier": "web", "access_kind": "open", "title": "Annual report 2025", "authors": [], "publisher": "Example Corp", "canonical_url": null, "published_date": "2026-03-12", "published_date_precision": "day", "published_date_basis": "structured_data", "modified_date": null, "language": "en", "language_versions": [], "profile": {"kind": "company", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "robots": "allowed", "declared_terms": [], "structured_data": [], "origins": [], "visitor": {"country": "DE", "language": "de-DE,de;q=0.9", "network": "datacenter"}},
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [], "elapsed_seconds": 9.0},
                    "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-06T12:00:00Z", "request_id": "req_01PaufBlzLM6CZzXNwUinf"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '404': {$ref: '#/components/responses/Problem404'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
    delete:
      operationId: delete_contents
      summary: Delete contents
      description: |-
        Erase a record before it expires: the record, its screenshot, its raw HTML, its document images, its recognized page images and its stored replays. Later calls on the id answer `404`. A retry of the fetch with its idempotency key, within the key's 24 hours, answers `404` naming the deletion, never a second fetch. A job that points at the record keeps its `contents_id`, and that id answers `404`. A second delete is `404`.

        **What it costs.** The key needs `contents:delete`. The call is free. The answer is `204 No Content`.

        **Refused before any work.** An id of the wrong kind: `400 invalid-request`, before any lookup. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **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.
        - 404 `not-found`, Not found: an unknown or another account's record, or one already erased.
        - 410 `contents-expired`, The record has expired: for 30 days after it expired, to the owning account only; then `404`.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record to erase, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
      responses:
        '204':
          description: >-
            Erased; no body.
          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'}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '404': {$ref: '#/components/responses/Problem404'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/contents/{contents_id}/sections/{section_id}:
    get:
      operationId: get_section
      summary: Get section
      description: |-
        Read one section of a record, free: its text when it fits, its own text and the rows of its child sections when it does not, and a page of its text when a cut is needed.

        Give it the record's `cnt_` id and the section's `s` id from the map, `sections`, which a fetch returns when the text did not fit or when `max_characters` was `0`. `s0` is the text before the first heading; on a page without headings it is the whole document. Use `get_contents` for the whole record; use `list_blocks` for the blocks of a section by kind.

        **What it costs.** The key needs `contents:read`. The call is free.

        **What comes back.** `200` with `SectionContents`: first the record's id, address, fetch time, fingerprint, version and configuration, then its new `expires_at`, then the section's row, then its text in the formats asked for, or its child rows.
        - The section fits `max_characters`: its text comes whole in the formats asked; `truncated` is false; no `sections`.
        - It does not fit and has child sections: its own text before the first child comes, with `sections`, the child rows, on this first page only; `truncated` is true; no `next_page_token`, since each child is read by its own id.
        - It does not fit and has no children, or its own text alone does not fit: the text is cut at a block edge; `truncated` is true; `next_page_token` continues it.
        - One block larger than the bound: the text is cut inside the block, at a row, an item, a line or a sentence edge; `truncated` is true; `next_page_token` continues it.
        - `max_characters: 0`: the row and the child rows, no text; `truncated` is false.
        - `links` are the section's links, narrowed by `block_kinds`; they come under `0` too.
        - The token binds the other parameters; a change is `400 page-token-invalid`. It is alive as long as the record, and a page that carries `next_page_token` always has text.

        **Refused before any work.**
        - A value outside its set, `max_characters` between 1 and 999, a duplicate or an empty list: `400 invalid-request`, `not_allowed`, `bound` or `duplicate`, each with where it is.
        - An id of the wrong kind: `400 invalid-request`, before any lookup.
        - A token of another record, another section or another query: `400 page-token-invalid`.
        - A record that failed, was refused or needs a person: `409 record-without-content`, `change` naming `fetch_contents`.
        - An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `sections_cut`, `links_cut`, `field_not_applicable`, `version_retiring`, after the record's own notices.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 404 `not-found`, Not found, `change.field` saying `contents_id` or `section_id`.
        - 409 `record-without-content`, The record has no content.
        - 410 `contents-expired`, The record has expired.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
        - name: section_id
          in: path
          required: true
          description: >-
            The section, an `s` id of the view asked, as the map's rows name it; `s0` is the text before the first heading.
          schema:
            type: string
            pattern: '^s[0-9]+$'
          example: s2
        - name: max_characters
          in: query
          required: false
          description: >-
            The most text to return, in characters. `0` returns the section's row and its child rows, no text. Default 20,000; `0`, or 1,000 to 1,000,000; a value between 1 and 999 is refused `bound`.
          schema:
            type: integer
            minimum: 0
            maximum: 1000000
            default: 20000
        - name: scope
          in: query
          required: false
          description: >-
            Which view's ids and text: `main` or `whole_page`. Default the record's own.
          schema:
            $ref: '#/components/schemas/Scope'
        - name: formats
          in: query
          required: false
          style: form
          explode: true
          description: >-
            The formats to return, over this section, 1 to 5 of these, one value per repeated key: `markdown`, the text as one markdown string; `html`, as clean HTML; `doclang`, as DocLang, an XML that keeps each block with its place on the page, on a page or an HTML file only; `json`, as `Block` objects; `links`, the section's links with their kinds. Default `markdown`. An open set; a key sent with an empty value is an empty list, refused `bound`, and a repeated value is refused `duplicate`.
          schema:
            type: array
            minItems: 1
            maxItems: 5
            uniqueItems: true
            default: [markdown]
            items:
              type: string
              minLength: 1
              examples: [markdown, html, doclang, json, links]
              description: >-
                One of the formats the field lists.
        - name: block_kinds
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Keep only blocks of these kinds, over this section: 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`, an open set, one value per repeated key. Default: every kind.
          schema:
            type: array
            minItems: 1
            maxItems: 10
            uniqueItems: true
            items:
              type: string
              minLength: 1
              description: >-
                One of the block kinds the field lists.
        - name: page_token
          in: query
          required: false
          description: >-
            Continues a cut text, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, alive as long as the record. Default none.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            The section, `SectionContents`: the record's id and facts, the record's new `expires_at`, the section's row, its text in the formats asked for or its child rows, `truncated`, and `next_page_token` while a cut continues.
          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/json:
              schema:
                $ref: '#/components/schemas/SectionContents'
              examples:
                get_section.fits:
                  summary: A section whose text fits whole
                  value: {"contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "final_url": "https://example.com/q3", "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "version": "1.0.0", "configuration": "cfg-2026-11", "expires_at": "2026-11-06T08:40:12Z",
                    "section": {"id": "s2", "title": "Margin", "level": 2, "characters": 1810, "basis": "structure"}, "formats": ["markdown"], "markdown": "## Margin\n\n…", "truncated": false, "notices": [], "request_id": "req_01JgELUWGGDGlc96clfpJQ"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/contents/{contents_id}/blocks:
    get:
      operationId: list_blocks
      summary: List blocks
      description: |-
        List the blocks of a record, free: by kind, by section, by document page or by id, in document order, one page of results at a time.

        Give it the record's `cnt_` id and the filters you want; every filter you send must match. Each block is the record's own `Block`: its id, kind, section, size and text, a table as its rows and spans, an image as its address and size. `block_ids` reads the blocks a highlight names by `block_id`, so you can read the whole block around a match. Use `get_section` for a section's text in one piece; use `get_contents` for the whole record.

        **What it costs.** The key needs `contents:read`. The call is free.

        **What comes back.** `200` with `BlockPage`: the record's id and facts, the record's new `expires_at`, the blocks, and `next_page_token` while more remain.
        - A page of results ends before the block that would pass `max_characters`, or at `page_size` blocks, whichever comes first.
        - One block alone larger than `max_characters` comes whole, alone on its page, with the notice `block_over_limit`.
        - `highlight_ids` is empty on every block here; the fetch's highlights stand on the record.
        - No block matching: `200` with `[]`.
        - `page_size` is from 1, default 50, maximum 200; a larger value is lowered with the notice `page_size_lowered`, never refused.
        - `page_token` is bound to its query and its record and is alive as long as the record; `next_page_token` is absent on the last page, and a page that carries it has at least one block.

        **Refused before any work.**
        - A value outside its set or range, a duplicate or an empty list: `400 invalid-request`, `not_allowed`, `bound` or `duplicate`, each with where it is; `page_size` above its maximum is lowered instead.
        - `page_number` on a record without `pages`: `400 invalid-request`, `dependent`; above `pages.count`: `400 invalid-request`, `bound`.
        - `block_ids` with `start_block_id`: `400 invalid-request`, `exclusive`.
        - An id of the wrong kind: `400 invalid-request`, before any lookup.
        - A token of another record or another query: `400 page-token-invalid`.
        - A `section_id`, a `block_ids` value or a `start_block_id` the record does not hold: `404 not-found`, `change.field` naming it.
        - A record that failed, was refused or needs a person: `409 record-without-content`.
        - An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `block_over_limit`, `page_size_lowered`, `field_not_applicable`, `version_retiring`, after the record's own notices.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 404 `not-found`, Not found, `change.field` saying `contents_id`, `section_id`, `block_ids` or `start_block_id`.
        - 409 `record-without-content`, The record has no content.
        - 410 `contents-expired`, The record has expired.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
        - name: block_kinds
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Keep only blocks of these kinds: 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`, an open set, one value per repeated key. Default: every kind.
          schema:
            type: array
            minItems: 1
            maxItems: 10
            uniqueItems: true
            items:
              type: string
              minLength: 1
              examples: [table, text, heading, code, math, divider, interactive, image, embed, media]
              description: >-
                One of the block kinds the field lists.
        - name: section_id
          in: query
          required: false
          description: >-
            Keep only the blocks of this section and of the sections under it, an `s` id from the map. Default none.
          schema:
            type: string
            pattern: '^s[0-9]+$'
            examples: [s2]
        - name: page_number
          in: query
          required: false
          description: >-
            Keep only the blocks of this page of a document, from 1 to `pages.count`. Default none. On a record without `pages`, a web page, it is refused `dependent`; above `pages.count`, `bound`.
          schema:
            type: integer
            minimum: 1
        - name: block_ids
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Keep only these blocks, 1 to 50 `b` ids, one value per repeated key; the ids a highlight names. Default none. With `start_block_id` it is refused `exclusive`.
          schema:
            type: array
            minItems: 1
            maxItems: 50
            uniqueItems: true
            items:
              type: string
              pattern: '^b[0-9]+$'
              examples: [b7]
              description: >-
                One block id, as `b7`.
        - name: start_block_id
          in: query
          required: false
          description: >-
            Begin the page of results at this block, a `b` id, and read on from there in document order. Default none, the first block. With `block_ids` it is refused `exclusive`.
          schema:
            type: string
            pattern: '^b[0-9]+$'
        - name: scope
          in: query
          required: false
          description: >-
            Which view's blocks: `main` or `whole_page`. Default the record's own.
          schema:
            $ref: '#/components/schemas/Scope'
        - name: max_characters
          in: query
          required: false
          description: >-
            The most text on one page of results, in characters; the page ends before the block that would pass it. Default 20,000; 1,000 to 1,000,000.
          schema:
            type: integer
            minimum: 1000
            maximum: 1000000
            default: 20000
        - name: page_size
          in: query
          required: false
          description: >-
            At most this many blocks on a page of results, from 1. Default 50; the maximum, 200, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            The next page, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, alive as long as the record. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            One page of the record's blocks in document order, `BlockPage`, with the record's id and facts and the record's new `expires_at`; `next_page_token` while more remain.
          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/json:
              schema:
                $ref: '#/components/schemas/BlockPage'
              examples:
                list_blocks.first-page:
                  summary: The table blocks of a record, one of them
                  value: {"contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "final_url": "https://example.com/q3", "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "version": "1.0.0", "configuration": "cfg-2026-11", "expires_at": "2026-11-06T08:40:12Z",
                    "blocks": [{"id": "b7", "kind": "table", "section_id": "s2", "characters": 412, "links": [], "highlight_ids": [],
                      "table": {"caption": null, "rows": [["Quarter", "Margin"], ["Q3", "41.2%"]], "spans": [], "header_rows": [0], "header_columns": [], "basis": "structure"}}],
                    "notices": [], "request_id": "req_01J3WbmHqruHQMHIwlFrMB"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/contents/{contents_id}/links:
    get:
      operationId: list_links
      summary: List links
      description: |-
        List the links of a record, free: every link with its kind and the block and section that hold it, in document order, one page of results at a time, without the 1,000-link cap a fetch puts on `formats: links`.

        Give it the record's `cnt_` id and the filters you want; every filter you send must match. Use `fetch_contents` to read a linked page; use `list_blocks` for the blocks themselves.

        **What it costs.** The key needs `contents:read`. The call is free.

        **What comes back.** `200` with `LinkPage`: the record's id and facts, the record's new `expires_at`, the links, each with its kind and its place, and `next_page_token` while more remain.
        - The order is the document order of the blocks that hold the links.
        - `kind` is read from the address alone, a guess: no request is made for any link, so a link carries no size and no served type.
        - `external` compares the link's host with the final URL's registrable domain; a link without a host, `mail`, `phone` or `fragment`, is left out under either value of the filter.
        - No link matching: `200` with `[]`.
        - `page_size` is from 1, default 50, maximum 200; a larger value is lowered with the notice `page_size_lowered`, never refused.
        - `page_token` is bound to its query and its record and is alive as long as the record; `next_page_token` is absent on the last page, and a page that carries it has at least one link.

        **Refused before any work.**
        - A value outside its set or range, a duplicate or an empty list: `400 invalid-request`, `not_allowed`, `bound` or `duplicate`, each with where it is; `page_size` above its maximum is lowered instead.
        - An id of the wrong kind: `400 invalid-request`, before any lookup.
        - A token of another record or another query: `400 page-token-invalid`.
        - A `section_id` the record does not hold: `404 not-found`, `change.field` naming it.
        - A record that failed, was refused or needs a person: `409 record-without-content`.
        - An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `page_size_lowered`, `field_not_applicable`, `version_retiring`, after the record's own notices.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 404 `not-found`, Not found, `change.field` saying `contents_id` or `section_id`.
        - 409 `record-without-content`, The record has no content.
        - 410 `contents-expired`, The record has expired.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
        - name: link_kinds
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Keep only links of these kinds: 1 to 7 of `file`, a file such as a PDF; `page`, another page; `fragment`, a place inside the same page; `mail`, an email address; `phone`, a phone number; `feed`, an RSS or Atom feed; `other`, anything else. An open set, one value per repeated key. Default: every kind.
          schema:
            type: array
            minItems: 1
            maxItems: 7
            uniqueItems: true
            items:
              type: string
              minLength: 1
              examples: [file, page, fragment, mail, phone, feed, other]
              description: >-
                One of the link kinds the field lists.
        - name: external
          in: query
          required: false
          description: >-
            `true` keeps only links that leave the final URL's registrable domain; `false`, only those that stay. Default none, both. A link without a host is left out under either value.
          schema:
            type: boolean
        - name: section_id
          in: query
          required: false
          description: >-
            Keep only the links of this section and of the sections under it, an `s` id from the map. Default none.
          schema:
            type: string
            pattern: '^s[0-9]+$'
            examples: [s3]
        - name: scope
          in: query
          required: false
          description: >-
            Which view's links: `main` or `whole_page`. Default the record's own.
          schema:
            $ref: '#/components/schemas/Scope'
        - name: page_size
          in: query
          required: false
          description: >-
            At most this many links on a page of results, from 1. Default 50; the maximum, 200, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            The next page, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, alive as long as the record. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            One page of the record's links, `LinkPage`, each with its kind and its place, with the record's id and facts and the record's new `expires_at`; `next_page_token` while more remain.
          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/json:
              schema:
                $ref: '#/components/schemas/LinkPage'
              examples:
                list_links.first-page:
                  summary: The file links of a record, one of them
                  value: {"contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "final_url": "https://example.com/q3", "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "version": "1.0.0", "configuration": "cfg-2026-11", "expires_at": "2026-11-06T08:40:12Z",
                    "links": [{"url": "https://example.com/q3/report.pdf", "text": "Full report", "kind": "file", "external": false, "block_id": "b12", "section_id": "s3"}],
                    "notices": [], "request_id": "req_01Jp0SRsqpJGQ9hFdqVC27"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  '/v1/contents:upload':
    post:
      operationId: upload_contents
      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.

        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.
      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'}
  /v1/jobs:
    get:
      operationId: list_jobs
      summary: List jobs
      description: |-
        List the account's jobs, newest first, free. `state` and `kind` filter them, and every filter you send must match. A job started while you page may make an item repeat; when you merge pages, keep one entry per `id`.

        **What it costs.** The key needs `jobs:read`. The call is free. The answer is `200` with `JobPage`.

        **Paging.** `page_size` from 1, default 50, maximum 200, a larger value lowered with the notice `page_size_lowered`; `page_token` is opaque, bound to its query, alive 24 hours; `next_page_token` is absent on the last page, and a page that carries it holds at least one job. A changed filter between pages, `page_size` excepted, or an unknown, expired or another list's token, is `400 page-token-invalid`.

        **Refused before any work.** A value outside its set or range, `page_size` above its maximum excepted, which is lowered: `400 invalid-request`, `not_allowed` or `bound`, each with where it is. A token of another list: `400 page-token-invalid`. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `page_size_lowered`, in `JobPage.notices`; a `Job` carries no notices and no version, so no retirement notice is made here.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: state
          in: query
          required: false
          description: >-
            Only jobs in this state; `queued`, `running`, `completed`, `failed` or `canceled`, the last three final; an open set. Default none.
          schema:
            type: string
            minLength: 1
            examples: [completed, queued, running, failed, canceled]
        - name: kind
          in: query
          required: false
          description: >-
            Only jobs of this kind, `upload_contents`, an open set. Default none.
          schema:
            type: string
            minLength: 1
            examples: [upload_contents]
        - name: page_size
          in: query
          required: false
          description: >-
            At most this many jobs on the page, from 1; default 50; the maximum, 200, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            The next page, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, never built by the caller. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            One page of the account's jobs, newest first; `next_page_token` while more remain.
          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/json:
              schema:
                $ref: '#/components/schemas/JobPage'
              examples:
                list_jobs.first-page:
                  summary: The account's jobs, one completed job among them
                  value: {"jobs": [{"id": "job_8Rt2mqXKclxu58MCwLkSCV", "kind": "upload_contents", "state": "completed", "finished": true, "counts": {"parsed_count": 310, "failed_count": 2, "remaining_count": 0}, "cost": {"ceiling": {"amount": "1.0000", "currency": "USD"}, "actual": {"amount": "0.3300", "currency": "USD"}, "units": {"contents": 1, "document_pages": 310, "recognized_pages": 3}, "replayed": false}, "outcome": {"kind": "partial", "reason": "pages_failed"}, "contents_id": "cnt_f9a1LknFzePvIKv1pEkejs", "created_at": "2026-11-04T10:02:11Z", "updated_at": "2026-11-04T10:14:52Z", "expires_at": "2026-12-04T10:14:52Z", "request_id": "req_01RcyYPWPnGlycDKoB9AfI"}],
                    "notices": [], "request_id": "req_01RcyYPWPnGlycDKoB9AfI"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/jobs/{job_id}:
    get:
      operationId: get_job
      summary: Get job
      description: |-
        Read a job, or wait for it to finish, free. The answer comes at the final state or when `wait_seconds` ends, with the job as it stands; it is `200` when the job failed too, with the failure inside. `Retry-After` and `retry_after_seconds` come on every answer that is not final. Once `contents_id` is set, `get_contents` reads the record; `cancel_job` asks the job to stop.

        **What it costs.** The key needs `jobs:read`. The call is free. The answer is `200` with `Job`, never cached. A `HEAD` on this path is answered at once and does not wait.

        **Refused before any work.** A value outside its range: `400 invalid-request`, `bound`. An id of the wrong kind: `400 invalid-request`, before any lookup. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **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.
        - 404 `not-found`, Not found: an unknown or another account's job.
        - 410 `job-expired`, The job has expired: the job ended more than 30 days ago. The answer comes for 30 more days, to the owning account only, with `expired_at` and `change` naming `upload_contents`; then `404`.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: job_id
          in: path
          required: true
          description: >-
            The job, a `job_` id as `upload_contents` returned it.
          schema:
            type: string
            pattern: '^job_[A-Za-z0-9]{22}$'
          example: job_8Rt2mqXKclxu58MCwLkSCV
        - name: wait_seconds
          in: query
          required: false
          description: >-
            The most seconds to wait for the job to finish, 0 to 90; the answer comes at the final state or when the wait ends, with the current state. Default 0, no wait.
          schema:
            type: number
            minimum: 0
            maximum: 90
            default: 0
      responses:
        '200':
          description: >-
            The job in its current state; `Retry-After` and `retry_after_seconds` while it is not finished; once finished, its `outcome`, its `contents_id` or its `problem`, and its final `cost`.
          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/json:
              schema:
                $ref: '#/components/schemas/Job'
              examples:
                get_job.completed:
                  summary: A completed job whose record is partial, two pages having failed
                  value: {"id": "job_8Rt2mqXKclxu58MCwLkSCV", "kind": "upload_contents", "state": "completed", "finished": true,
                    "counts": {"parsed_count": 310, "failed_count": 2, "remaining_count": 0},
                    "cost": {"ceiling": {"amount": "1.0000", "currency": "USD"}, "actual": {"amount": "0.3300", "currency": "USD"}, "units": {"contents": 1, "document_pages": 310, "recognized_pages": 3}, "replayed": false},
                    "outcome": {"kind": "partial", "reason": "pages_failed"}, "contents_id": "cnt_f9a1LknFzePvIKv1pEkejs",
                    "created_at": "2026-11-04T10:02:11Z", "updated_at": "2026-11-04T10:14:52Z", "expires_at": "2026-12-04T10:14:52Z", "request_id": "req_01Qm89u0cStrgTL7bxmqKa"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '404': {$ref: '#/components/responses/Problem404'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  '/v1/jobs/{job_id}:cancel':
    post:
      operationId: cancel_job
      summary: Cancel job
      description: |-
        Ask a job to stop, free. The answer is `200` with the job as it stands; the work may finish before it stops, and `Retry-After` comes while it still runs, as on `get_job`. A job already final is unchanged. With pages already parsed the record is `partial`, `canceled`, the pages kept and billed; with none, no record and nothing billed.

        **What it costs.** The key needs `jobs:cancel`. The call is free. It takes no body; a body sent is refused `400 invalid-request`.

        **Refused before any work.** An id of the wrong kind: `400 invalid-request`, before any lookup. A body sent: `400 invalid-request`. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **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.
        - 404 `not-found`, Not found: an unknown or another account's job.
        - 410 `job-expired`, The job has expired: the job ended more than 30 days ago; the answer comes for 30 more days, to the owning account only, then `404`.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: job_id
          in: path
          required: true
          description: >-
            The job to stop, a `job_` id.
          schema:
            type: string
            pattern: '^job_[A-Za-z0-9]{22}$'
          example: job_3ZYgQAhOBQmM5xiilC8Fj9
      responses:
        '200':
          description: >-
            The job in its current state after the ask; `Retry-After` and `retry_after_seconds` while it still runs; once canceled, its `outcome` and `contents_id` when pages were done.
          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/json:
              schema:
                $ref: '#/components/schemas/Job'
              examples:
                cancel_job.canceled:
                  summary: A job canceled with 41 pages done, which are kept and billed
                  value: {"id": "job_3ZYgQAhOBQmM5xiilC8Fj9", "kind": "upload_contents", "state": "canceled", "finished": true,
                    "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},
                    "outcome": {"kind": "partial", "reason": "canceled"}, "contents_id": "cnt_3xiMwacMbgXiIanT2iBPcB",
                    "created_at": "2026-11-04T10:02:11Z", "updated_at": "2026-11-04T10:03:05Z", "expires_at": "2026-12-04T10:03:05Z", "request_id": "req_01Q2Eg6uJmHGdKZo83Xpje"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '404': {$ref: '#/components/responses/Problem404'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  '/v1/contents:batch':
    post:
      operationId: fetch_contents_batch
      summary: Fetch contents batch
      description: |-
        Fetch 1 to 20 pages or documents at their URLs in one call. You get one record per address, kept as a single fetch's is, with a tally first and the sum of the costs last.

        Give it the addresses as `items`, each with its own few fields, and at the top the fields every item shares. The results come in input order, each a record or the problem that skipped it. Nothing here is atomic: an item that fails or is skipped leaves the others standing. The batch is not a resource, so it has no id, no expiry and no `Location`; each record has its own. Use `fetch_contents` for one address; use `upload_contents` for a file you hold. A batch takes at most 20 addresses and no files.

        **What it costs.** The key needs `contents:fetch`, plus `contents:model` as on `fetch_contents`, decided over the top fields and every item before any work. The price is the sum of the records' costs, each priced as a fetch, with `units` summed by name. An item that was skipped, or whose record failed, was refused or needs a person, bills nothing.

        **What comes back.** `200` with `ContentsBatch`: `counts`, how the items ended; `results`, in input order; `cost`, the sum. Every record is kept 48 hours after its last call and at most 30 days.

        **The idempotency key.** `Idempotency-Key` is required here, since a repeated batch would fetch and bill every address twice; without it the call is `400 invalid-request` naming the header. The whole answer is stored when at least one record was billed, and the same key with the same body returns it again with this call's `request_id`, every record's `expires_at` as it stands and `replayed` true on every `cost`. 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.

        **The bounds.**
        - The body is at most 4 MiB, enough for 20 items with five 4,000-character highlights each in a script such as Chinese, where a character takes three bytes, JSON escaping included.
        - `max_characters` bounds each record's text as on a fetch. `max_total_characters` bounds the whole answer's text, links counted by their url and text: records take their text in input order while it fits in what remains, and a record that would pass it comes as `sections_only` with the notice `total_characters_cut`; `get_contents` returns that record's text free unless `retention` is `none`. A value below `max_characters` is allowed.
        - `screenshot` counts against neither bound and bills one `screenshots` unit per record that made one; `raw_html` counts against neither and is free.
        - `wait_seconds` is each item's own deadline from its own start. Items run in parallel up to the key's concurrency and the rest wait inside the call; the whole call ends at `bounds.contents.batch_seconds`, and an item not started by then is `skipped` with the problem `overloaded` and `retry_after_seconds` set, never `deadline`.

        **Money.** `max_cost` is the whole call's ceiling, reserved at the start in input order: each item its smallest call, one `contents`, a `baseline_fingerprint` item too, and the units it asks for by name, the model steps and the screenshot. An item's record carries the ceiling reserved for it as `cost.ceiling`. An item the remainder cannot cover for its smallest call is `skipped` with the problem of the limit that bound it: `cost-exceeds-cap` for this request's `max_cost`, `policy-limit-exceeded` for the key's cap, `credit-exhausted`, `run-budget-exhausted` or `key-budget-exhausted`. What remains of the ceiling is shared by the documents' pages, which spend it as they come; a document stops when it is spent, `partial`, `cost_capped`. Inside an item the extras are cut in the order `fetch_contents` gives, each with the notice `cost_cut`. `json_schema` and `summary` run per record, one model step per record per field.

        **Faults, and whose they are.**
        - The batch's own shape broken, a missing `url`, a bad or repeated `label`, a malformed `baseline_fingerprint`, a bound passed, a misplaced or unknown field: `422` for the whole call, each violation with its pointer, as `/items/3/url`.
        - A top field's rule broken: `422` for the whole call, as on `fetch_contents`.
        - One item's fault in its address, its domain or a legal demand: that item alone is `skipped`, its problem beside it, `invalid-field`, `destination-refused`, `policy-limit-exceeded` or `legal-block`, and the batch runs.
        - One item's fault learned from the fetch: that item's record carries the outcome.
        - The same URL twice: two fetches, two records.

        **Refused before any work**, every violation of the body reported at once in `violations`:
        - Fewer than 1 or more than 20 items: `invalid-field`, `bound`.
        - An item without `url`: `required`.
        - A `label` repeated: `duplicate`; one outside its character set or length: `syntax`, `bound`.
        - `url`, `label`, `highlights` or `baseline_fingerprint` at the top, or a top-only field inside an item: `misplaced`.
        - `max_total_characters` outside its range: `bound`.
        - Every rule of `fetch_contents` on the top fields and on an item's own fields, except the address's own rules, its scheme and userinfo, the destination and the domain policy, which skip that item alone as said above.
        - An unknown field, at the top or in an item: `unknown_field`.
        - `Idempotency-Key` absent: `400 invalid-request`.

        **Notices this operation makes.** Every notice of `fetch_contents`, inside each record; `total_characters_cut` on a record cut by the whole answer's bound.

        **Problem types.** For the whole call:
        - 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; `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.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.

        Inside a skipped item, each without `status`: `invalid-field`, `destination-refused`, `policy-limit-exceeded`, `legal-block`, `cost-exceeds-cap`, `credit-exhausted`, `run-budget-exhausted`, `key-budget-exhausted`, `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.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
        - $ref: '#/components/parameters/Traceparent'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchContentsBatchRequest'
            examples:
              fetch_contents_batch.mixed:
                summary: Three pages, the tables of each, one page checked against a fingerprint from an earlier fetch, one address refused
                value: {"items": [{"url": "https://a.example/report", "label": "a"}, {"url": "https://b.example/filing", "label": "b", "baseline_fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:"}, {"url": "http://10.0.0.7/admin", "label": "c"}],
                  "formats": ["json"], "block_kinds": ["table"], "max_total_characters": 60000, "max_cost": {"amount": "0.1000", "currency": "USD"}}
      responses:
        '200':
          description: >-
            The tally first, then one result per item in input order, each a record or a problem without `status`, then the sum of the records' costs.
          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/json:
              schema:
                $ref: '#/components/schemas/ContentsBatch'
              examples:
                fetch_contents_batch.mixed:
                  summary: Two records delivered, one unchanged against its fingerprint, and one item skipped for its address
                  value: {"counts": {"delivered": 2, "partial": 0, "failed": 0, "refused": 0, "needs_person": 0, "skipped": 1},
                    "results": [{"index": 0, "label": "a", "contents": {"id": "cnt_1aQXCj1gfV92qewVcOExbP", "outcome": {"kind": "delivered", "reason": "whole"}, "notices": [], "fetched_at": "2026-11-04T09:12:00Z", "fingerprint": "sha-256=:Nq4iU56FPWeajZrOTZ7lW1KHecsKmVU+O6hc5H0r3RE=:", "scope": "main", "record_scope": "main", "formats": ["json"], "truncated": false,
                        "blocks": [{"id": "b4", "kind": "table", "section_id": "s1", "characters": 58, "links": [], "highlight_ids": [], "table": {"caption": "Revenue by year", "rows": [["Year", "Revenue"], ["2024", "3.7 bn"], ["2025", "4.1 bn"]], "spans": [], "header_rows": [0], "header_columns": [], "basis": "structure"}}],
                        "counts": {"characters": 5120, "blocks": {"heading": 3, "text": 15, "table": 1}, "links": {"page": 6}}, "hidden_text": [], "left_out": [{"kind": "navigation", "characters": 900}],
                        "source": {"url": "https://a.example/report", "final_url": "https://a.example/report", "redirects": [], "status_code": 200, "media_type": "text/html", "carrier": "web", "access_kind": "open", "title": "Annual report", "authors": [], "published_date": "2026-03-02", "published_date_precision": "day", "published_date_basis": "structured_data", "modified_date": null, "publisher": "A Example", "canonical_url": null, "language": "en", "language_versions": [], "profile": {"kind": "company", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "robots": "allowed", "declared_terms": [], "structured_data": [], "origins": [], "visitor": {"country": "DE", "language": "de-DE,de;q=0.9", "network": "datacenter"}},
                        "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [], "elapsed_seconds": 5.8},
                        "cost": {"ceiling": {"amount": "0.0050", "currency": "USD"}, "actual": {"amount": "0.0050", "currency": "USD"}, "units": {"contents": 1}, "replayed": false},
                        "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-06T09:12:00Z", "request_id": "req_01Jx0V1CDhYS12ULqNUtDm"}},
                      {"index": 1, "label": "b", "contents": {"id": "cnt_2bLpzRvKxOEx0I72jKoQSw", "outcome": {"kind": "delivered", "reason": "unchanged"}, "notices": [], "fetched_at": "2026-11-04T09:12:00Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "record_scope": "main", "formats": [], "truncated": false,
                        "source": {"url": "https://b.example/filing", "final_url": "https://b.example/filing", "redirects": [], "status_code": 200, "media_type": "text/html", "carrier": "web", "access_kind": "open", "title": "Annual filing 2025", "authors": [], "published_date": "2026-02-14", "published_date_precision": "day", "published_date_basis": "meta_tag", "modified_date": null, "publisher": "B Example", "canonical_url": null, "language": "en", "language_versions": [], "profile": {"kind": "company", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "robots": "allowed", "declared_terms": [], "structured_data": [], "origins": [], "visitor": {"country": "DE", "language": "de-DE,de;q=0.9", "network": "datacenter"}},
                        "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [], "elapsed_seconds": 6.1},
                        "cost": {"ceiling": {"amount": "0.0050", "currency": "USD"}, "actual": {"amount": "0.0050", "currency": "USD"}, "units": {"contents": 1}, "replayed": false},
                        "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-06T09:12:01Z", "request_id": "req_01Jx0V1CDhYS12ULqNUtDm"}},
                      {"index": 2, "label": "c", "problem": {"type": "https://api.getclean.ai/problems/destination-refused", "title": "The destination is refused", "detail": "The address is not globally reachable.", "instance": "https://api.getclean.ai/requests/req_01Jx0V1CDhYS12ULqNUtDm/items/2", "request_id": "req_01Jx0V1CDhYS12ULqNUtDm", "who_must_act": "caller", "retryable": false}}],
                    "cost": {"ceiling": {"amount": "0.1000", "currency": "USD"}, "actual": {"amount": "0.0100", "currency": "USD"}, "units": {"contents": 2}, "replayed": false},
                    "request_id": "req_01Jx0V1CDhYS12ULqNUtDm"}
        '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'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  '/v1/contents/{contents_id}:highlight':
    post:
      operationId: highlight_contents
      summary: Highlight contents
      description: |-
        Find words or questions in a record you already have and mark where they stand, without fetching again. You get each place with its section and block ids, and, when you ask for text, the sections that hold them, marked. A string found verbatim is free; one a model has to judge costs one model step, once per call however many strings needed it.

        **What it costs.** The key needs `contents:read`, and `contents:model` unless `deterministic_only` is true, since a string may need a model. Free when every string was found verbatim; 1 `model_steps` when any string had to be judged, once per call. The answer is `200` with `ContentsHighlights`; the call moves the record's `expires_at` 48 hours ahead.

        **The idempotency key.** `Idempotency-Key` is optional here. A billed answer is stored 24 hours and replayed under the same key and body with this call's `request_id` and `replayed` true on `cost`; a free answer is not stored; the same key in flight is `409 idempotency-key-in-flight`; the same key with another body `422 idempotency-key-reused`.

        **Each string.** Found `exact` when its words stand in one block, after Unicode normalization and whitespace collapse, case kept; `near` when they stand there after case folding, with ellipses and the punctuation at the ends of words removed, pieces in order, the dotted and dotless i of Turkic scripts folded to one; `judged` when not found verbatim and a model picked the blocks that bear on it; not found, and nothing bears on it, or `deterministic_only`: the notice `highlight_not_found`, one per string. Every occurrence is a highlight, in document order, at most 50, past which the notice `highlights_cut` comes.

        **What comes back.** `max_characters: 0`: the `highlights` list with ids and places, no text, `formats` echoed `[]`. Above `0`: the sections holding highlights, in document order while they fit; a section larger than what remains comes cut at a block edge with its highlighted blocks inside; `truncated` true when the text returned is not the whole content, false when the holding sections are the whole and fit or when nothing was found; the rest through `get_section` or `list_blocks` with `block_ids`. The marks are `<mark id="h1">…</mark>` in `markdown` and `html` and `highlight_ids` on `blocks`; the record's own text never changes.

        **Verbatim only.** Under `deterministic_only`, a key whose policy forbids model work, or a ceiling below a model step, the strings are matched verbatim only; this operation is never refused for the key's policy or the ceiling, an explicit `deterministic_only: false` under such a key excepted, `policy-limit-exceeded` as on the fetch; under a ceiling below the step the miss carries the notice `cost_cut` or `budget_cut` naming `highlights`. A model step that fails or passes its bound, `bounds.contents.model_step_seconds`, answers `200` with the verbatim results and the notice `step_failed`, not billed. `scope: whole_page` on a document record, or `block_kinds` that match no block, is the notice `field_not_applicable`; with no block to search nothing is found, nothing is judged, nothing billed.

        **Refused before any work.** `doclang`, `links`, `screenshot` or `raw_html` in `formats`, or a value outside its set: `invalid-field`, `not_allowed`. `highlights` missing: `required`; an empty list: `bound`; a duplicate: `duplicate`. `max_characters` between 1 and 999, or any other bound passed: `bound`. An unknown field: `unknown_field`. A record that failed, was refused or needs a person: `409 record-without-content`, `change` naming `fetch_contents`. Every violation of the body is reported at once in `violations`.

        **Notices this operation makes.** The record's own notices first, then `highlight_not_found`, `highlights_cut`, `step_failed`, `cost_cut`, `budget_cut`, `default_set_by_policy`, `field_not_applicable`, `version_retiring`.

        **Problem types.** Never a money problem: when the money does not cover the model step, the strings are matched verbatim instead.
        - 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.
        - 404 `not-found`, Not found.
        - 409 `record-without-content`, The record has no content; `idempotency-key-in-flight`, The same request is still running.
        - 410 `contents-expired`, The record has expired.
        - 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; `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.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HighlightContentsRequest'
            examples:
              highlight_contents.found:
                summary: Two strings, the places only
                value: {"highlights": ["Revenue rose 12%", "dividend policy"], "max_characters": 0}
      responses:
        '200':
          description: >-
            The highlights found with their places, the holding sections marked when text was asked, the execution and the cost; a string not found is a notice, never an error.
          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/json:
              schema:
                $ref: '#/components/schemas/ContentsHighlights'
              examples:
                highlight_contents.found:
                  summary: One string found verbatim, one judged and not found, the step billed once
                  value: {"contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "final_url": "https://example.com/q3", "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "version": "1.0.0", "configuration": "cfg-2026-11", "expires_at": "2026-11-06T08:40:12Z",
                    "highlights": [{"id": "h1", "query_index": 0, "text": "Revenue rose 12%", "basis": "exact", "section_id": "s1", "block_id": "b3"}],
                    "formats": [], "truncated": false,
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "highlights", "version": "hl-2026-10"}], "elapsed_seconds": 1.4},
                    "cost": {"ceiling": {"amount": "0.0020", "currency": "USD"}, "actual": {"amount": "0.0020", "currency": "USD"}, "units": {"model_steps": 1}, "replayed": false},
                    "notices": [{"code": "highlight_not_found", "message": "No block bears on the string.", "field": "highlights", "pointer": "/highlights/1"}], "request_id": "req_01JIuousU3aZV7sHAB3vEy"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '413': {$ref: '#/components/responses/Problem413'}
        '415': {$ref: '#/components/responses/Problem415'}
        '422': {$ref: '#/components/responses/Problem422'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  '/v1/contents/{contents_id}:fill':
    post:
      operationId: fill_schema
      summary: Fill schema
      description: |-
        Fill your JSON Schema from a record you already have. You get a value only where the record states it, never a plausible one, with the place and the cited words for each property, and `empty`, `absent` or `unread` where the record says nothing. It is the same step as `fetch_contents`'s `json_schema`, run on the copy getclean keeps.

        **What it costs.** The key needs `contents:model`. The price is 1 `model_steps`. The answer is `200` with `SchemaFill`; the call moves the record's `expires_at` 48 hours ahead.

        **The idempotency key.** `Idempotency-Key` is optional here. The billed answer is stored 24 hours and replayed under the same key and body with this call's `request_id` and `replayed` true on `cost`; the same key in flight is `409 idempotency-key-in-flight`; the same key with another body `422 idempotency-key-reused`.

        **The fill.** `schema_statuses` is keyed by JSON Pointer, one per property, with `text` the cited words and the place. `absent` means the content kept under `scope` says nothing; `unread` means the place may lie in parts not parsed, not recognized or past a cap, so absence cannot be claimed; an agent that meets `absent` beside a non-empty `left_out` may retry under `scope: whole_page`. `schema_values` carries no link and no image markup; a URL value is kept only when it stands in the record's links or text, otherwise removed with the notice `model_link_removed`. The step is the whole call: a step that gave a bad answer is `502 gateway-error`, a step that passed `bounds.contents.model_step_seconds` is `504 gateway-timeout`, each `retryable` true and not billed. `scope: whole_page` on a document record, or `block_kinds` that match no block, is the notice `field_not_applicable`; with no block to read every status is `absent` and the step is not billed.

        **Refused before any work.** `json_schema` missing: `invalid-field`, `required`. A schema that is not valid JSON Schema 2020-12: `syntax`; one whose root is not `type: object`, that has no `properties`, or whose `pattern` needs backtracking: `not_allowed`. A value outside its set: `not_allowed`; a bound passed: `bound`; an unknown field: `unknown_field`. A key whose policy forbids model work, or whose cap is below a model step: `403 policy-limit-exceeded`. A record that failed, was refused or needs a person: `409 record-without-content`. Every violation of the body is reported at once in `violations`.

        **Notices this operation makes.** The record's own notices first, then `model_link_removed`, `field_not_applicable`, `version_retiring`.

        **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.
        - 409 `record-without-content`, The record has no content; `idempotency-key-in-flight`, The same request is still running.
        - 410 `contents-expired`, The record has expired.
        - 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; `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.
        - 500 `internal-error`, The service failed.
        - 502 `gateway-error`, A step behind the service failed: the model step gave a bad answer; nothing was billed, and a retry may work.
        - 503 `overloaded`, The service is overloaded.
        - 504 `gateway-timeout`, A step behind the service timed out: the model step passed its time bound; nothing was billed, and a retry may work.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillSchemaRequest'
            examples:
              fill_schema.filled:
                summary: Two properties to fill
                value: {"json_schema": {"type": "object", "properties": {"revenue_growth": {"type": "string"}, "dividend": {"type": "string"}}}}
      responses:
        '200':
          description: >-
            The values filled, one status per property with its place and cited words, the execution and the cost.
          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/json:
              schema:
                $ref: '#/components/schemas/SchemaFill'
              examples:
                fill_schema.filled:
                  summary: One property found with its cited words, one absent from the record
                  value: {"contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "final_url": "https://example.com/q3", "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "version": "1.0.0", "configuration": "cfg-2026-11", "expires_at": "2026-11-06T08:40:12Z",
                    "schema_values": {"revenue_growth": "12%"},
                    "schema_statuses": {"/revenue_growth": {"status": "found", "text": "Revenue rose 12% to EUR 4.1 bn", "section_id": "s1", "block_id": "b3"}, "/dividend": {"status": "absent"}},
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "json_schema", "version": "fill-2026-10"}], "elapsed_seconds": 2.3},
                    "cost": {"ceiling": {"amount": "0.0020", "currency": "USD"}, "actual": {"amount": "0.0020", "currency": "USD"}, "units": {"model_steps": 1}, "replayed": false}, "notices": [], "request_id": "req_01Jkf30AHpVn2m9UKIRfWE"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '413': {$ref: '#/components/responses/Problem413'}
        '415': {$ref: '#/components/responses/Problem415'}
        '422': {$ref: '#/components/responses/Problem422'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '502': {$ref: '#/components/responses/Problem502'}
        '503': {$ref: '#/components/responses/Problem503'}
        '504': {$ref: '#/components/responses/Problem504'}
  '/v1/contents/{contents_id}:summarize':
    post:
      operationId: summarize_contents
      summary: Summarize contents
      description: |-
        Have a model write a summary of a record you already have, at most 1,500 characters in the content's language, from the copy getclean keeps. It is the same step as `fetch_contents`'s `summary`. Use `highlight_contents` to find words and `fill_schema` to fill fields.

        **What it costs.** The key needs `contents:model`. The price is 1 `model_steps`. The answer is `200` with `ContentsSummary`; the call moves the record's `expires_at` 48 hours ahead.

        **The idempotency key.** `Idempotency-Key` is optional here. The billed answer is stored 24 hours and replayed under the same key and body with this call's `request_id` and `replayed` true on `cost`; the same key in flight is `409 idempotency-key-in-flight`; the same key with another body `422 idempotency-key-reused`.

        **The summary.** At most 1,500 characters, in the content's language; no link and no image markup, any the model writes removed with the notice `model_link_removed`. The step is the whole call: a step that gave a bad answer is `502 gateway-error`, a step that passed `bounds.contents.model_step_seconds` is `504 gateway-timeout`, each `retryable` true and not billed. `scope: whole_page` on a document record, or `block_kinds` that match no block, is the notice `field_not_applicable`; with no block to read the summary is an empty string and the step is not billed.

        **Refused before any work.** A value outside its set: `invalid-field`, `not_allowed`; a bound passed: `bound`; an unknown field: `unknown_field`. A key whose policy forbids model work, or whose cap is below a model step: `403 policy-limit-exceeded`. A record that failed, was refused or needs a person: `409 record-without-content`. Every violation of the body is reported at once in `violations`.

        **Notices this operation makes.** The record's own notices first, then `model_link_removed`, `field_not_applicable`, `version_retiring`.

        **Problem types.** The same as `fill_schema`.
        - 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.
        - 409 `record-without-content`, The record has no content; `idempotency-key-in-flight`, The same request is still running.
        - 410 `contents-expired`, The record has expired.
        - 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; `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.
        - 500 `internal-error`, The service failed.
        - 502 `gateway-error`, A step behind the service failed: the model step gave a bad answer; nothing was billed, and a retry may work.
        - 503 `overloaded`, The service is overloaded.
        - 504 `gateway-timeout`, A step behind the service timed out: the model step passed its time bound; nothing was billed, and a retry may work.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_3Fk9abaUhNX7t2eKkgfd3e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummarizeContentsRequest'
            examples:
              summarize_contents.summary:
                summary: The whole record summarized, no field set
                value: {}
      responses:
        '200':
          description: >-
            The summary, the execution and the cost.
          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/json:
              schema:
                $ref: '#/components/schemas/ContentsSummary'
              examples:
                summarize_contents.summary:
                  summary: A summary written from a record you already have
                  value: {"contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e", "final_url": "https://example.com/q3", "fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "scope": "main", "version": "1.0.0", "configuration": "cfg-2026-11", "expires_at": "2026-11-06T08:40:12Z",
                    "summary": "Revenue rose 12% in the quarter, driven by volume in Europe; margin expanded on lower input costs and mix; guidance was raised.", "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "summary", "version": "sum-2026-10"}], "elapsed_seconds": 1.9},
                    "cost": {"ceiling": {"amount": "0.0020", "currency": "USD"}, "actual": {"amount": "0.0020", "currency": "USD"}, "units": {"model_steps": 1}, "replayed": false}, "notices": [], "request_id": "req_01Js1UX1k8Axr2vRanQO5u"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '413': {$ref: '#/components/responses/Problem413'}
        '415': {$ref: '#/components/responses/Problem415'}
        '422': {$ref: '#/components/responses/Problem422'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '502': {$ref: '#/components/responses/Problem502'}
        '503': {$ref: '#/components/responses/Problem503'}
        '504': {$ref: '#/components/responses/Problem504'}
  '/v1/contents/{contents_id}:compare':
    post:
      operationId: compare_contents
      summary: Compare contents
      description: |-
        Compare a record you already have with a baseline, block by block and cell by cell, without a model, free. You get whether anything changed, a tally, and each change with both of its sides. The baseline is another record, `baseline_contents_id`, or the markdown you kept yourself as a record returned it, `baseline_markdown` with its `baseline_fingerprint`. It is a `POST` with a body that bills nothing and changes nothing but the record's `expires_at`, so it is safe to repeat.

        **What it costs.** The key needs `contents:read`. The call is free. The answer is `200` with `Comparison`; the call moves the current record's `expires_at` 48 hours ahead. The body is at most 8 MiB, so that a baseline of 1,000,000 characters fits in any script.

        **The comparison.**
        - A baseline you kept yourself is checked first: the sha-256 of the text, after the same normalization as the fingerprint, must equal `baseline_fingerprint`, else `422 invalid-field`, `syntax`, naming `baseline_fingerprint`. The text is split into blocks by the rules that made it, `baseline.verified` is true, and the `before` sides carry text without ids.
        - Both sides must share one `execution.version` and one `record_scope`, else `422 records-incomparable` with `change` naming which. A difference in the kind of source or the configuration is the notice `fingerprint_incomparable`, and the comparison runs. A baseline you kept names its version and scope in `baseline_version` and `baseline_scope`, or takes the current record's.
        - The unit is the block. Text is compared after Unicode normalization with the formatting marks removed; tables cell by cell; no model.
        - `changed` blocks are paired in order when they are alike above a published similarity; `moved` is the same text at another position in the block order; `added` and `removed` are the rest, removed blocks at the place they held. A page number differing alone is no change, and a paragraph that runs across a page break is one block.
        - `changed` true with `changes` `[]` means only inline formatting moved. The same id on both sides is `changed` false with `changes` `[]`.
        - Two records of different URLs or documents are allowed; you know what you compare. `paywall_declared` is repeated when either side carries it.

        **Paging.** `changes` is paged, `counts` the whole tally on every page before the rows; `page_size` from 1, default 50, maximum 200, a larger value lowered with the notice `page_size_lowered`; `page_token` binds the body's other fields, `page_size` included; a token of another comparison, or of this one with another body, is `400 page-token-invalid`.

        **Refused before any work.** `baseline_contents_id` and `baseline_markdown` both present: `invalid-field`, `exclusive`; neither: `required`; `baseline_markdown` without `baseline_fingerprint` or the reverse: `dependent`; `baseline_version` or `baseline_scope` with `baseline_contents_id`: `dependent`. The text does not hash to `baseline_fingerprint`: `invalid-field`, `syntax`. A bound passed, `page_size` above its maximum excepted, which is lowered: `bound`; an unknown field: `unknown_field`. Another version or scope: `422 records-incomparable`, `change.field` naming `baseline_version` or `baseline_scope`, `baseline_contents_id` for a baseline that is a record. Either record without content: `409 record-without-content`, `change.field` naming the side. A token of another comparison, or of this one with another body: `400 page-token-invalid`. An id of the wrong kind: `400 invalid-request`. Every violation of the body is reported at once in `violations`.

        **Notices this operation makes.** `fingerprint_incomparable`, `paywall_declared`, `page_size_lowered`, `version_retiring`.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 404 `not-found`, Not found, `change.field` saying which id.
        - 409 `record-without-content`, The record has no content.
        - 410 `contents-expired`, The record has expired, `detail` naming which record.
        - 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; `records-incomparable`, The records cannot be compared.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: contents_id
          in: path
          required: true
          description: >-
            The current record, a `cnt_` id.
          schema:
            type: string
            pattern: '^cnt_[A-Za-z0-9]{22}$'
          example: cnt_9Zze6X8RDFg2XxyKyLlV5T
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompareContentsRequest'
            examples:
              compare_contents.changed:
                summary: The current record against an earlier record as its baseline
                value: {"baseline_contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e"}
      responses:
        '200':
          description: >-
            Both sides with their fingerprints, whether anything changed, the tally, and the changes block by block, paged.
          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/json:
              schema:
                $ref: '#/components/schemas/Comparison'
              examples:
                compare_contents.changed:
                  summary: One table cell changed between two fetches of the same page a week apart
                  value: {"contents_id": "cnt_9Zze6X8RDFg2XxyKyLlV5T", "expires_at": "2026-11-13T08:40:02Z", "baseline_contents_id": "cnt_3Fk9abaUhNX7t2eKkgfd3e",
                    "current": {"fetched_at": "2026-11-11T08:40:02Z", "fingerprint": "sha-256=:Rt11HNu+jiwX5K846APgS7Sri/ToHiTmp+MxA8fDhrM=:", "verified": true}, "baseline": {"fetched_at": "2026-11-04T08:40:12Z", "fingerprint": "sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:", "verified": true},
                    "changed": true, "counts": {"added": 0, "removed": 0, "changed": 1, "moved": 0},
                    "changes": [{"kind": "changed", "block_kind": "table", "before": {"section_id": "s2", "block_id": "b7", "text": "| Q3 | 41.2% |"}, "after": {"section_id": "s2", "block_id": "b7", "text": "| Q3 | 41.6% |"},
                      "cells": [{"row": 1, "column": 1, "before_text": "41.2%", "after_text": "41.6%"}]}],
                    "notices": [], "request_id": "req_01JONfNiPNrnysSRQjsH2k"}
        '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'}
        '410': {$ref: '#/components/responses/Problem410'}
        '413': {$ref: '#/components/responses/Problem413'}
        '415': {$ref: '#/components/responses/Problem415'}
        '422': {$ref: '#/components/responses/Problem422'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/limits:
    get:
      operationId: get_limits
      summary: Get limits
      description: |-
        Read your key's limits and your account's money in one answer, free, before a batch or any call that must fit a budget. You get the prepaid balance after the sums reserved by calls in flight, the use of the current period, every unit's price, the key's cap on one call and its budgets, its rate and the calls allowed in flight at once, the published bounds of both families, the document types taken, the countries getclean can read from, the recognition languages, the archives, the key's policy, and the versions served with the current one. There is no estimate operation: `max_cost` is the protection, and `prices` gives every unit's price.

        **What it costs.** The key needs `limits:read`. The call is free. The answer is `200` with `Limits`, never cached, since it is the key's own.

        **Refused before any work.** An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **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.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
      responses:
        '200':
          description: >-
            The key's limits and the account's money, as they stand at this call.
          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/json:
              schema:
                $ref: '#/components/schemas/Limits'
              examples:
                get_limits.limits:
                  summary: A key's limits on an account with credit left
                  value: {"balance": {"amount": "42.1000", "currency": "USD"},
                    "usage": {"starts_at": "2026-11-01T00:00:00Z", "ends_at": "2026-12-01T00:00:00Z", "units": {"contents": 1840, "model_steps": 212, "searches": 96}, "spent": {"amount": "17.9000", "currency": "USD"}},
                    "prices": {"contents": {"amount": "0.0050", "currency": "USD"}, "model_steps": {"amount": "0.0020", "currency": "USD"}, "screenshots": {"amount": "0.0010", "currency": "USD"}, "document_pages": {"amount": "0.0010", "currency": "USD"}, "recognized_pages": {"amount": "0.0050", "currency": "USD"}, "searches": {"amount": "0.0100", "currency": "USD"}, "datasource_queries": {"amount": "0.0010", "currency": "USD"}},
                    "caps": {"call_cap": {"amount": "0.0500", "currency": "USD"}},
                    "rates": {"requests_per_minute": 600, "concurrency": 20, "resets_at": "2026-11-05T09:01:00Z"},
                    "bounds": {"contents": {"max_characters": {"min": 0, "max": 1000000, "default_value": 20000, "excluded_min": 1, "excluded_max": 999}, "list_blocks.max_characters": {"min": 1000, "max": 1000000, "default_value": 20000}, "max_total_characters": {"min": 1000, "max": 2000000, "default_value": 200000}, "wait_seconds": {"min": 5, "max": 90, "default_value": 30}, "get_job.wait_seconds": {"min": 0, "max": 90, "default_value": 0}, "page_size": {"min": 1, "max": 200, "default_value": 50}, "items": {"min": 1, "max": 20}, "highlights": {"min": 1, "max": 5}, "recognition_languages": {"min": 1, "max": 10},
                        "call_seconds": {"max": 110}, "batch_seconds": {"max": 600}, "queue_seconds": {"max": 30}, "model_step_seconds": {"max": 20}, "screenshot_seconds": {"max": 15}, "screenshot_bytes": {"max": 20000000}, "job_seconds": {"max": 1800}, "read_seconds": {"max": 10}, "page_bytes": {"max": 20000000}, "document_bytes": {"max": 104857600}, "document_base64_bytes": {"max": 20971520}, "document_pages": {"max": 2000}, "document_page_characters": {"default_value": 5000}, "body_bytes": {"max": 256000}, "batch_body_bytes": {"max": 4194304}, "compare_body_bytes": {"max": 8388608}, "redirects": {"max": 10}, "links": {"max": 1000}, "section_rows": {"max": 200}, "highlight_occurrences": {"max": 50}, "summary_characters": {"max": 1500}, "structured_data_bytes": {"max": 64000}, "recognition_confidence_min": {"min": 0.6}, "version_notice_days": {"default_value": 90}},
                      "search": {"max_candidates": {"min": 1, "max": 50, "default_value": 10}, "max_per_datasource": {"min": 1, "max": 100, "default_value": 10}, "max_excerpt_characters": {"min": 0, "max": 4000, "default_value": 600}, "max_total_characters": {"min": 1000, "max": 200000, "default_value": 40000}, "wait_seconds": {"min": 0.2, "max": 60, "default_value": 10}, "get_search.page_size": {"min": 1, "max": 50}, "list_datasources.page_size": {"min": 1, "max": 200, "default_value": 50}, "items": {"min": 1, "max": 20}, "datasources": {"min": 1, "max": 10}, "alternate_queries": {"min": 1, "max": 10}, "call_seconds": {"max": 60}, "batch_seconds": {"max": 300}, "queue_seconds": {"max": 30}, "model_step_seconds": {"max": 20}, "body_bytes": {"max": 256000}, "batch_body_bytes": {"max": 4194304}}},
                    "document_media_types": ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/msword", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/vnd.oasis.opendocument.text", "application/epub+zip", "application/rtf", "text/markdown", "text/csv", "text/html", "application/xhtml+xml", "application/xml", "application/json", "application/yaml", "text/plain", "image/png", "image/jpeg", "image/tiff", "image/webp", "image/heic"],
                    "exits": ["DE", "FR", "GB", "US"], "recognition_languages": ["en", "de", "fr", "es", "it", "nl", "pt", "tr"], "archives": ["Wayback Machine"], "default_exit": "DE",
                    "policy": {"deterministic_only": false, "safe_search": "moderate", "retention": "hold", "allowed_domains": [], "blocked_domains": [], "refuse_credential_urls": false},
                    "versions": [{"version": "1.0.0", "released_at": "2026-10-01T00:00:00Z", "changes_url": "https://api.getclean.ai/versions/1.0.0"}], "current_version": "1.0.0", "version_minimum_days": 90,
                    "request_id": "req_01ZWyyr8KwLQuLkEAedYvD"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/search:
    post:
      operationId: search
      summary: Search
      description: |-
        Search up to ten datasources with one question, in up to twenty wordings, and get one ranked list of results with the facts of each and a receipt of what ran where, before any page is read. Each result is a lead, the one page shown for a group of copies. The search is kept as a record, so its full list is read again free, and every cut, skip or change is named in the answer. Use `contents` to fetch the top leads in the same call, `fetch_contents` to read one by its URL, and `list_datasources` to see what can be searched.

        **What it costs.** The key needs `search:run`, which covers everything a search does, the inline fetches and their model fields included, under the key's policy. The price is 1 `searches`, plus 1 `datasource_queries` per source per wording that ran, plus 1 `model_steps` for the ranking and 1 for the choice of sources when they ran, plus the inline fetches priced as `fetch_contents`; a ranking cut by the deadline is not billed. The answer is `201 Created` with `Location` naming the record, `Search`. The record is kept 48 hours after its last call and at most 30 days from its making; `get_search` pages the list the search stored and never searches again or charges. A search answers within `wait_seconds`; what did not finish is named in a `partial` outcome. There is no job, no stream and no webhook.

        **The idempotency key.** `Idempotency-Key` is optional here. 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`, no second charge; the same key in flight is `409 idempotency-key-in-flight`; the same key with another body `422 idempotency-key-reused`.

        **The default call**, `{"query": "…"}`: the web plus the groups a model picks; ten results from each source per wording; ranked by a model; ten leads with 600-character excerpts and their publisher profiles; moderate safe search; ten seconds; the full record; the key's default run. Two model steps run by default, the ranking and the choice of sources when none are named, and a third identifies the publisher of a site getclean has not seen before; `deterministic_only` turns all three off.

        **Languages.** A wording runs only on a source that covers its language. The web source takes every wording, each in its own language, searched from `subject_country`; a source in one language takes only wordings in that language; a source with one index per language takes each wording in its own index. A wording no source covers is a coverage gap, with the hint to add a wording in the source's language. `languages` restricts the pages returned and is independent of this. Nothing is translated. With `subject_identifiers` and no `query`, each identifier's value runs as a wording with origin `identifier`.

        **The inline fetch.** `contents.top` of the leads are fetched in the same call, each as a contents record under `fetch_contents`'s rules.
        - It takes the search's `as_of_date`, `pinned_version`, `run_id`, `deterministic_only`, `retention` and `max_source_price`, and its `subject_country` when that is a country getclean can read from, else the key's `default_exit` with the notice `field_not_applicable`.
        - A lead found through a registered datasource is fetched under that datasource's login, the one way to use a login on a fetch.
        - Its time comes out of the search's `wait_seconds`, and it runs under what remains of the search's ceiling at its turn. Each inline record carries its own `cost`.
        - At the deadline the record follows the contents' rules. A fetch not started by the deadline makes no record, and the search ends `partial`, `fetches_missing`, with the notice `fetch_not_finished`.
        - `contents.max_characters` bounds one page. `max_total_characters` bounds the whole answer's text, excerpts and fetched pages together: the excerpts first, cut from the last lead backwards when they alone pass it, then the fetched pages in rank order while they fit in what remains; a page that would pass it comes as `sections_only`; each cut makes the notice `total_characters_cut`.

        **Money.** The ceiling is the lowest of the request's `max_cost`, the key's cap, the run's budget, the key's budget and the balance. When it cannot cover everything, the extras are cut in this order, each with the notice `cost_cut`: first each inline fetch's own extras, in the order `fetch_contents` gives; then whole fetches, the search ending `partial`, `fetches_missing`; then the ranking, `partial`, `rerank_missing`; then the choice of sources; then the results taken per source. `max_source_price` is the most you allow for a datasource that charges per query, or for a site an inline fetch meets that asks a price; a source whose fee passes it is not searched, the coverage gap `over_price`. getclean pays no site for a page, so a page that asks a price ends `payment_required`.

        **Said, never refused.** A hard filter a source cannot apply and cannot emulate: that source skipped, in `coverage_gaps`, the filter named. A wording in a language no source covers: `coverage_gaps`. `source_independence`, or `independent` in `ranking_priorities`, with no subject resolved: notice `field_not_applicable`. A window later than `as_of_date`, or a per-site cap on one allowed site: a notice. `datasources` absent under `deterministic_only`: the receipt shows `web` only. The inline fetch's `subject_country` not in `Limits.exits`: notice `field_not_applicable`, the key's `default_exit` used. `max_source_price` below a datasource's fee: that source skipped, coverage gap `over_price`. An `issuer` sent with a scheme that takes none: notice `field_not_applicable`, the identifier runs by its `scheme` and `value`.

        **Fields that read alike.** `allowed_domains` names sites that count, names with dots; `datasources` names places to search, names without. `allowed_domains` is hard, only these; `ranking_preferred_domains` is soft, these first and the rest still count. `subject_country` is where the search is made from; `languages` is what the pages are written in. `published_from` is the page's own date; `as_of_date` the source's state on a past day. `pinned_version` is getclean's version; `as_of_date` the sources' day. `purpose` is why, for the record and every model step; `ranking_instructions` is how to rank. `ranking_priorities` says which source facts go first; `ranking_order` how the rest is ordered. `source_kinds` is a filter that removes; `ranking_priorities: official` a preference that reorders. `max_per_datasource` is taken from each source before merging; `ranking_max_per_domain` is kept from each site in the answer. `max_candidates` is how many leads; `contents.top` how many of them to fetch. `max_excerpt_characters` is per lead, `max_total_characters` the whole answer, `contents.max_characters` one page fetched. Leaving the model fields out still runs the ranking and the choice of sources; `deterministic_only` turns every judging step off. `view` is how much of the record comes back; `record_form` the form the record is written in.

        **Refused before any work**, every violation of the body reported at once in `violations`:
        - Neither `query` nor `subject_identifiers`: `invalid-field`, `required`.
        - `alternate_queries` without `query`: `dependent`.
        - A scheme that needs an issuer, without one: `dependent`; an `issuer` no catalog entry lists for its scheme: `not_allowed`, with the listed codes in `allowed_values`.
        - `published_within_days` with `published_from` or `published_until`: `exclusive`; `published_until` before `published_from`: `order`; a date after today: `bound`.
        - A site in both `allowed_domains` and `blocked_domains`: `exclusive`; a `ranking_preferred_domains` value outside `allowed_domains` when that is set, or in `blocked_domains`: `dependent`.
        - A site name in `datasources`, or a datasource id in `allowed_domains`, `blocked_domains` or `ranking_preferred_domains`: `misplaced`, `change.field` naming the field it belongs in.
        - `contents` without `top`: `required`; `top` above 10: `bound`; `top` above `max_candidates`: `order`; `contents` with `wait_seconds` below 5, the least a fetch needs: `order`.
        - Under `deterministic_only`: `ranking_instructions`, and `json_schema` or `summary` inside `contents`: `model-work-refused`.
        - More than 20 wordings after OR splits: `bound`, with the count.
        - `max_cost` below the smallest call's price, one `searches` and one `datasource_queries`: `cost-exceeds-cap`, with `minimum_cap`.
        - `max_total_characters` below `max_excerpt_characters`: `order`.
        - A source getclean cannot search: `datasource-not-searchable`. Every named source behind a login the key has not registered: `403 datasource-access-required`; one such source among others is the coverage gap `access_needed`, and the rest run.
        - `safe_search` or `deterministic_only` looser than the key's policy, or `allowed_domains` widening the key's domain policy: `403 policy-limit-exceeded`.
        - A value of `source_kinds`, `source_independence`, `ranking_priorities` or `ranking_order` outside its set: `not_allowed`.
        - Every source would be skipped before work: `no-datasource-can-run`.
        - An unknown datasource id: `datasource-unknown`; an unknown `set:NAME`: `domain-set-unknown`.
        - A bare `pdf` in `media_types`: `not_allowed`, with `application/pdf` suggested.
        - Any other bound passed: `bound`; an unknown field: `unknown_field`.
        - `pinned_version` not served, never or no longer: `version-withdrawn`.

        **Notices this operation makes.** `query_corrected`, `filter_emulated`, `default_set_by_policy`, `window_after_as_of_date`, `fetch_not_finished`, `cost_cut`, `budget_cut`, `time_cut`, `field_not_applicable`, `total_characters_cut` on the search and on an inline record, `version_retiring`. A skipped source is a coverage gap, never a notice too.

        **Problem types.** A source's failure is never an API problem; it stands as that source's outcome in the receipt.
        - 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; `datasource-access-required`, The datasource needs a registered login; `credit-exhausted`, The credit is exhausted; `run-budget-exhausted`, The run's budget is exhausted; `key-budget-exhausted`, The key's budget is exhausted.
        - 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; `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; `no-datasource-can-run`, No datasource can run this search; `datasource-unknown`, The datasource is unknown; `datasource-not-searchable`, The datasource has no search; `domain-set-unknown`, The domain set is unknown.
        - 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.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/Traceparent'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              search.delivered:
                summary: A question searched with the first lead fetched in the same call
                value: {"query": "EU AI Act article 50 marking obligations", "published_within_days": 365, "max_candidates": 3, "contents": {"top": 1, "max_characters": 8000}, "max_cost": {"amount": "0.1000", "currency": "USD"}}
      responses:
        '201':
          description: >-
            The search record, `Search`, with `Location` naming it; the outcome first, then the notices and coverage gaps, then the leads in rank order with the facts of each, the receipt per source, the ranking, the execution and the cost.
          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/Search'
              examples:
                search.delivered:
                  summary: A question searched with the first lead fetched in the same call
                  value: {"id": "srch_4HmUunqCCXquleKVCosqFG", "retention": "hold", "outcome": {"kind": "delivered", "reason": "candidates"}, "notices": [], "coverage_gaps": [],
                    "candidates": [{"id": "cand_a1dYqVUaEDEMqh7Qgn8yip", "url": "https://eur-lex.example/ai-act", "final_url": "https://eur-lex.example/ai-act", "title": "Regulation (EU) 2024/1689", "language": "en", "media_type": "text/html",
                        "source_profile": {"kind": "state", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "copy_count": 2, "language_versions": [], "carrier": "web",
                        "published_date": "2024-07-12", "published_date_basis": "structured_data", "published_date_precision": "day", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [],
                        "relevance_score": 0.93, "excerpts": [{"text": "Providers of AI systems … shall ensure …", "wording_index": 0, "origin": "snippet", "truncated": false, "section_id": "s4", "block_id": "b31"}], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 1}],
                        "fetch_cost": {"amount": "0.0050", "currency": "USD"},
                        "contents": {"id": "cnt_8Lq5XFriyaJ0jEc2oPNx6E", "outcome": {"kind": "delivered", "reason": "sections_only"}, "notices": [], "fetched_at": "2026-11-05T09:00:03Z", "fingerprint": "sha-256=:Zt4DIioPPcwNH3magrYziAsXB0Fj8m1dwQBKY5IRuzs=:", "scope": "main", "record_scope": "main", "formats": [], "truncated": true, "counts": {"characters": 9500, "blocks": {"heading": 3, "text": 18}, "links": {"page": 12}},
                          "sections": [{"id": "s0", "title": null, "level": 0, "characters": 400, "basis": "structure"}, {"id": "s4", "title": "Article 50", "level": 2, "characters": 9100, "basis": "structure"}],
                          "source": {"url": "https://eur-lex.example/ai-act", "final_url": "https://eur-lex.example/ai-act", "title": "Regulation (EU) 2024/1689", "published_date": "2024-07-12"},
                          "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [], "elapsed_seconds": 6.2}, "cost": {"ceiling": {"amount": "0.0100", "currency": "USD"}, "actual": {"amount": "0.0050", "currency": "USD"}, "units": {"contents": 1}, "replayed": false}, "retention": "hold", "run_id": "run_default", "expires_at": "2026-11-07T09:00:03Z"}},
                      {"id": "cand_a27BTvL7IEwl2lokVFjz6n", "url": "https://commentary.example/ai-act-50", "title": "Article 50 AI Act: transparency obligations, a commentary", "language": "en", "media_type": "text/html",
                        "source_profile": {"kind": "scholarly_publisher", "role": "secondary", "independence": "unknown", "review": {"kind": "editorial", "by": null}}, "copy_count": 0, "language_versions": [], "carrier": "web",
                        "published_date": "2025-02-03", "published_date_basis": "meta_tag", "published_date_precision": "day", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [],
                        "relevance_score": 0.81, "excerpts": [{"text": "Article 50 requires providers to mark synthetic output in a machine-readable form …", "wording_index": 0, "origin": "snippet", "truncated": false}], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 2}],
                        "fetch_cost": {"amount": "0.0050", "currency": "USD"}},
                      {"id": "cand_a3fKWtZ0PhMBOSM78lATqf", "url": "https://law-firm.example/briefing", "title": "Client briefing: marking obligations under the AI Act", "language": "en", "media_type": "text/html",
                        "source_profile": {"kind": "professional_practice", "role": "secondary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "copy_count": 3, "language_versions": [], "carrier": "web",
                        "published_date": "2025-09-15", "published_date_basis": "byline", "published_date_precision": "day", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [],
                        "relevance_score": 0.64, "excerpts": [{"text": "From 2 August 2026, deployers and providers must …", "wording_index": 0, "origin": "snippet", "truncated": false}], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 5}],
                        "fetch_cost": {"amount": "0.0050", "currency": "USD"}}],
                    "counts": {"returned": 3, "found": 41, "dropped": {"not_relevant": 30, "undated": 0, "max_per_domain": 0, "blocked_domain": 0, "outside_allowed": 0, "source_kind": 0, "source_independence": 0, "folded_copy": 8, "phrase_check": 0, "exclusion_check": 0, "beyond_max_candidates": 0}},
                    "end_reason": "relevance", "interpretation": {"canonical_query": "EU AI Act article 50 marking obligations", "phrases": [], "exclusions": [], "operators": [], "wordings": [{"index": 0, "text": "EU AI Act article 50 marking obligations", "language": "en", "language_basis": "detected", "origin": "caller", "result_counts": {"web": 41}}], "languages_searched": ["en"]},
                    "applied_request": {"query": "EU AI Act article 50 marking obligations", "datasources": ["web"], "published_within_days": 365, "undated": "shown", "safe_search": "moderate", "max_per_datasource": 10, "ranking_order": "relevance", "max_candidates": 3, "max_excerpt_characters": 600, "max_total_characters": 40000, "contents": {"top": 1, "max_characters": 8000, "scope": "main", "summary": false}, "view": "full", "wait_seconds": 10, "max_cost": {"amount": "0.1000", "currency": "USD"}, "deterministic_only": false, "pinned_version": "1.0.0", "run_id": "run_default", "retention": "hold"},
                    "datasources_searched": [{"id": "web", "display_name": "Web", "group": "web", "reason": "default", "outcome": {"kind": "delivered", "reason": "candidates"}, "effective_country": "DE", "effective_language": "en", "wordings": [0], "returned_count": 41, "result_count": 41, "result_count_kind": "exact", "lead_count": 3,
                        "filters_applied": {"allowed_domains": {"state": "not_applicable"}, "blocked_domains": {"state": "not_applicable"}, "published_from": {"state": "not_applicable"}, "published_until": {"state": "not_applicable"}, "published_within_days": {"state": "native"}, "undated": {"state": "emulated", "how": "pages without a detectable date kept, as asked"}, "languages": {"state": "not_applicable"}, "media_types": {"state": "not_applicable"}, "safe_search": {"state": "native"}, "source_kinds": {"state": "not_applicable"}, "source_independence": {"state": "not_applicable"}, "as_of_date": {"state": "not_applicable"}},
                        "operators_applied": {"phrase": {"state": "not_applicable"}, "exclusion": {"state": "not_applicable"}, "alternatives": {"state": "not_applicable"}, "site": {"state": "not_applicable"}, "filetype": {"state": "not_applicable"}, "intitle": {"state": "not_applicable"}, "inurl": {"state": "not_applicable"}, "before": {"state": "not_applicable"}, "after": {"state": "not_applicable"}, "wildcard": {"state": "not_applicable"}},
                        "access_used": "open", "cost": {"ceiling": {"amount": "0.0100", "currency": "USD"}, "actual": {"amount": "0.0010", "currency": "USD"}, "units": {"datasource_queries": 1}, "replayed": false}}],
                    "ranking": {"reranked": true, "reranker_version": "rr-2026-10", "min_score": 0.42, "instructions_applied": false, "priorities": [], "order": "relevance", "preferred_domains": [], "merge": "stratified_rank_fusion", "strata": [{"datasource_id": "web", "language": "en", "lead_count": 3}]},
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "reranking", "version": "rr-2026-10"}, {"step": "discovery", "version": "disc-2026-10"}], "elapsed_seconds": 8.4},
                    "cost": {"ceiling": {"amount": "0.1000", "currency": "USD"}, "actual": {"amount": "0.0200", "currency": "USD"}, "units": {"searches": 1, "datasource_queries": 1, "model_steps": 2, "contents": 1}, "replayed": false},
                    "searched_at": "2026-11-05T09:00:00Z", "run_id": "run_default", "expires_at": "2026-11-07T09:00:03Z", "request_id": "req_02ARUKU1YFino5zjD2hYpX"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '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'}
  /v1/search/{search_id}:
    get:
      operationId: get_search
      summary: Get search
      description: |-
        Read a search you already have, free: the first page as it was answered, and behind it the full list the search stored, including the results it dropped and why. Nothing is searched again and nothing is charged; only the record's `expires_at` moves.

        The first page is the original answer as stored, whatever `page_size`: its members and the notices kept with it. A notice of the original answer that was not kept does not come back, and `dropped_reason` is absent on every candidate. A later page is the stored list in rank order, and every item on it carries `dropped_reason`. Every other member comes as stored; `request_id` is this call's, and `expires_at` is the record's new one. `next_page_token` comes while more remain. `fetch_contents` reads a candidate by its URL.

        **What it costs.** The key needs `search:read`. The call is free. The answer is `200` with `Search`; the call moves the record's `expires_at` 48 hours ahead.

        **Refused before any work.** A value outside its set or range, `page_size` above its maximum excepted, which is lowered with the notice `page_size_lowered`: `400 invalid-request`, `not_allowed` or `bound`, each with where it is. An id of the wrong kind: `400 invalid-request`, before any lookup. A token of another search or another query: `400 page-token-invalid`. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** The search's own notices first, then `page_size_lowered` and `version_retiring`.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 404 `not-found`, Not found: an unknown or another account's search.
        - 410 `search-expired`, The search has expired: for 30 days after it expired, to the owning account only, with `expired_at` and `change` naming `search`; then `404`.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: search_id
          in: path
          required: true
          description: >-
            The search record, an `srch_` id as `search` returned it.
          schema:
            type: string
            pattern: '^srch_[A-Za-z0-9]{22}$'
          example: srch_4HmUunqCCXquleKVCosqFG
        - name: view
          in: query
          required: false
          description: >-
            How much of the record comes back: `full`, every member, or `compact`, the smaller form the `Search` schema lists. Default `full`; the MCP server always asks for `compact`.
          schema:
            $ref: '#/components/schemas/View'
        - name: page_size
          in: query
          required: false
          description: >-
            Results per page of the stored list, from 1; the maximum, 50, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`. Default the search's `max_candidates`.
          schema:
            type: integer
            minimum: 1
        - name: page_token
          in: query
          required: false
          description: >-
            The next page of the stored list, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, alive as long as the record. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            The search record as stored: the first page as it was answered, or a later page of the stored list with `dropped_reason` on every item; `next_page_token` while more remain.
          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/json:
              schema:
                $ref: '#/components/schemas/Search'
              examples:
                get_search.delivered:
                  summary: A later page of the stored list, a dropped candidate with its reason, every other member as stored
                  value: {"id": "srch_4HmUunqCCXquleKVCosqFG", "retention": "hold", "outcome": {"kind": "delivered", "reason": "candidates"}, "notices": [], "coverage_gaps": [],
                    "candidates": [{"id": "cand_b7v7hQoJ35NvgmndljizaO", "url": "https://example.org/commentary", "title": "Commentary", "dropped_reason": "not_relevant", "relevance_score": 0.31, "fetch_cost": {"amount": "0.0050", "currency": "USD"}, "source_profile": {"kind": "press", "role": "secondary", "independence": "unknown", "review": {"kind": "editorial", "by": null}}, "copy_count": 0, "language_versions": [], "carrier": "web", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [], "excerpts": [], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 17}]}],
                    "counts": {"returned": 3, "found": 41, "dropped": {"not_relevant": 30, "undated": 0, "max_per_domain": 0, "blocked_domain": 0, "outside_allowed": 0, "source_kind": 0, "source_independence": 0, "folded_copy": 8, "phrase_check": 0, "exclusion_check": 0, "beyond_max_candidates": 0}},
                    "end_reason": "relevance", "interpretation": {"canonical_query": "EU AI Act article 50 marking obligations", "phrases": [], "exclusions": [], "operators": [], "wordings": [{"index": 0, "text": "EU AI Act article 50 marking obligations", "language": "en", "language_basis": "detected", "origin": "caller", "result_counts": {"web": 41}}], "languages_searched": ["en"]},
                    "applied_request": {"query": "EU AI Act article 50 marking obligations", "datasources": ["web"], "published_within_days": 365, "undated": "shown", "safe_search": "moderate", "max_per_datasource": 10, "ranking_order": "relevance", "max_candidates": 3, "max_excerpt_characters": 600, "max_total_characters": 40000, "contents": {"top": 1, "max_characters": 8000, "scope": "main", "summary": false}, "view": "full", "wait_seconds": 10, "max_cost": {"amount": "0.1000", "currency": "USD"}, "deterministic_only": false, "pinned_version": "1.0.0", "run_id": "run_default", "retention": "hold"},
                    "datasources_searched": [{"id": "web", "display_name": "Web", "group": "web", "reason": "default", "outcome": {"kind": "delivered", "reason": "candidates"}, "effective_country": "DE", "effective_language": "en", "wordings": [0], "returned_count": 41, "result_count": 41, "result_count_kind": "exact", "lead_count": 3,
                        "filters_applied": {"allowed_domains": {"state": "not_applicable"}, "blocked_domains": {"state": "not_applicable"}, "published_from": {"state": "not_applicable"}, "published_until": {"state": "not_applicable"}, "published_within_days": {"state": "native"}, "undated": {"state": "emulated", "how": "pages without a detectable date kept, as asked"}, "languages": {"state": "not_applicable"}, "media_types": {"state": "not_applicable"}, "safe_search": {"state": "native"}, "source_kinds": {"state": "not_applicable"}, "source_independence": {"state": "not_applicable"}, "as_of_date": {"state": "not_applicable"}},
                        "operators_applied": {"phrase": {"state": "not_applicable"}, "exclusion": {"state": "not_applicable"}, "alternatives": {"state": "not_applicable"}, "site": {"state": "not_applicable"}, "filetype": {"state": "not_applicable"}, "intitle": {"state": "not_applicable"}, "inurl": {"state": "not_applicable"}, "before": {"state": "not_applicable"}, "after": {"state": "not_applicable"}, "wildcard": {"state": "not_applicable"}},
                        "access_used": "open", "cost": {"ceiling": {"amount": "0.0100", "currency": "USD"}, "actual": {"amount": "0.0010", "currency": "USD"}, "units": {"datasource_queries": 1}, "replayed": false}}],
                    "ranking": {"reranked": true, "reranker_version": "rr-2026-10", "min_score": 0.42, "instructions_applied": false, "priorities": [], "order": "relevance", "preferred_domains": [], "merge": "stratified_rank_fusion", "strata": [{"datasource_id": "web", "language": "en", "lead_count": 3}]},
                    "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "reranking", "version": "rr-2026-10"}, {"step": "discovery", "version": "disc-2026-10"}], "elapsed_seconds": 8.4},
                    "cost": {"ceiling": {"amount": "0.1000", "currency": "USD"}, "actual": {"amount": "0.0200", "currency": "USD"}, "units": {"searches": 1, "datasource_queries": 1, "model_steps": 2, "contents": 1}, "replayed": false},
                    "searched_at": "2026-11-05T09:00:00Z", "run_id": "run_default", "expires_at": "2026-11-07T09:30:00Z", "request_id": "req_02Bm6tTFlq4Fjkaic7g4OM", "next_page_token": "eyJzIjoic3JjaF80SG0iLCJvIjozfQ"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '404': {$ref: '#/components/responses/Problem404'}
        '410': {$ref: '#/components/responses/Problem410'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  '/v1/search:batch':
    post:
      operationId: search_batch
      summary: Search batch
      description: |-
        Run 1 to 20 searches in one call, one record each. You get the tally first, then one result per item in input order, each a search record or the problem that skipped it; nothing is atomic, so a skipped item leaves the others standing. Each item carries its own question, wordings, identifiers, country and purpose; every other field of `search` stands once at the top and is shared by every item.

        **What it costs.** The key needs `search:run`. The price is the sum of the searches' costs, `units` summed by name. The answer is `200` with `SearchBatch`. The body is at most 4 MiB.

        **The idempotency key.** `Idempotency-Key` is required here, since a repeated batch would run and bill every search twice; its absence is `400 invalid-request` naming the header. A replay repeats the whole answer with this call's `request_id`, the current `expires_at` of every record and `replayed` true on every `cost`; the same key in flight is `409 idempotency-key-in-flight`; the same key with another body `422 idempotency-key-reused`.

        **Faults and limits.**
        - A datasource behind an unregistered login, a policy the item's sites break, a legal demand, or the remainder of the ceiling: that item comes back `skipped` with its problem, without `status`, and the batch still runs. A fault of a shared top field skips every item. A fault of the batch's shape or of any field's rule refuses the whole call.
        - `wait_seconds` is each item's own deadline from its own start. The call's whole time is bounded by `bounds.search.batch_seconds`, and an item not started when it ends is `skipped` with the problem `overloaded`, `retry_after_seconds` set.
        - `max_cost`: the whole call is refused below one search's smallest price, with the problem of the limit that binds; else it is reserved at the start and split in input order, each item its smallest call and the model steps asked by name. The items the remainder cannot cover are `skipped` with the problem of the limit that binds: `cost-exceeds-cap` for the request's `max_cost`, `policy-limit-exceeded` for the key's cap, `credit-exhausted`, `run-budget-exhausted` or `key-budget-exhausted`.
        - An item's `Search` carries the batch call's `request_id`, its `applied_request` the item's fields merged with the top's, the top's `metadata`, and its own `expires_at`.

        **Refused before any work**, every violation of the body reported at once in `violations`:
        - Fewer than 1 or more than 20 items: `invalid-field`, `bound`.
        - An item with neither `query` nor `subject_identifiers`: `required`.
        - A `label` repeated: `duplicate`; a `label` outside its character set or length: `syntax`, `bound`.
        - A top-only field inside an item, or an item field at the top: `misplaced`.
        - Every rule of `search` on the top fields and on an item's own fields refuses the whole call, except a named source behind a login the key has not registered, a site the key's policy forbids and a legal block, which skip the items they touch.
        - An unknown field, at the top or in an item: `unknown_field`.
        - `Idempotency-Key` absent: `400 invalid-request`.

        **Notices this operation makes.** Every notice of `search` inside each item's record, `version_retiring` inside each too.

        **Problem types.** For the whole call:
        - 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, for a setting, a minimum or a widening of the key's domain policy; `credit-exhausted`, The credit is exhausted; `run-budget-exhausted`, The run's budget is exhausted; `key-budget-exhausted`, The key's budget is exhausted.
        - 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; `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; `no-datasource-can-run`, No datasource can run this search; `datasource-unknown`, The datasource is unknown; `datasource-not-searchable`, The datasource has no search; `domain-set-unknown`, The domain set is unknown.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.

        Inside a skipped item, each without `status`: `datasource-access-required`, `policy-limit-exceeded`, `legal-block`, `cost-exceeds-cap`, `credit-exhausted`, `run-budget-exhausted`, `key-budget-exhausted`, `overloaded`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
        - $ref: '#/components/parameters/Traceparent'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchBatchRequest'
            examples:
              search_batch.mixed:
                summary: Two questions under one ceiling that covers one of them
                value: {"items": [{"label": "a", "query": "EU AI Act article 50 marking obligations"}, {"label": "b", "query": "EU AI Act article 52 transparency"}], "max_candidates": 3, "max_cost": {"amount": "0.0150", "currency": "USD"}}
      responses:
        '200':
          description: >-
            The tally first, then one result per item in input order, each a search record or a problem without `status`, then the sum of the searches' costs.
          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/json:
              schema:
                $ref: '#/components/schemas/SearchBatch'
              examples:
                search_batch.mixed:
                  summary: One search delivered and one item skipped, the ceiling's remainder below its smallest call
                  value: {"counts": {"delivered": 1, "partial": 0, "failed": 0, "refused": 0, "needs_person": 0, "skipped": 1},
                    "results": [{"index": 0, "label": "a", "search": {"id": "srch_5JnMVBRlNJRXAtzF4CVX0F", "retention": "hold", "outcome": {"kind": "delivered", "reason": "candidates"}, "notices": [], "coverage_gaps": [],
                        "candidates": [{"id": "cand_a1dYqVUaEDEMqh7Qgn8yip", "url": "https://eur-lex.example/ai-act", "title": "Regulation (EU) 2024/1689", "language": "en", "media_type": "text/html", "source_profile": {"kind": "state", "role": "primary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "copy_count": 2, "language_versions": [], "carrier": "web", "published_date": "2024-07-12", "published_date_basis": "structured_data", "published_date_precision": "day", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [], "relevance_score": 0.93, "excerpts": [{"text": "Providers of AI systems … shall ensure …", "wording_index": 0, "origin": "snippet", "truncated": false}], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 1}], "fetch_cost": {"amount": "0.0050", "currency": "USD"}},
                          {"id": "cand_a27BTvL7IEwl2lokVFjz6n", "url": "https://commentary.example/ai-act-50", "title": "Article 50 AI Act: transparency obligations, a commentary", "language": "en", "media_type": "text/html", "source_profile": {"kind": "scholarly_publisher", "role": "secondary", "independence": "unknown", "review": {"kind": "editorial", "by": null}}, "copy_count": 0, "language_versions": [], "carrier": "web", "published_date": "2025-02-03", "published_date_basis": "meta_tag", "published_date_precision": "day", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [], "relevance_score": 0.81, "excerpts": [{"text": "Article 50 requires providers to mark synthetic output in a machine-readable form …", "wording_index": 0, "origin": "snippet", "truncated": false}], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 2}], "fetch_cost": {"amount": "0.0050", "currency": "USD"}},
                          {"id": "cand_a3fKWtZ0PhMBOSM78lATqf", "url": "https://law-firm.example/briefing", "title": "Client briefing: marking obligations under the AI Act", "language": "en", "media_type": "text/html", "source_profile": {"kind": "professional_practice", "role": "secondary", "independence": "unknown", "review": {"kind": "none", "by": null}}, "copy_count": 3, "language_versions": [], "carrier": "web", "published_date": "2025-09-15", "published_date_basis": "byline", "published_date_precision": "day", "access": {"kind": "open", "declared_terms": [], "robots": "allowed"}, "identifier_matches": [], "relevance_score": 0.64, "excerpts": [{"text": "From 2 August 2026, deployers and providers must …", "wording_index": 0, "origin": "snippet", "truncated": false}], "matches": [{"wording_index": 0, "datasource_id": "web", "rank": 5}], "fetch_cost": {"amount": "0.0050", "currency": "USD"}}],
                        "counts": {"returned": 3, "found": 41, "dropped": {"not_relevant": 30, "undated": 0, "max_per_domain": 0, "blocked_domain": 0, "outside_allowed": 0, "source_kind": 0, "source_independence": 0, "folded_copy": 8, "phrase_check": 0, "exclusion_check": 0, "beyond_max_candidates": 0}},
                        "end_reason": "relevance", "interpretation": {"canonical_query": "EU AI Act article 50 marking obligations", "phrases": [], "exclusions": [], "operators": [], "wordings": [{"index": 0, "text": "EU AI Act article 50 marking obligations", "language": "en", "language_basis": "detected", "origin": "caller", "result_counts": {"web": 41}}], "languages_searched": ["en"]},
                        "applied_request": {"query": "EU AI Act article 50 marking obligations", "datasources": ["web"], "undated": "shown", "safe_search": "moderate", "max_per_datasource": 10, "ranking_order": "relevance", "max_candidates": 3, "max_excerpt_characters": 600, "max_total_characters": 40000, "view": "full", "wait_seconds": 10, "max_cost": {"amount": "0.0150", "currency": "USD"}, "deterministic_only": false, "pinned_version": "1.0.0", "run_id": "run_default", "retention": "hold"},
                        "datasources_searched": [{"id": "web", "display_name": "Web", "group": "web", "reason": "default", "outcome": {"kind": "delivered", "reason": "candidates"}, "effective_country": "DE", "effective_language": "en", "wordings": [0], "returned_count": 41, "result_count": 41, "result_count_kind": "exact", "lead_count": 3,
                          "filters_applied": {"allowed_domains": {"state": "not_applicable"}, "blocked_domains": {"state": "not_applicable"}, "published_from": {"state": "not_applicable"}, "published_until": {"state": "not_applicable"}, "published_within_days": {"state": "not_applicable"}, "undated": {"state": "emulated", "how": "pages without a detectable date kept, as asked"}, "languages": {"state": "not_applicable"}, "media_types": {"state": "not_applicable"}, "safe_search": {"state": "native"}, "source_kinds": {"state": "not_applicable"}, "source_independence": {"state": "not_applicable"}, "as_of_date": {"state": "not_applicable"}},
                          "operators_applied": {"phrase": {"state": "not_applicable"}, "exclusion": {"state": "not_applicable"}, "alternatives": {"state": "not_applicable"}, "site": {"state": "not_applicable"}, "filetype": {"state": "not_applicable"}, "intitle": {"state": "not_applicable"}, "inurl": {"state": "not_applicable"}, "before": {"state": "not_applicable"}, "after": {"state": "not_applicable"}, "wildcard": {"state": "not_applicable"}},
                          "access_used": "open", "cost": {"ceiling": {"amount": "0.0150", "currency": "USD"}, "actual": {"amount": "0.0010", "currency": "USD"}, "units": {"datasource_queries": 1}, "replayed": false}}],
                        "ranking": {"reranked": true, "reranker_version": "rr-2026-10", "min_score": 0.42, "instructions_applied": false, "priorities": [], "order": "relevance", "preferred_domains": [], "merge": "stratified_rank_fusion", "strata": [{"datasource_id": "web", "language": "en", "lead_count": 3}]},
                        "execution": {"version": "1.0.0", "configuration": "cfg-2026-11", "models": [{"step": "reranking", "version": "rr-2026-10"}, {"step": "discovery", "version": "disc-2026-10"}], "elapsed_seconds": 7.9},
                        "cost": {"ceiling": {"amount": "0.0150", "currency": "USD"}, "actual": {"amount": "0.0150", "currency": "USD"}, "units": {"searches": 1, "datasource_queries": 1, "model_steps": 2}, "replayed": false},
                        "searched_at": "2026-11-05T09:10:00Z", "run_id": "run_default", "expires_at": "2026-11-07T09:10:00Z", "request_id": "req_02Cibui4kSLfZhLrsUYlO2"}},
                      {"index": 1, "label": "b", "problem": {"type": "https://api.getclean.ai/problems/cost-exceeds-cap", "title": "The cost cap is below the smallest call", "detail": "The remainder of max_cost cannot cover this item's smallest call.", "instance": "https://api.getclean.ai/requests/req_02Cibui4kSLfZhLrsUYlO2/items/1", "request_id": "req_02Cibui4kSLfZhLrsUYlO2", "who_must_act": "caller", "retryable": false, "minimum_cap": {"amount": "0.0110", "currency": "USD"}}}],
                    "cost": {"ceiling": {"amount": "0.0150", "currency": "USD"}, "actual": {"amount": "0.0150", "currency": "USD"}, "units": {"searches": 1, "datasource_queries": 1, "model_steps": 2}, "replayed": false},
                    "request_id": "req_02Cibui4kSLfZhLrsUYlO2"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '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'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/datasources:
    get:
      operationId: list_datasources
      summary: List datasources
      description: |-
        List the places getclean can search, free; the answer may be cached for an hour. An entry's `id`, its `group` or `set:NAME` goes into the search's `datasources`; `filters` and `operators` say what each source honors, before any search; `issuers` gives the codes an identifier scheme takes, so your agent learns a code from the catalog and never guesses one. Every filter you send must match, and the order is the catalog's own.

        **What it costs.** The key needs `search:read`. The call is free. The answer is `200` with `DatasourcePage` and `Cache-Control: max-age=3600`, so a cached answer repeats the first call's `request_id` and rate figures, which describe that call and not yours.

        **Paging.** `page_size` from 1, default 50, maximum 200, a larger value lowered with the notice `page_size_lowered`; `page_token` is opaque, bound to its query, alive 24 hours; `next_page_token` is absent on the last page, and a page that carries it holds at least one entry.

        **Refused before any work.** A value outside its set or range, `page_size` above its maximum excepted, which is lowered: `400 invalid-request`, `not_allowed` or `bound`, each with where it is. A token of another list: `400 page-token-invalid`. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **Notices this operation makes.** `page_size_lowered`.

        **Problem types.**
        - 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
        - 401 `unauthorized`, The key is missing or rejected.
        - 403 `insufficient-scope`, The key lacks a scope this call needs.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: group
          in: query
          required: false
          description: >-
            Only this group, `web` or a group the catalog publishes, an open set, 1 to 64 characters. Default none.
          schema:
            type: string
            minLength: 1
            maxLength: 64
        - name: country
          in: query
          required: false
          description: >-
            Only sources that cover this country, ISO 3166-1 alpha-2. Default none.
          schema:
            type: string
            pattern: '^[A-Z]{2}$'
            examples: [US]
        - name: language
          in: query
          required: false
          description: >-
            Only sources that cover this language, BCP 47, 1 to 35 characters. Default none.
          schema:
            type: string
            minLength: 1
            maxLength: 35
            examples: [en]
        - name: access
          in: query
          required: false
          description: >-
            Only sources reached this way: `open`, no login; `registered`, a login the account owner registers; `paid`, a fee per query. An open set. Default none.
          schema:
            type: string
            minLength: 1
            examples: [open, registered, paid]
        - name: page_size
          in: query
          required: false
          description: >-
            At most this many entries on the page, from 1; default 50; the maximum, 200, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page_token
          in: query
          required: false
          description: >-
            The next page, as the last answer's `next_page_token` gave it; opaque, at most 1,024 characters, never built by the caller. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            One page of the catalog, in its own order; `next_page_token` while more remain.
          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/json:
              schema:
                $ref: '#/components/schemas/DatasourcePage'
              examples:
                list_datasources.first-page:
                  summary: The web and one legal register, two entries of the catalog
                  value: {"datasources": [{"id": "web", "display_name": "Web", "group": "web", "countries": [], "languages": [], "access": {"kind": "open"}, "searchable": true,
                        "filters": {"allowed_domains": "native", "blocked_domains": "native", "published_from": "native", "published_until": "native", "published_within_days": "native", "undated": "emulated", "languages": "native", "media_types": "native", "safe_search": "native", "source_kinds": "emulated", "source_independence": "emulated", "as_of_date": "not_applicable"},
                        "operators": {"phrase": "native", "exclusion": "native", "alternatives": "native", "site": "native", "filetype": "native", "intitle": "native", "inurl": "native", "before": "native", "after": "native", "wildcard": "native"},
                        "identifier_schemes": [], "history": false, "card_url": "https://api.getclean.ai/datasources/web", "request_id": "req_02EtiTZXJiQkv6q3XFlqUa"},
                      {"id": "courtlistener", "display_name": "CourtListener", "group": "legal", "countries": ["US"], "languages": ["en"], "access": {"kind": "open"}, "searchable": true,
                        "filters": {"allowed_domains": "not_applicable", "blocked_domains": "not_applicable", "published_from": "native", "published_until": "native", "published_within_days": "native", "undated": "emulated", "languages": "not_applicable", "media_types": "emulated", "safe_search": "not_applicable", "source_kinds": "not_applicable", "source_independence": "not_applicable", "as_of_date": "not_applicable"},
                        "operators": {"phrase": "native", "exclusion": "native", "alternatives": "native", "site": "not_applicable", "filetype": "not_applicable", "intitle": "emulated", "inurl": "not_applicable", "before": "native", "after": "native", "wildcard": "dropped"},
                        "identifier_schemes": ["docket", "reporter_citation"], "issuers": {"docket": ["ca9", "cand", "nysd"]}, "history": false, "card_url": "https://api.getclean.ai/datasources/courtlistener", "request_id": "req_02EtiTZXJiQkv6q3XFlqUa"}],
                    "notices": [], "request_id": "req_02EtiTZXJiQkv6q3XFlqUa"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
  /v1/datasources/{datasource_id}:
    get:
      operationId: get_datasource
      summary: Get datasource
      description: |-
        Read one entry of the catalog whole, free; the answer may be cached for an hour. You get what the source covers, how it is reached, which filters and operators it honors, which identifier schemes it resolves and with which issuer codes, and whether it keeps history for `as_of_date`.

        **What it costs.** The key needs `search:read`. The call is free. The answer is `200` with `Datasource` and `Cache-Control: max-age=3600`.

        **Refused before any work.** An id of the wrong form, other than 1 to 64 of `a-z`, `0-9` and `_` with a letter first: `400 invalid-request`, `syntax`, before any lookup. An unknown query parameter: `400 invalid-request`, `unknown_field`.

        **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.
        - 404 `not-found`, Not found: no entry has this id.
        - 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
        - 500 `internal-error`, The service failed.
        - 503 `overloaded`, The service is overloaded.
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: datasource_id
          in: path
          required: true
          description: >-
            The catalog's id, 1 to 64 of `a-z`, `0-9` and `_`, a letter first, as `web` and `courtlistener`.
          schema:
            type: string
            pattern: '^[a-z][a-z0-9_]{0,63}$'
          example: courtlistener
      responses:
        '200':
          description: >-
            The entry whole.
          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/json:
              schema:
                $ref: '#/components/schemas/Datasource'
              examples:
                get_datasource.entry:
                  summary: A legal register that resolves dockets and reporter citations
                  value: {"id": "courtlistener", "display_name": "CourtListener", "group": "legal", "countries": ["US"], "languages": ["en"], "access": {"kind": "open"}, "searchable": true,
                    "filters": {"allowed_domains": "not_applicable", "blocked_domains": "not_applicable", "published_from": "native", "published_until": "native", "published_within_days": "native", "undated": "emulated", "languages": "not_applicable", "media_types": "emulated", "safe_search": "not_applicable", "source_kinds": "not_applicable", "source_independence": "not_applicable", "as_of_date": "not_applicable"},
                    "operators": {"phrase": "native", "exclusion": "native", "alternatives": "native", "site": "not_applicable", "filetype": "not_applicable", "intitle": "emulated", "inurl": "not_applicable", "before": "native", "after": "native", "wildcard": "dropped"},
                    "identifier_schemes": ["docket", "reporter_citation"], "issuers": {"docket": ["ca9", "cand", "nysd"]}, "history": false, "card_url": "https://api.getclean.ai/datasources/courtlistener", "request_id": "req_02DBMPlcTpjeCo52E9vS45"}
        '400': {$ref: '#/components/responses/Problem400'}
        '401': {$ref: '#/components/responses/Problem401'}
        '403': {$ref: '#/components/responses/Problem403'}
        '404': {$ref: '#/components/responses/Problem404'}
        '429': {$ref: '#/components/responses/Problem429'}
        '500': {$ref: '#/components/responses/Problem500'}
        '503': {$ref: '#/components/responses/Problem503'}
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |-
        Send `Authorization: Bearer <key>` on every call.

        The bearer value is one of two things: an API key, made at `https://app.getclean.ai`; or an access token issued by `https://auth.getclean.ai/realms/getclean` to a person and the program acting for them. A client treats either as opaque, so no `bearerFormat` is declared. Either one stands for one account, with its scopes, its cap on one call, its budgets, its policy and its default run. An access token's scopes are its `scope` claim, narrowed to what the person approved and never wider.

        Scopes are explicit and deny by default. Each operation names the scope it needs in its description. One scope depends on the request: `contents:model` is needed only when a call asks for a model step, and the server decides that from the request before any work, so a missing scope is answered before any field is checked.

        What goes wrong, and how it is answered:
        - No credential, or one the service does not accept: `401`. The `WWW-Authenticate` header names the document that leads to the sign-in. A credential placed in the query string is ignored and answered the same way.
        - A credential short of a scope: `403 insufficient-scope`. Every scope the call needs is listed in `scopes_required` and in `WWW-Authenticate`.
        - A credential that fails is always `401`, never a softer answer.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |-
        One key per logical call, so a retry is never billed twice.

        Optional on this operation; required on `upload_contents`, `fetch_contents_batch` and `search_batch`, where a duplicate would cost the most. 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`, `expires_at` as it stands and `replayed` true on every `cost`. Nothing is billed again.
        - 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 free answer is not stored. 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: 1f6d4c3a-9b2e-4e7a-8c05-3d2b7a9e6f41
      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
    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}$'
  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
    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
    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
    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'
    Problem410:
      description: |-
        What the id names has expired. Three problem types answer `410`, each for 30 days after the end and to the owning account only; after that the id is `404`. Another account's id gets the `404` from the start, with the same body.
        - `contents-expired`, The record has expired: `expired_at` is the moment it expired; `change.operation` `fetch_contents` with `change.field` `url` says the page is fetched again.
        - `search-expired`, The search has expired: `change.operation` `search`.
        - `job-expired`, The job has expired: `change.operation` `upload_contents`.

        The answer carries the moment it expired and never the record's URL or the search's question.
      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:
            get_contents.contents-expired:
              summary: A record read after it expired
              value: {"type": "https://api.getclean.ai/problems/contents-expired", "title": "The record has expired", "status": 410, "detail": "The record has expired; fetch the page again.",
                "instance": "https://api.getclean.ai/requests/req_01QEihyEKxtyS4rknqVJEV", "request_id": "req_01QEihyEKxtyS4rknqVJEV", "who_must_act": "caller", "retryable": false, "expired_at": "2026-11-06T12:00:00Z", "change": {"operation": "fetch_contents", "field": "url"}}
    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'
    Problem502:
      description: |-
        `gateway-error`, A step behind the service failed: the model step that is the whole call gave a bad answer. Nothing was billed, `retryable` is true, and a retry may work; getclean looks into it. Never a source's failure, which is an outcome.
      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'
    Problem504:
      description: |-
        `gateway-timeout`, A step behind the service timed out: the model step that is the whole call passed its time bound, `bounds.contents.model_step_seconds`. Nothing was billed, `retryable` is true, and a retry may work; getclean looks into it. Never a source's timeout, which is an outcome.
      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'
  schemas:
    FetchContentsRequest:
      type: object
      description: >-
        What you send to `fetch_contents`. Only `url` is required; every other field has a default. Every field is at the top level, and an explicit null means the same as leaving the field out. The object is closed: a field it does not list is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      required: [url]
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            The address to fetch, a page or a document; getclean tells which. Required. http or https, at most 2,048 characters. A scheme other than http or https, or a password in the URL's userinfo, is refused `invalid-field`, `syntax`; localhost, an address that is not globally reachable or a bad port is `destination-refused`; a host outside the key's domain policy is `policy-limit-exceeded`.
          examples: ['https://example.com/q3']
        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 size before paying for its text. Default 20,000; `0`, or 1,000 to 1,000,000; a value between 1 and 999 is refused `bound`.
        scope:
          $ref: '#/components/schemas/Scope'
          default: main
          description: >-
            Which view to return: `main`, the main content alone, or `whole_page`, everything on the page. Default `main`. A document has one view, so `whole_page` on a document makes the notice `field_not_applicable`.
        formats:
          type: array
          minItems: 0
          maxItems: 7
          uniqueItems: true
          default: [markdown]
          description: >-
            The formats to return, 0 to 7 of these: `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; `json`, as `Block` objects; `links`, every link with its kind; `screenshot`, a picture of the whole page; `raw_html`, the page's bytes exactly as served. `[]` returns the facts only. Default `["markdown"]`. An open set; a repeated value is refused `duplicate`, a value outside the set `not_allowed`. `doclang`, `screenshot` and `raw_html` apply to a web page only; on a document each 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, screenshot, raw_html]
        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. Default: every kind. An empty list is refused `bound`. 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, 1 to 5 strings of 1 to 4,000 characters each. 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.
          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 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 input: no judged highlight, no schema fill, no summary, and the publisher's kind only from what getclean already knows. 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 scanned page 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`.
        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. When the page still matches it, the answer is `unchanged` with no text, at the fetch's price, and you know nothing moved. Default none. A malformed value is refused `syntax`. A fingerprint no record of your account issued makes the notice `fingerprint_unknown`, and one issued under another scope, version, configuration or kind of source the notice `fingerprint_incomparable`; in both cases the fetch runs whole.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        as_of_date:
          type: string
          format: date
          description: >-
            Read the page as an archive held it on that day: the latest capture at or before the end of the day, UTC. A date not after today in UTC. Default none, the live page. On an archive copy, `subject_country`, `subject_language`, `screenshot` and `max_source_price` do not apply, a notice each.
          examples: ['2026-10-01']
        subject_country:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country the page is read from, ISO 3166-1 alpha-2, one of the countries getclean can read from, `Limits.exits`. Default the key's `default_exit`. A country getclean cannot read from is refused `not_allowed`, with the countries it can read from in `allowed_values`. On a live page or a document at a URL only.
          examples: [DE]
        subject_language:
          type: string
          minLength: 1
          maxLength: 35
          description: >-
            The language to ask the site for, as its `Accept-Language`, a BCP 47 tag of 1 to 35 characters. Default none: getclean sends its usual `Accept-Language`, which `source.visitor.language` reports. On a live page or a document at a URL only.
          examples: [de-DE]
        recognition_languages:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            The languages to expect on scanned pages, 1 to 10 BCP 47 tags of 1 to 35 characters each, among `Limits.recognition_languages`; 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. On a document only; on a web page the notice `field_not_applicable` says so.
          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, the read of the page or the document, every model step and the screenshot inside, counted from the moment the work starts; time spent waiting to start is not counted. 5 to 90; default 30. What did not finish by then is cut in the published order with a notice, or the outcome says so.
        max_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most this call may cost, in the account's currency, reserved at the start against the balance and the budgets. 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 page. getclean pays no site, whatever the value: a page 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 this answer, so the screenshot and the raw HTML travel inline; `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 the read configuration and every model step's version with it, 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, 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`.
    SearchRequest:
      type: object
      description: >-
        The request of `search`; also the shape of `Search.applied_request`, the request as it ran with every field in force. Every field is at the top level but the named objects `Money`, `SubjectIdentifier` and `SearchContentsOptions`; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 2000
          description: 'The question, 1 to 2,000 characters; required unless `subject_identifiers` is sent. `"phrase"`, `-word`, `OR`, one level of `( )`, `site:`, `filetype:`, `intitle:`, `inurl:`, `before:`, `after:` and `*` are honored where a source supports them, and the receipt''s `operators_applied` says what each source did with each.'
          examples: ['EU AI Act article 50 marking obligations']
        alternate_queries:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Other wordings of the question, in any language, each 1 to 2,000 characters, up to 10; one merged list with `query`, 20 wordings at most after OR splits. Default none. A wording runs only on the sources that cover its language; nothing is translated, so a wording in another language reaches the sources in that language. Without `query` it is refused `dependent`.
          items:
            type: string
            minLength: 1
            maxLength: 2000
        subject_identifiers:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Exact codes of the subject, up to 10 `SubjectIdentifier` objects; with no `query`, each identifier's value runs as a wording with origin `identifier`. `issuer` is required for `ticker`, `docket`, `tax_id` and `registry`, as the catalog's codes; a duplicate is refused `duplicate`. Default none.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        subject_country:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country the search is made from, ISO 3166-1 alpha-2; groups of sources expand by it; the inline fetch reads from it when it is a country getclean can read from, one of `Limits.exits`, else from the key's `default_exit` with the notice `field_not_applicable`. Default none.
          examples: [DE]
        purpose:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            Your reason for the search, kept in the record and read by every model step; never sent to a source. At most 2,000 characters. Default none.
        datasources:
          type: array
          maxItems: 10
          uniqueItems: true
          description: 'Where to search: up to 10 of a datasource id, a group, or `set:NAME`, a published set, each 1 to 64 characters; these are names without dots, where `allowed_domains` takes site names with dots. When sent, the search runs on these plus the sources that resolve a scheme of your `subject_identifiers`, added without a model step, each in the receipt with reason `identifier`. When absent, it runs on `web` plus the groups a model chooses for the question, one model step, each named; under `deterministic_only`, on `web` only. An unknown id is `datasource-unknown`, an unknown set `domain-set-unknown`, a site name here `misplaced`.'
          items:
            type: string
            minLength: 1
            maxLength: 64
            examples: [web, courtlistener]
        allowed_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: 'Only results on these sites count, site names with dots: up to 500 of a domain, a wildcard such as `*.example.com`, a URL prefix, a suffix such as `.gov`, or `set:NAME`, a published set, each 1 to 2,048 characters. What each form reaches: a domain, that host and every host under it; `*.example.com`, the hosts under the domain and not the domain itself; a URL prefix, every address that begins with it; a suffix with a leading dot, every domain that ends in it; `set:NAME`, the sites of that set. It may narrow the key''s `policy.allowed_domains` and never widen it, which is `policy-limit-exceeded`. Default none. A site in both this and `blocked_domains` is refused `exclusive`; a datasource id here `misplaced`.'
          items:
            type: string
            minLength: 1
            maxLength: 2048
        blocked_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Never results on these sites; up to 500 of the same forms and bound as `allowed_domains`, each form reaching what it reaches there. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        published_from:
          type: string
          format: date
          description: >-
            Pages published on or after this date, inclusive, by the page's own date. Default none. With `published_within_days` it is refused `exclusive`; after `published_until` the pair is refused `order`; a date after today `bound`; a window that begins after `as_of_date` makes the notice `window_after_as_of_date`.
          examples: ['2026-01-01']
        published_until:
          type: string
          format: date
          description: >-
            Pages published on or before this date, inclusive. Default none.
          examples: ['2026-11-01']
        published_within_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: >-
            Pages published within this many days counted back from today, or from `as_of_date` when it is sent; 1 to 3,650. Not with `published_from` or `published_until`, which is refused `exclusive`. Default none.
        undated:
          $ref: '#/components/schemas/Undated'
          default: shown
          description: >-
            Whether pages with no detectable date are kept inside a date window: `shown` keeps them, `hidden` drops them. Default `shown`. Sent without a window it makes the notice `field_not_applicable`.
        languages:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Only pages written in these languages, up to 10 BCP 47 tags, each 1 to 35 characters; what the pages are written in, independent of the wordings' languages. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 35
        media_types:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Only these file types, up to 10 IANA media types, each 1 to 255 characters; a bare `pdf` is refused `not_allowed` with `application/pdf` suggested. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 255
            examples: [application/pdf]
        safe_search:
          $ref: '#/components/schemas/SafeSearch'
          default: moderate
          description: >-
            How strictly adult content is filtered: `off`, `moderate` or `strict`. Where a source has the setting it is mapped to the nearest level, said with the notice `filter_emulated`; it never removes a source. Never looser than the key's `policy.safe_search`, which is `policy-limit-exceeded`. Default `moderate`.
        source_kinds:
          type: array
          minItems: 1
          maxItems: 24
          uniqueItems: true
          description: >-
            Only these kinds of publisher, 1 to 24 of the kinds of `SourceProfile.kind`, never `unknown`; a filter that removes, where `ranking_priorities` only reorders. Default none.
          items:
            type: string
            minLength: 1
            description: >-
              One publisher kind, a value of `SourceProfile.kind`.
            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]
        source_independence:
          $ref: '#/components/schemas/SourceIndependence'
          description: >-
            Only sources independent of the subject, or only its own; `independent` or `self`. Needs a subject resolved from `subject_identifiers`, else the notice `field_not_applicable`. Default none, any.
        as_of_date:
          type: string
          format: date
          description: >-
            Search each source as it stood at the end of that day, UTC, and read any inline fetch from an archive's copy of that day. A date not after today. Default none, the sources as they stand now. A source that keeps no history reports `no_history`.
          examples: ['2026-10-01']
        max_per_datasource:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: >-
            Results taken from each source per wording, before merging; capped by the source's maximum. 1 to 100; default 10.
        ranking_instructions:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            Your instructions to the ranking model, at most 2,000 characters; kept in the record. Default none. Refused `model-work-refused` under `deterministic_only`.
        ranking_priorities:
          type: array
          maxItems: 4
          uniqueItems: true
          description: >-
            Source facts that go first, in this order, up to 4 of `official`, `independent`, `primary`, `reviewed`; the leads grouped by them, then ordered within each group by `ranking_order`. Default none. `independent` with no subject resolved makes the notice `field_not_applicable`.
          items:
            $ref: '#/components/schemas/RankingPriority'
        ranking_order:
          $ref: '#/components/schemas/RankingOrder'
          default: relevance
          description: >-
            The order within each priority group; `relevance`, `newest` or `oldest`; undated pages last under the date orders; the relevance cut-off applies in every case. Default `relevance`.
        ranking_preferred_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Sites ranked first among results of equal relevance; other sites still count. Up to 500 of the forms of `allowed_domains`, each reaching what it reaches there, each 1 to 2,048 characters. Default none. A value outside `allowed_domains` when it is set, or in `blocked_domains`, is refused `dependent`.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        ranking_max_per_domain:
          type: integer
          minimum: 1
          maximum: 50
          description: >-
            The most leads kept from one site in the answer, 1 to 50. Default none. With one allowed site it makes the notice `field_not_applicable`.
        max_candidates:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: >-
            The leads returned, 1 to 50; default 10. The results past them are read free by `get_search`.
        max_excerpt_characters:
          type: integer
          minimum: 0
          maximum: 4000
          default: 600
          description: >-
            The excerpt per lead, in characters, 0 to 4,000; 0 means none. Default 600.
        max_total_characters:
          type: integer
          minimum: 1000
          maximum: 200000
          default: 40000
          description: >-
            The whole answer's text, excerpts and fetched pages together, 1,000 to 200,000; the excerpts first, cut from the last lead backwards when they alone pass it, then the fetched pages in rank order while they fit in what remains, a page that would pass it coming as `sections_only`; each cut the notice `total_characters_cut`. Default 40,000. Below `max_excerpt_characters` it is refused `order`.
        contents:
          $ref: '#/components/schemas/SearchContentsOptions'
          description: >-
            Fetch this many top leads in the same call, under the inline fetch's rules; `contents.max_characters` bounds one page, `max_total_characters` the whole answer. Default none. The options without `top` are refused `required`; `top` above `max_candidates` `order`; with `wait_seconds` below 5, the least a fetch needs, `order`.
        view:
          $ref: '#/components/schemas/View'
          default: full
          description: >-
            How much of the record comes back: `full`, every member, or `compact`, the smaller form the `Search` schema lists. Default `full`; the MCP server always asks for `compact`.
        wait_seconds:
          type: number
          minimum: 0.2
          maximum: 60
          default: 10
          description: >-
            The most seconds this call may work, the ranking, the choice of sources and every inline fetch inside, counted from the start of the work; what did not finish comes back `partial`, named. 0.2 to 60; default 10.
        max_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most this call may cost, in the account's currency. When it cannot cover everything, the extras are cut in order, each with the notice `cost_cut`: first each inline fetch's own extras, then whole fetches, then the ranking, then the choice of sources, then the results taken per source. Default the key's cap on one call. Below the smallest call's price, one `searches` and one `datasource_queries`, it is refused `cost-exceeds-cap` with `minimum_cap`.
        deterministic_only:
          type: boolean
          default: false
          description: >-
            Turn off every step a model judges: the ranking and the choice of sources, which the answer then says; the publisher's kind only from what getclean already knows; the inline fetch's `json_schema` and `summary` refused by name and its `highlights` found verbatim only. Text recognition on a scanned page fetched inline still runs and is listed. Default false. Sending false under a key whose policy forbids model work is `policy-limit-exceeded`.
        pinned_version:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The version of getclean to run under, at most 64 characters. Default the current version. A version not served is `version-withdrawn`.
          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. Default the key's default run. An unknown run is refused `not_allowed`.
        record_form:
          type: string
          minLength: 1
          description: >-
            Have the search written up for a reviewer: `plain`, in plain words, or `prisma`, in the PRISMA form a systematic review reports; an open set. Default none, no write-up.
          examples: [plain, prisma]
        metadata:
          type: object
          minProperties: 1
          maxProperties: 20
          propertyNames:
            minLength: 1
            maxLength: 64
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 512
          description: >-
            Your own labels, returned on the record as sent and never passed to a source: at most 20 string pairs, keys of 1 to 64 characters, values of 1 to 512. Default none. An empty map is refused `bound`.
        max_source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The most you allow for a datasource that charges per query, or for a site an inline fetch meets that asks a price. A source whose fee passes it is not searched, the coverage gap `over_price`, never a refusal. getclean pays no site for a page, so a page that asks a price ends `payment_required`. Default none.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the search record and every inline record are kept: `hold`, 48 hours after the last call and at most 30 days, allowed only under a `hold` policy; `none`, nothing kept past the answer. Default the key's `policy.retention`.
    SearchContentsOptions:
      type: object
      description: >-
        What to fetch in the same call as the search, the `contents` field of `SearchRequest`: how many of the top leads, `top`, and how each is read, with the fields as `fetch_contents` defines them. There is no `formats`, since the record a search carries holds markdown or the map. The object is closed.
      additionalProperties: false
      required: [top]
      properties:
        top:
          type: integer
          minimum: 1
          maximum: 10
          description: >-
            The leads to fetch in the same call, 1 to 10, from the top of the list; above `max_candidates` it is refused `order`. Required inside the object.
        max_characters:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 20000
          description: >-
            The most text returned per fetched page, in characters; `0` means no text, the map and the facts; `0`, or 1,000 to 1,000,000. Default 20,000.
        scope:
          $ref: '#/components/schemas/Scope'
          default: main
          description: >-
            Which view of each fetched page: `main`, the main content alone, or `whole_page`. Default `main`.
        block_kinds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            Keep only blocks of these kinds, as on `fetch_contents`. Default: every kind.
          items:
            type: string
            minLength: 1
            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 and mark in each fetched page, as on `fetch_contents`. 1 to 5 strings, each 1 to 4,000 characters. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 4000
        json_schema:
          type: object
          description: >-
            Your own fields, filled from each fetched page by a model, as on `fetch_contents`; one model step per page. Default none. Refused `model-work-refused` under `deterministic_only`.
        summary:
          type: boolean
          default: false
          description: >-
            Have a model write a summary of each fetched page, as on `fetch_contents`; one model step per page. Default false. Refused `model-work-refused` under `deterministic_only`.
    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]
    SubjectIdentifier:
      type: object
      description: >-
        One exact code of a subject. A certificate's or a licence's number travels as `registry` with its issuing body. The object is closed.
      additionalProperties: false
      required: [scheme, value]
      properties:
        scheme:
          type: string
          minLength: 1
          description: >-
            The kind of code: `doi`, `pmid`, `isbn`, `issn`, `arxiv`, `isin`, `lei`, `ticker`, `tax_id`, `registry`, `docket`, `reporter_citation`, `ecli`, `patent`, `asin` or `gtin`; an open set.
          examples: [doi, pmid, isbn, issn, arxiv, isin, lei, ticker, tax_id, registry, docket, reporter_citation, ecli, patent, asin, gtin]
        value:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            The code, 1 to 256 characters.
          examples: ['10.1000/xyz123']
        issuer:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The catalog's code for the issuing body, 1 to 64 characters; required for `ticker`, `docket`, `tax_id` and `registry`, where its absence is refused `dependent` and a code no catalog entry lists `not_allowed`; absent otherwise, where a sent value makes the notice `field_not_applicable`. The catalog's `Datasource.issuers` lists the codes, so your agent learns one and never guesses.
          examples: [xnys]
    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]
    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]
    Undated:
      type: string
      description: >-
        Whether pages with no detectable date are kept inside a date window: `shown` keeps them, `hidden` drops them. A closed set.
      enum: [shown, hidden]
    SafeSearch:
      type: string
      description: >-
        How strictly adult content is filtered, where a source has the setting: `off`, `moderate` or `strict`. A closed set.
      enum: ['off', moderate, strict]
    SourceIndependence:
      type: string
      description: >-
        Sources independent of the subject, `independent`, or the subject's own, `self`. A closed set.
      enum: [independent, self]
    RankingPriority:
      type: string
      description: >-
        A fact about a source that puts it first in the ranking: `official`, a publisher of one of the six public kinds of `SourceProfile.kind`, a state, a court, a regulator, a statistics office, an intergovernmental body or a standards body; `independent`, independent of the subject; `primary`, a primary source; `reviewed`, a stated review. A closed set.
      enum: [official, independent, primary, reviewed]
    RankingOrder:
      type: string
      description: >-
        The order within each priority group; `relevance`, `newest` or `oldest`. A closed set.
      enum: [relevance, newest, oldest]
    View:
      type: string
      description: >-
        How much of a search record comes back: `full`, every member, or `compact`, the smaller form the `Search` schema lists. A closed set.
      enum: [full, compact]
    DatePrecision:
      type: string
      description: >-
        How exact a published date is; `day`, `month` or `year`. A closed set.
      enum: [day, month, year]
    FilterState:
      type: string
      description: >-
        How a hard filter was applied on one source; `native`, by the source; `emulated`, by getclean after the fact; `skipped`, the source skipped for it; `not_applicable`, the filter not sent. A closed set.
      enum: [native, emulated, skipped, not_applicable]
    OperatorState:
      type: string
      description: >-
        How a query operator was applied on one source: `native`, by the source; `emulated`, by getclean; `dropped`, left out on that source; `not_applicable`, the query did not use it. A closed set.
      enum: [native, emulated, dropped, not_applicable]
    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`.
    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.
    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
    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.
    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'
    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.
    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']
    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.
    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.
    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.
    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]
    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.
    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.
    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']
    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.
    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.
    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]
    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'
    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`.
    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.
    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.
    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.
    Search:
      type: object
      description: |-
        One search record, `srch_`, kept 48 hours after its last call and at most 30 days from its making. It keeps the results and the receipt as they were, and `get_search` pages the list the search stored and never searches again or charges. It reads in one order: the outcome; the notices and the coverage gaps, read before the list; the leads in rank order with the facts of each; the counts, which describe the search and never a page; how the question was read and the request as it ran; the receipt per source; what ordered the list; how it ran; the money.

        Under `view` `compact` only these members come, each whole: `id`, `outcome`, `notices`, `coverage_gaps`, `counts`, `end_reason`, `cost`, `searched_at`, `run_id`, `expires_at`, `request_id`, `next_page_token` on a paged `get_search`, and `candidates`, each with `id`, `url`, `title`, `published_date`, `access`, `relevance_score`, `source_profile`, `fetch_cost`, `dropped_reason` on a paged item, `excerpts` holding the first excerpt only, and `contents` when fetched. Every member outside that list is optional in this schema and always present in the full view.
      required: [id, outcome, notices, coverage_gaps, candidates, counts, cost, searched_at, run_id, expires_at, request_id]
      properties:
        id:
          type: string
          pattern: '^srch_[A-Za-z0-9]{22}$'
          description: >-
            The record's id, `srch_` and 22 random characters, which cannot be guessed.
          examples: [srch_4HmUunqCCXquleKVCosqFG]
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the record is kept, `hold` or `none`. Present in the full view.
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: >-
            What happened, first. `delivered` when every source tried answered and everything asked ran, a source skipped before work being a coverage gap and no partial; `partial` when something tried did not finish; the other kinds only when no source answered.
        notices:
          type: array
          description: >-
            Read before the list; a corrected query, an emulated filter, a cut, a default set by policy, a fetch that did not finish; a skipped source is a coverage gap, never a notice too. `[]` when none.
          items:
            $ref: '#/components/schemas/Notice'
        coverage_gaps:
          type: array
          description: >-
            What was asked and not searched, with why; `[]` when none.
          items:
            $ref: '#/components/schemas/CoverageGap'
        candidates:
          type: array
          description: >-
            The leads, in rank order; `[]` when none. On a later page of `get_search`, the list the search stored, each item with `dropped_reason`.
          items:
            $ref: '#/components/schemas/Candidate'
        counts:
          $ref: '#/components/schemas/SearchCounts'
          description: >-
            Leads returned and pages found before the cut; `found` equals `returned` plus every dropped count.
        end_reason:
          type: string
          description: >-
            Why the list ended: `relevance`, the next candidate fell under the ranking model's cut-off; `max_candidates`, the cap on leads was reached; `ceiling`, the money ran out; `exhausted`, every source gave all it had; `source_cap`, every source reached `max_per_datasource`. A closed set. Present on `delivered` and `partial`, absent on the other kinds.
          enum: [relevance, max_candidates, ceiling, exhausted, source_cap]
        interpretation:
          $ref: '#/components/schemas/Interpretation'
          description: >-
            How the question was read. Present in the full view.
        applied_request:
          $ref: '#/components/schemas/SearchRequest'
          description: >-
            The request as it ran; every field whose value was in force present with that value, defaults and resolutions written out; a field with no value absent. Present in the full view.
        record:
          $ref: '#/components/schemas/SearchRecord'
          description: >-
            The search written up. Present only with `record_form`.
        datasources_searched:
          type: array
          description: >-
            The receipt per source. Present in the full view, `[]` when none.
          items:
            $ref: '#/components/schemas/DatasourceReceipt'
        ranking:
          $ref: '#/components/schemas/Ranking'
          description: >-
            What ordered the list. Present in the full view.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How it ran; `models` carries `reranking`, `discovery` and `source_profile` when they ran. Present in the full view.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The money, the original bill as stored on every `get_search` page, never a new charge; `units` among `searches`, `datasource_queries`, `model_steps` and the inline fetches' units.
        metadata:
          type: object
          description: >-
            Your own labels, returned as sent. Present when sent.
          additionalProperties:
            type: string
        searched_at:
          type: string
          format: date-time
          description: >-
            When the search started, RFC 3339 in UTC.
          examples: ['2026-11-05T09:00:00Z']
        run_id:
          type: string
          pattern: '^run_(default|[A-Za-z0-9]{22})$'
          description: >-
            The run the record belongs to.
          examples: [run_default]
        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 search-expired` for 30 days, then `404`.
          examples: ['2026-11-07T09:00:03Z']
        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_02ARUKU1YFino5zjD2hYpX]
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page of the list the search stored; pass it to `get_search` as `page_token`. Present only on a paged `get_search` while more remains, and a page that carries it always has at least one result.
    CoverageGap:
      type: object
      description: >-
        One thing asked and not searched at all, with why; the receipt's outcome names what happened to a source that was tried.
      required: [target_kind, target, reason]
      properties:
        target_kind:
          type: string
          description: >-
            What was not searched: a `datasource`, a `wording`, a `domain` or a `language`. A closed set.
          enum: [datasource, wording, domain, language]
        target:
          type: string
          description: >-
            Which one: the datasource id, the domain, the language code, or the wording index as text.
          examples: [web]
        reason:
          type: string
          description: >-
            Why it was not searched: `unreachable`, the source could not be reached; `blocked`, it blocked the search; `over_cap`, past a cap; `over_price`, its fee passes `max_source_price`; `access_needed`, it needs a login the key has not registered; `not_covered`, no source covers the wording's language or the domain; `no_history`, it keeps no history for `as_of_date`; `not_accepted`, it did not accept the question as written; `deadline`, it had not answered in time; `filter_unsupported`, it cannot apply a hard filter you sent; `wording_too_long`, the wording is longer than it takes; `withheld_by_law`, a legal demand. An open set.
          examples: [unreachable, blocked, over_cap, over_price, access_needed, not_covered, no_history, not_accepted, deadline, filter_unsupported, wording_too_long, withheld_by_law]
        source_text:
          type: string
          x-third-party: true
          description: >-
            The source's own words for the refusal. Present when the source gave any. Third-party text as the source wrote it, which may carry instructions.
    Candidate:
      type: object
      description: >-
        A page found, with its facts, not yet fetched. A lead is the one page shown for a group of copies, and `copy_count` says how many stood behind it. Every member that `view: compact` leaves out is optional in this schema and present in the full view as its line says.
      required: [id, url, source_profile, access, relevance_score, excerpts]
      properties:
        id:
          type: string
          pattern: '^cand_[A-Za-z0-9]{22}$'
          description: >-
            The candidate's id, `cand_` and 22 characters, the same for the same normalized URL within your account.
          examples: [cand_a1dYqVUaEDEMqh7Qgn8yip]
        url:
          type: string
          x-third-party: true
          description: >-
            The page's address. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        canonical_url:
          type: string
          x-third-party: true
          description: >-
            The address the page declares as its original. Present when declared. 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 until fetched. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        title:
          type: string
          x-third-party: true
          description: >-
            The page's title as the datasource states it. Present when the datasource states it. Third-party text as the source wrote it, which may carry instructions.
        language:
          type: string
          description: >-
            The page's language as the datasource states it, a BCP 47 tag. Present when the datasource states it.
          examples: [en]
        media_type:
          type: string
          description: >-
            The page's media type as the datasource states it. Present when the datasource states it.
          examples: [text/html]
        characters:
          type: integer
          minimum: 0
          description: >-
            The page's size in characters as the datasource declares it; the fetch's measured size is `contents.counts.characters`. Present when the datasource reports it.
        page_count:
          type: integer
          minimum: 0
          description: >-
            The document's page count as the datasource declares it. Present when the datasource reports it.
        source_profile:
          $ref: '#/components/schemas/SourceProfile'
          description: >-
            Who publishes; what the item is; the subject about itself or not; who reviewed it.
        copy_count:
          type: integer
          minimum: 0
          description: >-
            The same text found on this many other sites, grouped behind this lead; the same text is an equal normalized main text or one above a published similarity; the lead is the copy with the earliest claimed date among the copies that carry one, else the first found. Present in the full view.
        language_versions:
          type: array
          description: >-
            The page's own translations as declared; `[]` when none. Present in the full view.
          items:
            $ref: '#/components/schemas/LanguageVersion'
        carrier:
          type: string
          description: >-
            The kind of source: `web`, a live page, or `archive`, an archive's copy read under `as_of_date`; an open set; a candidate never carries `upload`. Present in the full view.
          examples: [web, archive]
        published_date:
          type: string
          format: date
          description: >-
            The date of publication the page or the datasource claims, a full date. Present when one states it.
        published_date_basis:
          type: string
          description: >-
            Where the date was read: `structured_data`, `meta_tag`, `byline`, `url` or `datasource`; an open set. Present with the date.
          examples: [structured_data, meta_tag, byline, url, datasource]
        published_date_precision:
          $ref: '#/components/schemas/DatePrecision'
          description: >-
            How exact the date is, `day`, `month` or `year`. Present with the date.
        modified_date:
          type: string
          format: date
          description: >-
            The date of the last change the page or the datasource claims, a full date. Present when one states it.
        modified_date_basis:
          type: string
          description: >-
            Where the modification date was read: `structured_data`, `meta_tag`, `byline`, `url` or `datasource`; an open set. Present with the date.
          examples: [structured_data, meta_tag, byline, url, datasource]
        published_at:
          type: string
          format: date-time
          description: >-
            The moment of publication in UTC. Present only when the page states a time with its zone.
        modified_at:
          type: string
          format: date-time
          description: >-
            The moment of the last change in UTC. Present only when the page states a time with its zone.
        acquired_at:
          type: string
          format: date-time
          description: >-
            When the datasource took its copy of the page. Present when known.
        declared:
          $ref: '#/components/schemas/Declared'
          description: >-
            What the datasource declares about the item. Present when the datasource declares anything.
        access:
          $ref: '#/components/schemas/Access'
          description: >-
            What the page demands, seen without a fetch.
        identifier_matches:
          type: array
          description: >-
            The codes sent that this page carries; `[]` when none. Present in the full view.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        relevance_score:
          type: [number, 'null']
          minimum: 0
          maximum: 1
          description: >-
            The ranking model's score, 0 to 1; null under `deterministic_only` and on `rerank_missing`.
        dropped_reason:
          type: string
          description: >-
            Why this item is not a lead, one of the member names of `DroppedCounts`. A closed set. Absent on a lead; set on an item of a later page of `get_search`.
          enum: [not_relevant, undated, max_per_domain, blocked_domain, outside_allowed, source_kind, source_independence, folded_copy, phrase_check, exclusion_check, beyond_max_candidates]
        lead_id:
          type: string
          pattern: '^cand_[A-Za-z0-9]{22}$'
          description: >-
            The lead this copy was grouped behind. Present on an item of a later page dropped as `folded_copy`.
          examples: [cand_a27BTvL7IEwl2lokVFjz6n]
        excerpts:
          type: array
          description: >-
            The matching snippets; `[]` when none; under `view` `compact` the first excerpt only.
          items:
            $ref: '#/components/schemas/Excerpt'
        matches:
          type: array
          description: >-
            Which wording found it where. Present in the full view only.
          items:
            $ref: '#/components/schemas/Match'
        fetch_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most a fetch of it with this request's inline options can cost, from the price list and the known size. Absent when a document's page count is unknown.
        contents:
          $ref: '#/components/schemas/ContentsCompact'
          description: >-
            The compact record of the inline fetch, with its own `cost`; the full record is free through `get_contents` with its `id`. Present when the search that made the record fetched it, in both views and on `get_search`'s first page.
    Declared:
      type: object
      x-third-party: true
      description: >-
        What the datasource declares about the item; each member present when declared. Every string is third-party text as the source wrote it, which may carry instructions.
      properties:
        identifiers:
          type: array
          description: >-
            The codes the datasource declares for the item.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        authors:
          type: array
          description: >-
            The authors as the datasource states them.
          items:
            type: string
        publisher:
          type: string
          description: >-
            The publisher's name as the datasource states it.
        version_label:
          type: string
          description: >-
            The item's version label as the datasource states it.
        license:
          type: string
          description: >-
            The item's licence as the datasource states it.
        open_access_status:
          type: string
          description: >-
            The item's open access status as the datasource states it.
        item_type:
          type: string
          description: >-
            The kind of item as the datasource states it.
        publisher_place:
          type: string
          description: >-
            The publisher's place as the datasource states it.
        match_level:
          type: string
          description: >-
            How closely the item matched, as the datasource states it.
        status:
          type: string
          description: >-
            The item's status as the datasource states it.
        restrictions:
          type: string
          description: >-
            The restrictions on the item as the datasource states them.
        scores:
          type: object
          description: >-
            The datasource's own scores, by its names.
          additionalProperties:
            type: number
    Access:
      type: object
      description: >-
        What a page demands, as the search saw it without a fetch.
      required: [kind, declared_terms, robots]
      properties:
        kind:
          type: string
          description: >-
            What the page demands: `open`, nothing; `paywall`, a purchase; `sign_in`, a sign-in; `blocked`, it refuses the visitor; `unknown`. A closed set.
          enum: [open, paywall, sign_in, blocked, unknown]
        price:
          $ref: '#/components/schemas/Money'
          description: >-
            The price the page states. Present when known.
        declared_terms:
          type: array
          description: >-
            The signals the search saw without a fetch; `[]` when none.
          items:
            $ref: '#/components/schemas/DeclaredTerm'
        robots:
          type: string
          description: >-
            What the site's robots file says for getclean by its published name: `allowed`, `disallowed`, `absent`, `unreachable` or `not_applicable`; an open set.
          examples: [allowed, disallowed, absent, unreachable, not_applicable]
    Excerpt:
      type: object
      description: >-
        One matching snippet of a candidate.
      required: [text, wording_index, origin, truncated]
      properties:
        text:
          type: string
          x-third-party: true
          description: >-
            The snippet. Third-party text as the source wrote it, which may carry instructions.
        wording_index:
          type: integer
          minimum: 0
          description: >-
            The wording that found it, from 0.
        origin:
          type: string
          description: >-
            Where the snippet came from: `snippet`, the source's own snippet; `featured`, the source's featured answer. A closed set.
          enum: [snippet, featured]
        truncated:
          type: boolean
          description: >-
            Whether the snippet was cut.
        limit:
          type: string
          description: >-
            What cut it: `press_publication`, a press publication's protection; `source_restricted`, the source's own restriction. An open set. Present when a limit cut it.
          examples: [press_publication, source_restricted]
        section_id:
          type: string
          pattern: '^s[0-9]+$'
          description: >-
            The section the excerpt stands in within the fetched record, placed by the `exact` and `near` rules of `highlights`, nothing marked and no model. Present once an inline fetch placed it.
          examples: [s2]
        block_id:
          type: string
          pattern: '^b[0-9]+$'
          description: >-
            The block the excerpt stands in. Present as `section_id` is.
          examples: [b7]
    Match:
      type: object
      description: >-
        One wording's hit on one source.
      required: [wording_index, datasource_id, rank]
      properties:
        wording_index:
          type: integer
          minimum: 0
          description: >-
            The wording that found it, by its index from 0.
        datasource_id:
          type: string
          pattern: '^[a-z][a-z0-9_]{0,63}$'
          description: >-
            The datasource it was found on.
          examples: [web]
        rank:
          type: integer
          minimum: 1
          description: >-
            The position in that source's list for that wording, from 1.
    ContentsCompact:
      type: object
      description: >-
        The compact contents record: the record a search's candidate carries, in both views, and the item of `list_contents`. Each member is typed and present as `Contents` gives it, with three differences: `source` is a `SourceCompact`; there is no `screenshot` and no `raw_html`; `cost` is present on the record as the call that billed it answered it, the search's inline fetch, and absent on the item of `list_contents`.
      required: [id, outcome, notices, fetched_at, truncated, source, execution, retention, run_id, expires_at]
      properties:
        id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record's id; the full record is free through `get_contents`.
          examples: [cnt_8Lq5XFriyaJ0jEc2oPNx6E]
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: >-
            What happened at the fetch; no later call rewrites it.
        notices:
          type: array
          description: >-
            The notices kept with the record first, then this answer's own; `[]` when 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.
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it. Present on delivered and partial records.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view this answer delivers. Present on delivered and partial records.
        record_scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view the fetch ran under. Present on delivered and partial records.
        formats:
          type: array
          description: >-
            The formats this answer carries: `markdown` when the text came, else `[]`, as when the map came or on an item of `list_contents`, which carries no text. Present on delivered and partial records.
          items:
            type: string
            examples: [markdown]
        truncated:
          type: boolean
          description: >-
            True when text was asked for and did not fit, so the map came instead.
        markdown:
          type: string
          x-third-party: true
          description: >-
            The content as one markdown string. Present when the text fit. Third-party text as the source wrote it, which may carry instructions.
        sections:
          type: array
          description: >-
            The map of the content, one row per section. Present when the text did not fit or `max_characters` was `0`.
          items:
            $ref: '#/components/schemas/Section'
        counts:
          $ref: '#/components/schemas/ContentsCounts'
          description: >-
            How much the record holds: characters, blocks by kind, links by kind. Present on delivered and partial records.
        highlights:
          type: array
          description: >-
            Every place the fetch's `highlights` strings found. Present when `highlights` were sent.
          items:
            $ref: '#/components/schemas/Highlight'
        summary:
          type: string
          x-third-party: true
          maxLength: 1500
          description: >-
            The summary a model wrote of the content. Present when `summary` was sent and written. 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. Present when `json_schema` was sent and filled. 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, keyed by a JSON Pointer into `schema_values`. Present when `json_schema` was sent and filled.
          additionalProperties:
            $ref: '#/components/schemas/SchemaStatus'
        source:
          $ref: '#/components/schemas/SourceCompact'
          description: >-
            The source's address, final address, title and date.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How the record was made: the version, the configuration, the model steps and the time it took.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The inline fetch's own bill. Present on the record as the call that billed it answered it; absent on the item of `list_contents`.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the record is kept, `hold` or `none`.
        run_id:
          type: string
          pattern: '^run_(default|[A-Za-z0-9]{22})$'
          description: >-
            The run the record belongs to.
          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.
    SourceCompact:
      type: object
      description: >-
        The source of a compact record; each member present and typed as `Source` gives it.
      required: [title, published_date]
      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']
        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.
        published_date:
          type: [string, 'null']
          format: date
          description: >-
            The date of publication as the source declares it, a full date; null when none.
        published_at:
          type: string
          format: date-time
          description: >-
            The moment of publication in UTC. Present when the page states a time with its zone.
    SearchCounts:
      type: object
      description: >-
        The counts describe the search, never a page; `found` equals `returned` plus every dropped count whatever ended the list.
      required: [returned, found, dropped]
      properties:
        returned:
          type: integer
          minimum: 0
          description: >-
            The leads returned.
        found:
          type: integer
          minimum: 0
          description: >-
            The pages found before the cut.
        dropped:
          $ref: '#/components/schemas/DroppedCounts'
          description: >-
            Why the rest are not leads, by reason.
    DroppedCounts:
      type: object
      description: >-
        The results that are not leads, by reason; every integer always present; the keys are the values `dropped_reason` takes.
      required: [not_relevant, undated, max_per_domain, blocked_domain, outside_allowed, source_kind, source_independence, folded_copy, phrase_check, exclusion_check, beyond_max_candidates]
      properties:
        not_relevant:
          type: integer
          minimum: 0
          description: >-
            Results under the ranking model's cut-off.
        undated:
          type: integer
          minimum: 0
          description: >-
            Results with no detectable date, dropped under `undated` `hidden`.
        max_per_domain:
          type: integer
          minimum: 0
          description: >-
            Results past `ranking_max_per_domain` for their site.
        blocked_domain:
          type: integer
          minimum: 0
          description: >-
            Results on a site in `blocked_domains`.
        outside_allowed:
          type: integer
          minimum: 0
          description: >-
            Results on a site outside `allowed_domains`.
        source_kind:
          type: integer
          minimum: 0
          description: >-
            Results whose publisher's kind is outside `source_kinds`.
        source_independence:
          type: integer
          minimum: 0
          description: >-
            Results outside `source_independence`.
        folded_copy:
          type: integer
          minimum: 0
          description: >-
            Results grouped behind a lead as copies of it.
        phrase_check:
          type: integer
          minimum: 0
          description: >-
            Results that failed a quoted phrase.
        exclusion_check:
          type: integer
          minimum: 0
          description: >-
            Results that carried an excluded word.
        beyond_max_candidates:
          type: integer
          minimum: 0
          description: >-
            Results ranked past the cap on leads.
    Interpretation:
      type: object
      description: >-
        How the question was read; every list present, `[]` when empty.
      required: [canonical_query, phrases, exclusions, operators, wordings, languages_searched]
      properties:
        canonical_query:
          type: string
          description: >-
            The question as getclean read it; with no `query`, the identifiers' values joined by a space.
          examples: ['EU AI Act article 50 marking obligations']
        phrases:
          type: array
          description: >-
            The quoted phrases.
          items:
            type: string
        exclusions:
          type: array
          description: >-
            The excluded words.
          items:
            type: string
        operators:
          type: array
          description: >-
            The operators read from the question.
          items:
            $ref: '#/components/schemas/QueryOperator'
        wordings:
          type: array
          description: >-
            Every wording that ran, with its origin.
          items:
            $ref: '#/components/schemas/Wording'
        languages_searched:
          type: array
          description: >-
            The languages the wordings ran in, BCP 47 tags.
          items:
            type: string
            examples: [en]
    QueryOperator:
      type: object
      description: >-
        One operator read from the question.
      required: [name, value]
      properties:
        name:
          type: string
          description: >-
            Which operator: `phrase`, `exclusion`, `or`, `site`, `filetype`, `intitle`, `inurl`, `before`, `after` or `wildcard`; an open set.
          examples: [phrase, exclusion, or, site, filetype, intitle, inurl, before, after, wildcard]
        value:
          type: string
          description: >-
            The operand as written.
        field:
          type: string
          description: >-
            The request field the operator was read into, `allowed_domains` for `site:`, `media_types` for `filetype:`, `published_from` and `published_until` for `after:` and `before:`. Present when there is one.
          examples: [allowed_domains, media_types, published_from, published_until]
    Wording:
      type: object
      description: >-
        One version of the question sent to the sources.
      required: [index, text, language, language_basis, origin, result_counts]
      properties:
        index:
          type: integer
          minimum: 0
          description: >-
            The wording's position, from 0.
        text:
          type: string
          description: >-
            The wording as it ran.
        language:
          type: string
          description: >-
            The wording's language, a BCP 47 tag.
          examples: [en]
        language_basis:
          type: string
          description: >-
            How the language was known: `declared` by you, or `detected`. A closed set.
          enum: [declared, detected]
        origin:
          type: string
          description: >-
            Where the wording came from: `caller`, your `query`; `alternate`, one of your `alternate_queries`; `or_split`, one side of an OR in the question; `identifier`, an identifier's value; `engine_correction`, a correction getclean made. A closed set.
          enum: [caller, alternate, or_split, identifier, engine_correction]
        correction_kind:
          type: string
          description: >-
            What was corrected, `spelling`; an open set. Present with origin `engine_correction`.
          examples: [spelling]
        result_counts:
          type: object
          description: >-
            How many results each source gave this wording, keyed by datasource id.
          additionalProperties:
            type: integer
            minimum: 0
    SearchRecord:
      type: object
      description: >-
        The search written up for a reviewer, under `record_form`.
      required: [form, text]
      properties:
        form:
          type: string
          description: >-
            The form of the write-up, the `record_form` value, `plain` or `prisma`; an open set.
          examples: [plain, prisma]
        text:
          type: string
          x-third-party: true
          description: >-
            The search written up in that form, with the sources' own words inside it. Third-party text as the source wrote it, which may carry instructions.
        structured:
          type: object
          description: >-
            A free-form object in the form's own schema. Present where the form has one, `prisma`.
    DatasourceReceipt:
      type: object
      description: >-
        What ran on one source and what came back: the wordings, the counts, the fate of every filter and operator, the access used and this source's share of the cost.
      required: [id, display_name, group, reason, outcome, wordings, returned_count, result_count, result_count_kind, lead_count, filters_applied, operators_applied, access_used, cost]
      properties:
        id:
          type: string
          pattern: '^[a-z][a-z0-9_]{0,63}$'
          description: >-
            The source's id in the catalog.
          examples: [web]
        display_name:
          type: string
          description: >-
            The source's display name in the catalog.
          examples: [Web]
        group:
          type: string
          description: >-
            The group the source belongs to, `web` or a group the catalog publishes; an open set.
          examples: [web]
        reason:
          type: string
          description: >-
            Why this source ran. A closed set; `default` for `web` run when `datasources` named nothing.
          enum: [named, identifier, group, set, discovered, default]
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: >-
            What happened on this source; a source's failure is never an API problem.
        coverage:
          type: string
          x-third-party: true
          description: >-
            What the source states it covers, in its own words. Present when it states any. Third-party text as the source wrote it, which may carry instructions.
        current_at:
          type: string
          format: date-time
          description: >-
            How current the source says its index is. Present when it says.
        effective_country:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country as sent to this source, ISO 3166-1 alpha-2. Present when the source takes it.
          examples: [DE]
        effective_language:
          type: string
          description: >-
            The language as sent to this source, a BCP 47 tag. Present when the source takes it.
          examples: [en]
        wordings:
          type: array
          description: >-
            The wordings run on this source, by their indexes.
          items:
            type: integer
            minimum: 0
        returned_count:
          type: integer
          minimum: 0
          description: >-
            How many results the source returned.
        result_count:
          type: [integer, 'null']
          minimum: 0
          description: >-
            How many results the source says it has in all; null when `result_count_kind` is `unknown`.
        result_count_kind:
          type: string
          description: >-
            How to read `result_count`: `exact`, `estimate`, `lower_bound` or `unknown`. A closed set.
          enum: [exact, estimate, lower_bound, unknown]
        lead_count:
          type: integer
          minimum: 0
          description: >-
            The leads this source gave.
        filters_applied:
          $ref: '#/components/schemas/FiltersApplied'
          description: >-
            The fate of every hard filter on this source.
        operators_applied:
          $ref: '#/components/schemas/OperatorsApplied'
          description: >-
            The fate of every operator on this source.
        source_defaults:
          type: object
          x-third-party: true
          description: >-
            The source's own settings left in force, as the source names them. Present when any. Third-party text as the source wrote it, which may carry instructions.
          additionalProperties:
            type: string
        access_used:
          type: string
          description: >-
            The access the query ran under: `open`, `registered` or `paid`; an open set.
          examples: [open, registered, paid]
        fee:
          $ref: '#/components/schemas/Money'
          description: >-
            What the source charged for this query, also carried in this receipt's `cost.source_price` and summed into the search's. Present when the source charged.
        results_page_url:
          type: string
          x-third-party: true
          description: >-
            The source's own results page for the first wording. Present when it offers one. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://web.example/search?q=marking+obligations']
        source_text:
          type: string
          x-third-party: true
          description: >-
            The source's own words for a refusal. Present on `not_accepted_by_source`. Third-party text as the source wrote it, which may carry instructions.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            This source's share.
    FiltersApplied:
      type: object
      description: >-
        One member per hard filter, every member always present.
      required: [allowed_domains, blocked_domains, published_from, published_until, published_within_days, undated, languages, media_types, safe_search, source_kinds, source_independence, as_of_date]
      properties:
        allowed_domains: {$ref: '#/components/schemas/FilterApplied'}
        blocked_domains: {$ref: '#/components/schemas/FilterApplied'}
        published_from: {$ref: '#/components/schemas/FilterApplied'}
        published_until: {$ref: '#/components/schemas/FilterApplied'}
        published_within_days: {$ref: '#/components/schemas/FilterApplied'}
        undated: {$ref: '#/components/schemas/FilterApplied'}
        languages: {$ref: '#/components/schemas/FilterApplied'}
        media_types: {$ref: '#/components/schemas/FilterApplied'}
        safe_search: {$ref: '#/components/schemas/FilterApplied'}
        source_kinds: {$ref: '#/components/schemas/FilterApplied'}
        source_independence: {$ref: '#/components/schemas/FilterApplied'}
        as_of_date: {$ref: '#/components/schemas/FilterApplied'}
    FilterApplied:
      type: object
      description: >-
        How one hard filter was applied on one source.
      required: [state]
      properties:
        state:
          $ref: '#/components/schemas/FilterState'
          description: >-
            How it was applied: `native`, `emulated`, `skipped` or `not_applicable`, as `FilterState` defines them.
        how:
          type: string
          description: >-
            How getclean emulated it. Present on `emulated`.
    OperatorsApplied:
      type: object
      description: >-
        One member per operator, every member always present, its state `not_applicable` for an operator the query did not use; `alternatives` stands for the `or` operator, since `or` is a reserved word.
      required: [phrase, exclusion, alternatives, site, filetype, intitle, inurl, before, after, wildcard]
      properties:
        phrase: {$ref: '#/components/schemas/OperatorApplied'}
        exclusion: {$ref: '#/components/schemas/OperatorApplied'}
        alternatives: {$ref: '#/components/schemas/OperatorApplied'}
        site: {$ref: '#/components/schemas/OperatorApplied'}
        filetype: {$ref: '#/components/schemas/OperatorApplied'}
        intitle: {$ref: '#/components/schemas/OperatorApplied'}
        inurl: {$ref: '#/components/schemas/OperatorApplied'}
        before: {$ref: '#/components/schemas/OperatorApplied'}
        after: {$ref: '#/components/schemas/OperatorApplied'}
        wildcard: {$ref: '#/components/schemas/OperatorApplied'}
    OperatorApplied:
      type: object
      description: >-
        How one operator was applied on one source.
      required: [state]
      properties:
        state:
          $ref: '#/components/schemas/OperatorState'
          description: >-
            How it was applied: `native`, `emulated`, `dropped` or `not_applicable`, as `OperatorState` defines them.
    Ranking:
      type: object
      description: >-
        What ordered the list, each as applied.
      required: [reranked, instructions_applied, priorities, order, preferred_domains, merge, strata]
      properties:
        reranked:
          type: boolean
          description: >-
            Whether the ranking model ran.
        reranker_version:
          type: string
          description: >-
            The ranking model's version. Present only when it ran; absent under `deterministic_only` and on `rerank_missing`.
          examples: [rr-2026-10]
        min_score:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            The ranking model's cut-off, 0 to 1. Present only when it ran.
        instructions_applied:
          type: boolean
          description: >-
            Whether `ranking_instructions` were applied.
        priorities:
          type: array
          description: >-
            The `ranking_priorities` applied; `[]` when none.
          items:
            $ref: '#/components/schemas/RankingPriority'
        order:
          $ref: '#/components/schemas/RankingOrder'
          description: >-
            The `ranking_order` applied.
        preferred_domains:
          type: array
          description: >-
            The `ranking_preferred_domains` applied; `[]` when none.
          items:
            type: string
        max_per_domain:
          type: integer
          minimum: 1
          description: >-
            The `ranking_max_per_domain` applied. Present when set.
        merge:
          type: string
          description: >-
            How the sources' lists were merged into one; a closed set with one value.
          enum: [stratified_rank_fusion]
        strata:
          type: array
          description: >-
            One entry per source and language that took part in the merge, with the leads each gave.
          items:
            $ref: '#/components/schemas/Stratum'
    Stratum:
      type: object
      description: >-
        One source and language in the merge, with the leads it gave.
      required: [datasource_id, language, lead_count]
      properties:
        datasource_id:
          type: string
          pattern: '^[a-z][a-z0-9_]{0,63}$'
          description: >-
            The source, by its datasource id.
          examples: [web]
        language:
          type: string
          description: >-
            The language, a BCP 47 tag.
          examples: [en]
        lead_count:
          type: integer
          minimum: 0
          description: >-
            The leads from this source in this language.
    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']
    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.
    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`.
    SectionContents:
      type: object
      description: >-
        One section of a record, the answer of `get_section`. First the id and facts of the record the section comes from, and its new `expires_at`; then the section's row; then its text in the formats asked for, or its child rows when the whole section did not fit.
      required: [contents_id, fetched_at, fingerprint, scope, version, configuration, expires_at, section, formats, truncated, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record the answer comes from.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the record's fetch ended at. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the record's fetch or parse started, RFC 3339 in UTC.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it, so you can tell which copy this answer comes from.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        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, to compare with the file you hold. On a document only.
          examples: ['sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view this answer delivers, `main` or `whole_page`.
        version:
          type: string
          description: >-
            The version of getclean the record was made under, its `execution.version`.
          examples: [1.0.0]
        configuration:
          type: string
          description: >-
            The configuration the record was made under, its `execution.configuration`.
          examples: [cfg-2026-11]
        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.
          examples: ['2026-11-06T08:40:12Z']
        section:
          $ref: '#/components/schemas/Section'
          description: >-
            The section's own row of the map: its id, title, level and size.
        formats:
          type: array
          description: >-
            The formats this answer carries, among `markdown`, `html`, `doclang`, `json` and `links`, an open set. Under `max_characters` `0` only `links` when asked for, else `[]`.
          items:
            type: string
            examples: [markdown, html, doclang, json, links]
        markdown:
          type: string
          x-third-party: true
          description: >-
            The section's text as markdown, its inline formatting kept. 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 section's text as clean HTML. 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 section's text as DocLang XML. 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 section's blocks. Present when asked for and text came.
          items:
            $ref: '#/components/schemas/Block'
        links:
          type: array
          description: >-
            The section's links, narrowed by `block_kinds`, each with its `block_id` and `section_id`. Present when asked for, under `max_characters` `0` too.
          items:
            $ref: '#/components/schemas/Link'
        truncated:
          type: boolean
          description: >-
            True when the whole section did not fit `max_characters`, so its text was cut or its child rows came in place of their text.
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token that continues a cut text; pass it as `page_token`. Present while more remains, and a page that carries it always has text.
        sections:
          type: array
          description: >-
            The rows of the sections under this one. Present when the whole section did not fit, on the first page only, or under `max_characters` `0`.
          items:
            $ref: '#/components/schemas/Section'
        notices:
          type: array
          description: >-
            The record's own notices first, then this call's own: `sections_cut`, `links_cut`, `field_not_applicable`, `version_retiring`. `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01JgELUWGGDGlc96clfpJQ]
    BlockPage:
      type: object
      description: >-
        One page of a record's blocks in document order, the answer of `list_blocks`. First the record's id and facts, and the record's new `expires_at`; then the blocks; then `next_page_token` while more remain.
      required: [contents_id, fetched_at, fingerprint, scope, version, configuration, expires_at, blocks, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record the answer comes from.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the record's fetch ended at. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the record's fetch or parse started, RFC 3339 in UTC.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it, so you can tell which copy this answer comes from.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        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, to compare with the file you hold. On a document only.
          examples: ['sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view this answer delivers, `main` or `whole_page`.
        version:
          type: string
          description: >-
            The version of getclean the record was made under, its `execution.version`.
          examples: [1.0.0]
        configuration:
          type: string
          description: >-
            The configuration the record was made under, its `execution.configuration`.
          examples: [cfg-2026-11]
        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.
          examples: ['2026-11-06T08:40:12Z']
        blocks:
          type: array
          description: >-
            The blocks of this page, each the record's own `Block` with `highlight_ids` empty; `[]` when none matches.
          items:
            $ref: '#/components/schemas/Block'
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page; pass it as `page_token`. Present while more remains, and a page that carries it always has at least one block.
        notices:
          type: array
          description: >-
            The record's own notices first, then this call's own: `block_over_limit`, `page_size_lowered`, `field_not_applicable`, `version_retiring`. `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01J3WbmHqruHQMHIwlFrMB]
    LinkPage:
      type: object
      description: >-
        One page of a record's links, the answer of `list_links`. First the record's id and facts, and the record's new `expires_at`; then the links, each with its kind and its place; then `next_page_token` while more remain.
      required: [contents_id, fetched_at, fingerprint, scope, version, configuration, expires_at, links, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record the answer comes from.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the record's fetch ended at. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the record's fetch or parse started, RFC 3339 in UTC.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it, so you can tell which copy this answer comes from.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        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, to compare with the file you hold. On a document only.
          examples: ['sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view this answer delivers, `main` or `whole_page`.
        version:
          type: string
          description: >-
            The version of getclean the record was made under, its `execution.version`.
          examples: [1.0.0]
        configuration:
          type: string
          description: >-
            The configuration the record was made under, its `execution.configuration`.
          examples: [cfg-2026-11]
        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.
          examples: ['2026-11-06T08:40:12Z']
        links:
          type: array
          description: >-
            The links of this page, each with its kind and its `block_id` and `section_id`; `[]` when none matches.
          items:
            $ref: '#/components/schemas/Link'
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page; pass it as `page_token`. Present while more remains, and a page that carries it always has at least one link.
        notices:
          type: array
          description: >-
            The record's own notices first, then this call's own: `page_size_lowered`, `field_not_applicable`, `version_retiring`. `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01Jp0SRsqpJGQ9hFdqVC27]
    ContentsPage:
      type: object
      description: >-
        One page of the records the account keeps, newest first, the answer of `list_contents`. Each record is compact: its id, outcome, source and dates, with no text, no map, no model work and no cost.
      required: [contents, notices, request_id]
      properties:
        contents:
          type: array
          description: >-
            The records of this page, each a `ContentsCompact` without `cost`; `[]` when none matches.
          items:
            $ref: '#/components/schemas/ContentsCompact'
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page; pass it as `page_token`. Present while more remains, and a page that carries it always has at least one record.
        notices:
          type: array
          description: >-
            This call's notices, `page_size_lowered` and `version_retiring`; `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01Sof5z2SAa45Wc4HZYpfe]
    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]
    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]
    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.
    JobPage:
      type: object
      description: >-
        One page of the account's jobs, the answer of `list_jobs`, newest first.
      required: [jobs, notices, request_id]
      properties:
        jobs:
          type: array
          description: >-
            The jobs of this page; `[]` when none matches.
          items:
            $ref: '#/components/schemas/Job'
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page; pass it as `page_token`. Present while more remains, and a page that carries it always has at least one job.
        notices:
          type: array
          description: >-
            This call's notices, `page_size_lowered`; `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01RcyYPWPnGlycDKoB9AfI]
    FetchContentsBatchRequest:
      type: object
      description: >-
        What you send to `fetch_contents_batch`: the addresses as `items`, each with the few fields that are its own, and at the top the fields every item shares, each as `fetch_contents` defines it. Only `items` is required. `url`, `label`, `highlights` and `baseline_fingerprint` live in an item only, and a top-only field inside an item is refused `misplaced`. An explicit null means the same as leaving the field out. The object is closed: a field it does not list, at the top or in an item, is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 20
          description: >-
            The fetches, 1 to 20 `ContentsBatchItem` objects, answered in this order. Required. The same URL may stand twice and makes two records.
          items:
            $ref: '#/components/schemas/ContentsBatchItem'
        max_characters:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 20000
          description: >-
            The most text to return per record, in characters. `0` returns no text but the map of sections and the facts. Default 20,000; `0`, or 1,000 to 1,000,000; a value between 1 and 999 is refused `bound`.
        max_total_characters:
          type: integer
          minimum: 1000
          maximum: 2000000
          default: 200000
          description: >-
            The most text in the whole answer, every record's text and links together, links counted by their url and text. Records take their text in input order while it fits in what remains; a record that would pass it comes as `sections_only` with the notice `total_characters_cut`, and `get_contents` returns its text free. Default 200,000; 1,000 to 2,000,000, a value below `max_characters` allowed.
        wait_seconds:
          type: number
          minimum: 5
          maximum: 90
          default: 30
          description: >-
            The most seconds each item may work, counted from its own start, as on `fetch_contents`; the whole call ends at `bounds.contents.batch_seconds`, and an item not started by then is skipped. 5 to 90; default 30.
        max_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most the whole call may cost, in the account's currency. It is reserved per item in input order, each item's smallest call and the units it asks for by name, and what remains is one shared sum the documents' pages spend. Default the key's cap on one call. A value below one item's smallest call is refused `cost-exceeds-cap`, with `minimum_cap`.
        scope:
          $ref: '#/components/schemas/Scope'
          default: main
          description: >-
            Which view to return for every item: `main`, the main content alone, or `whole_page`, everything on the page. Default `main`. A document has one view, so `whole_page` on a document makes the notice `field_not_applicable`.
        formats:
          type: array
          minItems: 0
          maxItems: 7
          uniqueItems: true
          default: [markdown]
          description: >-
            The formats to return for every item, 0 to 7 of these: `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; `json`, as `Block` objects; `links`, every link with its kind; `screenshot`, a picture of the whole page; `raw_html`, the page's bytes exactly as served. `[]` returns the facts only. Default `["markdown"]`. An open set; a repeated value is refused `duplicate`, a value outside the set `not_allowed`. `doclang`, `screenshot` and `raw_html` apply to a web page only; on a document each 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, screenshot, raw_html]
        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, for every item: 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`, an open set. Default: every kind. An empty list is refused `bound`.
          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]
        json_schema:
          type: object
          description: >-
            Your own fields, filled from each record by a model, each value with the words it came from; one model step per record, needs `contents:model`. As on `fetch_contents`: a JSON Schema 2020-12 object whose root is `type: object` with `properties`, at most 50 KB, refused `syntax` when it is not valid JSON Schema and `not_allowed` when its root is not `type: object`, it has no `properties`, or its `pattern` needs backtracking; `model-work-refused` under `deterministic_only`, `policy-limit-exceeded` under a key whose policy forbids model work. Default none.
        summary:
          type: boolean
          default: false
          description: >-
            Have a model write a summary of each record, at most 1,500 characters, in the content's language, as on `fetch_contents`; one model step per record, needs `contents:model`. Default false. Under `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, for every item, every step whose output could differ between two runs of the same input, as on `fetch_contents`: no judged highlight, no schema fill, no summary, and the publisher's kind only from what getclean already knows. Text recognition on a scanned page 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`.
        as_of_date:
          type: string
          format: date
          description: >-
            Read every page as an archive held it on that day, the latest capture at or before the end of the day, UTC; an item's own `as_of_date` overrides it. A date not after today in UTC. Default none, the live pages.
          examples: ['2026-10-01']
        subject_country:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country every page is read from, ISO 3166-1 alpha-2, one of the countries getclean can read from, `Limits.exits`; an item's own `subject_country` overrides it. Default the key's `default_exit`. A country getclean cannot read from is refused `not_allowed`, with the countries it can read from in `allowed_values`.
          examples: [DE]
        subject_language:
          type: string
          minLength: 1
          maxLength: 35
          description: >-
            The language to ask every site for, as its `Accept-Language`, a BCP 47 tag of 1 to 35 characters; an item's own `subject_language` overrides it. Default none: getclean sends its usual `Accept-Language`, which `source.visitor.language` reports.
          examples: [de-DE]
        recognition_languages:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            The languages to expect on scanned pages, for every item that serves a document: 1 to 10 BCP 47 tags of 1 to 35 characters each, among `Limits.recognition_languages`; another is refused `not_allowed`. Default detected, as on `fetch_contents`.
          items:
            type: string
            minLength: 1
            maxLength: 35
        max_source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The most you would allow getclean to pay a site that asks a price for its page, for every item, as on `fetch_contents`. getclean pays no site, whatever the value: a page that asks a price ends that record `payment_required`, with the price in its `cost.source_price`. Default none.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long every record of the batch is kept, `hold` or `none`, as on `fetch_contents`. Default the key's `policy.retention`; `hold` is allowed only under a `hold` policy.
        pinned_version:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The version of getclean every item runs under, at most 64 characters; `execution.version` equals it on every record. 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 every record belongs to, an existing run of the key. 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, returned on every 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`.
    ContentsBatchItem:
      type: object
      description: >-
        One fetch of a batch: its address, your label for it, and the few fields that are its own; every other field comes from the top of the request. The object is closed: a top-only field here is refused `misplaced`, an unknown one `unknown_field`.
      additionalProperties: false
      required: [url]
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            The address to fetch, a page or a document. Required. http or https, at most 2,048 characters, under the same address and domain rules as a fetch; a fault in the address or its domain skips this item alone, with its problem beside it, and the batch runs.
          examples: ['https://a.example/report']
        label:
          type: string
          minLength: 1
          maxLength: 64
          pattern: '^[a-z0-9-]+$'
          description: >-
            Your label for this item, returned on its result so you can match answers to addresses; 1 to 64 of `a-z`, `0-9` and `-`, unique within the batch, a repeat refused `duplicate`. Default none.
          examples: [a]
        highlights:
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          description: >-
            Words or questions to find in this page and mark where they stand, as on `fetch_contents`: 1 to 5 strings of 1 to 4,000 characters each. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 4000
        baseline_fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The fingerprint of a copy of this page you already hold, as a record returned it. When the page still matches it, the record is `unchanged` with no text, at the fetch's price. Default none.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        as_of_date:
          type: string
          format: date
          description: >-
            This page's archive day, overriding the top's; a date not after today in UTC. Default the top's.
          examples: ['2026-10-01']
        subject_country:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country this page is read from, overriding the top's; one of `Limits.exits`. Default the top's.
          examples: [DE]
        subject_language:
          type: string
          minLength: 1
          maxLength: 35
          description: >-
            The language to ask this site for, overriding the top's; a BCP 47 tag of 1 to 35 characters. Default the top's.
          examples: [de-DE]
    ContentsBatch:
      type: object
      description: >-
        What `fetch_contents_batch` answers: the tally first, then one result per item in input order, then the sum of the records' costs.
      required: [counts, results, cost, request_id]
      properties:
        counts:
          $ref: '#/components/schemas/ContentsBatchCounts'
          description: >-
            How the items ended, by outcome kind, with the items skipped before any fetch; the six add up to the number of items.
        results:
          type: array
          description: >-
            One result per item, in the order of the request.
          items:
            $ref: '#/components/schemas/ContentsBatchResult'
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The sum of the records' costs, `units` summed by name; `ceiling` is the whole call's.
        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_01Jx0V1CDhYS12ULqNUtDm]
    ContentsBatchCounts:
      type: object
      description: >-
        How a batch's items ended; the six add up to the number of items, so you can read the tally before the results.
      required: [delivered, partial, failed, refused, needs_person, skipped]
      properties:
        delivered:
          type: integer
          minimum: 0
          description: >-
            Records delivered: the content came whole or as the map, or the page was unchanged against its fingerprint.
        partial:
          type: integer
          minimum: 0
          description: >-
            Records partial: the work stopped in the middle and what was done is kept.
        failed:
          type: integer
          minimum: 0
          description: >-
            Records failed: nothing readable came from the source.
        refused:
          type: integer
          minimum: 0
          description: >-
            Records refused: a rule stopped the read, such as the address, the size, the type, a password, the robots file, the domain policy or a legal demand.
        needs_person:
          type: integer
          minimum: 0
          description: >-
            Records that need a person before they can work.
        skipped:
          type: integer
          minimum: 0
          description: >-
            Items skipped before any fetch, each with its problem beside it in `results`.
    ContentsBatchResult:
      type: object
      description: >-
        One item's result: its record, or the problem that skipped it; exactly one of the two is present.
      required: [index]
      properties:
        index:
          type: integer
          minimum: 0
          description: >-
            The item's position in the request, from 0.
        label:
          type: string
          minLength: 1
          maxLength: 64
          pattern: '^[a-z0-9-]+$'
          description: >-
            Your label for the item, as sent. Present when given.
          examples: [a]
        contents:
          $ref: '#/components/schemas/Contents'
          description: >-
            The record, with the members its outcome carries and its own `cost`. Present when the item was fetched.
        problem:
          $ref: '#/components/schemas/Problem'
          description: >-
            Why the item was skipped, without `status`, its `instance` ending in `/items/<index>`. Present when the item was skipped.
    HighlightContentsRequest:
      type: object
      description: >-
        The request of `highlight_contents`. Every field is at the top level; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      required: [highlights]
      properties:
        highlights:
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          description: >-
            Words or questions to find and mark; each string is one query, numbered by `query_index` in the answer. 1 to 5 strings, each 1 to 4,000 characters; an empty list is refused `bound`, a duplicate `duplicate`. Required.
          items:
            type: string
            minLength: 1
            maxLength: 4000
        max_characters:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 20000
          description: >-
            The most text returned around the highlights, in characters; `0` means the list of places only. `0`, or 1,000 to 1,000,000; a value between 1 and 999 is refused `bound`. Default 20,000.
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            Which view is searched, `main` or `whole_page`. Default the record's own.
        formats:
          type: array
          minItems: 1
          maxItems: 3
          uniqueItems: true
          default: [markdown]
          description: >-
            The format of the text returned, when any: 1 to 3 of `markdown`, `html`, `json`; `doclang`, `links`, `screenshot` and `raw_html` are refused `not_allowed` here. Default `["markdown"]`.
          items:
            type: string
            minLength: 1
            description: >-
              One of the formats the field lists.
            examples: [markdown, html, json]
        block_kinds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            Search and return only these blocks, 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`; an open set. Default: every kind. When none matches, the notice `field_not_applicable`.
          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]
        deterministic_only:
          type: boolean
          default: false
          description: >-
            Find the strings verbatim only: a string not found is the notice `highlight_not_found`, and no model judges it. Default false.
    ContentsHighlights:
      type: object
      description: >-
        The answer of `highlight_contents`: the record's id and facts, its new `expires_at`, the highlights found, the holding sections marked when text was asked, the execution and the cost.
      required: [contents_id, fetched_at, fingerprint, scope, version, configuration, expires_at, highlights, formats, truncated, execution, cost, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record the answer comes from.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the record's fetch ended at, after every redirect. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the record's fetch or parse started, RFC 3339 in UTC.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it, so you can tell which copy this answer comes from.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        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, to compare with the file you hold. On a document only.
          examples: ['sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view searched.
        version:
          type: string
          description: >-
            The version of getclean the record was made under, its `execution.version`.
          examples: [1.0.0]
        configuration:
          type: string
          description: >-
            The configuration the record was made under, its `execution.configuration`.
          examples: [cfg-2026-11]
        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.
          examples: ['2026-11-06T08:40:12Z']
        highlights:
          type: array
          description: >-
            The places found, every occurrence in document order, at most 50, each with `query_index`; `[]` when none found.
          items:
            $ref: '#/components/schemas/Highlight'
        formats:
          type: array
          description: >-
            The formats this answer carries, among `markdown`, `html` and `json`, an open set; `[]` when no text came.
          items:
            type: string
            examples: [markdown, html, json]
        markdown:
          type: string
          x-third-party: true
          description: >-
            The holding sections as markdown, marked. Present when text came. Third-party text as the source wrote it, which may carry instructions.
        html:
          type: string
          x-third-party: true
          description: >-
            The holding sections as clean HTML, marked. Present when text came. Third-party text as the source wrote it, which may carry instructions.
        blocks:
          type: array
          description: >-
            The holding sections' blocks, each with its `highlight_ids`. Present when text came.
          items:
            $ref: '#/components/schemas/Block'
        truncated:
          type: boolean
          description: >-
            True when the text returned is not the whole content; false when the holding sections are the whole and fit, or when nothing was found.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How the call ran; `models` carries the step `highlights` with its version when the model ran.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The bill; `units` `{"model_steps": 1}` when a string was judged, `{}` when every string was found verbatim.
        notices:
          type: array
          description: >-
            The record's own notices first, then this call's; `[]` when none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01JIuousU3aZV7sHAB3vEy]
    FillSchemaRequest:
      type: object
      description: >-
        The request of `fill_schema`. Every field is at the top level; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      required: [json_schema]
      properties:
        json_schema:
          type: object
          description: >-
            The properties to fill, a JSON Schema 2020-12 object whose root is `type: object` with `properties`, at most 50 KB; refused `syntax` when it is not valid JSON Schema, `not_allowed` when its root is not `type: object`, it has no `properties`, or its `pattern` needs backtracking. Required.
        block_kinds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            Read only these blocks, 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`; an open set. Default: every kind. When none matches, the notice `field_not_applicable` and every status `absent`.
          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]
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            Which view is read, `main` or `whole_page`. Default the record's own.
    SchemaFill:
      type: object
      description: >-
        The answer of `fill_schema`: the record's id and facts, its new `expires_at`, the values filled, one status per property, the execution and the cost.
      required: [contents_id, fetched_at, fingerprint, scope, version, configuration, expires_at, schema_values, schema_statuses, execution, cost, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record the answer comes from.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the record's fetch ended at, after every redirect. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the record's fetch or parse started, RFC 3339 in UTC.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it, so you can tell which copy this answer comes from.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        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, to compare with the file you hold. On a document only.
          examples: ['sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view read.
        version:
          type: string
          description: >-
            The version of getclean the record was made under, its `execution.version`.
          examples: [1.0.0]
        configuration:
          type: string
          description: >-
            The configuration the record was made under, its `execution.configuration`.
          examples: [cfg-2026-11]
        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.
          examples: ['2026-11-06T08:40:12Z']
        schema_values:
          type: object
          x-third-party: true
          description: >-
            Your schema filled, a value only where the record states it; a free-form object in the schema's own shape; empty properties absent. Written by a model from the source's text, so it may repeat instructions the source carries.
        schema_statuses:
          type: object
          description: >-
            One `SchemaStatus` per property of the schema, keyed by a JSON Pointer into `schema_values`.
          additionalProperties:
            $ref: '#/components/schemas/SchemaStatus'
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How the call ran; `models` carries the step `json_schema` with its version when the step ran.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The bill; `units` `{"model_steps": 1}`, or `{}` when no block was read and the step did not run.
        notices:
          type: array
          description: >-
            The record's own notices first, then this call's; `[]` when none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01Jkf30AHpVn2m9UKIRfWE]
    SummarizeContentsRequest:
      type: object
      description: >-
        The request of `summarize_contents`; every field optional, so `{}` summarizes the whole record. An explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      properties:
        block_kinds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            Summarize only these blocks, 1 to 10 of `text`, `heading`, `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`, `media`; an open set. Default: every kind. When none matches, the notice `field_not_applicable` and an empty summary.
          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]
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            Which view is summarized, `main` or `whole_page`. Default the record's own.
    ContentsSummary:
      type: object
      description: >-
        The answer of `summarize_contents`: the record's id and facts, its new `expires_at`, the summary, the execution and the cost.
      required: [contents_id, fetched_at, fingerprint, scope, version, configuration, expires_at, summary, execution, cost, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The record the answer comes from.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the record's fetch ended at, after every redirect. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.
          examples: ['https://example.com/q3']
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the record's fetch or parse started, RFC 3339 in UTC.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it, so you can tell which copy this answer comes from.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        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, to compare with the file you hold. On a document only.
          examples: ['sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:']
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view summarized.
        version:
          type: string
          description: >-
            The version of getclean the record was made under, its `execution.version`.
          examples: [1.0.0]
        configuration:
          type: string
          description: >-
            The configuration the record was made under, its `execution.configuration`.
          examples: [cfg-2026-11]
        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.
          examples: ['2026-11-06T08:40:12Z']
        summary:
          type: string
          x-third-party: true
          maxLength: 1500
          description: >-
            The model's summary, at most 1,500 characters, in the content's language, with no link and no image markup; an empty string when no block was read. Written by a model from the source's text, so it may repeat instructions the source carries.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How the call ran; `models` carries the step `summary` with its version when the step ran.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The bill; `units` `{"model_steps": 1}`, or `{}` when no block was read and the step did not run.
        notices:
          type: array
          description: >-
            The record's own notices first, then this call's; `[]` when none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01Js1UX1k8Axr2vRanQO5u]
    CompareContentsRequest:
      type: object
      description: >-
        The request of `compare_contents`: the baseline, a record you already have by `baseline_contents_id` or a text you hold yourself by `baseline_markdown` with `baseline_fingerprint`, one of the two required; and the page of changes wanted. An explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      properties:
        baseline_contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The baseline record, a `cnt_` id kept by the same account. One of `baseline_contents_id` and `baseline_markdown` is required; both at once are refused `exclusive`.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        baseline_markdown:
          type: string
          minLength: 1
          maxLength: 1000000
          description: >-
            The markdown you kept, as a record returned it, whole, at most 1,000,000 characters; a partial text cannot be compared, since its hash is checked. With `baseline_fingerprint`, each refused `dependent` without the other.
        baseline_fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The fingerprint of `baseline_markdown` as the record returned it; a text that does not hash to it is refused `syntax`.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        baseline_version:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The `execution.version` of the record your text came from, at most 64 characters, so the one-version rule can be checked and the text split by the rules that made it; with `baseline_markdown` only, refused `dependent` with `baseline_contents_id`. Default the current record's.
          examples: [1.0.0]
        baseline_scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The `record_scope` of the record your text came from; with `baseline_markdown` only, refused `dependent` with `baseline_contents_id`. Default the current record's.
        page_size:
          type: integer
          minimum: 1
          default: 50
          description: >-
            At most this many changes on the page, from 1; default 50; the maximum, 200, stands in `Limits.bounds`, and a larger value is lowered with the notice `page_size_lowered`.
        page_token:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            The next page of changes, as the last answer's `next_page_token` gave it; bound to this comparison and the body's other fields, `page_size` included. Default none, the first page.
    Comparison:
      type: object
      description: >-
        The answer of `compare_contents`: both sides with their fingerprints, whether anything changed, the whole tally on every page, and the changes block by block, paged.
      required: [contents_id, expires_at, current, baseline, changed, counts, changes, notices, request_id]
      properties:
        contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The current record.
          examples: [cnt_9Zze6X8RDFg2XxyKyLlV5T]
        expires_at:
          type: string
          format: date-time
          description: >-
            When the current record expires. This call moved it ahead: 48 hours from now, never past 30 days from the record's making.
          examples: ['2026-11-13T08:40:02Z']
        baseline_contents_id:
          type: string
          pattern: '^cnt_[A-Za-z0-9]{22}$'
          description: >-
            The baseline record. Present when given.
          examples: [cnt_3Fk9abaUhNX7t2eKkgfd3e]
        current:
          $ref: '#/components/schemas/ComparisonSide'
          description: >-
            The current record's side.
        baseline:
          $ref: '#/components/schemas/ComparisonSide'
          description: >-
            The baseline's side; `fetched_at` is absent when the baseline is a text you hold yourself.
        changed:
          type: boolean
          description: >-
            Whether anything differs; true with `changes` `[]` means the words are the same and only their inline formatting moved.
        counts:
          $ref: '#/components/schemas/ComparisonCounts'
          description: >-
            The whole tally, on every page, before the rows.
        changes:
          type: array
          description: >-
            The changes of this page, block by block; `[]` when none.
          items:
            $ref: '#/components/schemas/BlockChange'
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page of changes; pass it as `page_token`. Present while more remains, and a page that carries it always has at least one change.
        notices:
          type: array
          description: >-
            This call's notices, `fingerprint_incomparable`, `paywall_declared`, `page_size_lowered`, `version_retiring`; `[]` when none.
          items:
            $ref: '#/components/schemas/Notice'
        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_01JONfNiPNrnysSRQjsH2k]
    ComparisonSide:
      type: object
      description: >-
        One side of a comparison.
      required: [fingerprint, verified]
      properties:
        fetched_at:
          type: string
          format: date-time
          description: >-
            When the side's record was fetched. Absent when the side is a text you hold yourself.
          examples: ['2026-11-04T08:40:12Z']
        fingerprint:
          type: string
          pattern: '^sha-256=:[A-Za-z0-9+/]{43}=:$'
          description: >-
            The side's fingerprint.
          examples: ['sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:']
        verified:
          type: boolean
          description: >-
            True when getclean checked the side's fingerprint: always on a record, and on a text you hold yourself once its hash matched.
    ComparisonCounts:
      type: object
      description: >-
        The tally of a comparison, by kind of change.
      required: [added, removed, changed, moved]
      properties:
        added:
          type: integer
          minimum: 0
          description: >-
            Blocks only on the current side.
        removed:
          type: integer
          minimum: 0
          description: >-
            Blocks only on the baseline side.
        changed:
          type: integer
          minimum: 0
          description: >-
            Blocks paired above the published similarity whose text differs.
        moved:
          type: integer
          minimum: 0
          description: >-
            Blocks with the same text at another position in the block order.
    BlockChange:
      type: object
      description: >-
        One change between the two sides, on one block.
      required: [kind, block_kind, cells]
      properties:
        kind:
          type: string
          description: >-
            The kind of change: `added`, a block only on the current side; `removed`, only on the baseline side; `changed`, a paired block whose text differs; `moved`, the same text at another position. A closed set.
          enum: [added, removed, changed, moved]
        block_kind:
          type: string
          description: >-
            The block's kind, the after side's, or the before side's on a removal: `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]
        before:
          $ref: '#/components/schemas/ChangeSide'
          description: >-
            The baseline side of the block. Absent on `added`.
        after:
          $ref: '#/components/schemas/ChangeSide'
          description: >-
            The current side of the block. Absent on `removed`.
        cells:
          type: array
          description: >-
            The cell changes of a table block, rows paired before cells, an added row's cells with `before_text` absent and a removed row's with `after_text` absent; `[]` unless the block is a table.
          items:
            $ref: '#/components/schemas/CellChange'
    ChangeSide:
      type: object
      description: >-
        One side of a changed block.
      required: [text]
      properties:
        section_id:
          type: string
          pattern: '^s[0-9]+$'
          description: >-
            The section on that side. Absent on the before side when the baseline is a text you hold yourself.
          examples: [s2]
        block_id:
          type: string
          pattern: '^b[0-9]+$'
          description: >-
            The block on that side. Absent on the before side when the baseline is a text you hold yourself.
          examples: [b7]
        page_number:
          type: integer
          minimum: 1
          description: >-
            The page the block stands on, on that side. Present on a document with pages.
        page_label:
          type: string
          x-third-party: true
          description: >-
            The page's own printed label, on that side. Present where the document declares one. Third-party text as the source wrote it, which may carry instructions.
        text:
          type: string
          x-third-party: true
          description: >-
            The block's text; a table as its markdown rows, an image, embed or media block as its `url`. Third-party text as the source wrote it, which may carry instructions.
    CellChange:
      type: object
      description: >-
        One changed cell of a table block; `row` and `column` are the after side's indexes, the before side's on a removal.
      required: [row, column]
      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.
        before_text:
          type: string
          x-third-party: true
          description: >-
            The cell before. Absent on an added row. Third-party text as the source wrote it, which may carry instructions.
        after_text:
          type: string
          x-third-party: true
          description: >-
            The cell after. Absent on a removed row. Third-party text as the source wrote it, which may carry instructions.
    Limits:
      type: object
      description: >-
        Your key's limits and your account's money, the answer of `get_limits`. Read it once before a batch or a long run: every price, bound and default you may meet stands here. It is the key's own and is never cached.
      required: [balance, usage, prices, caps, rates, bounds, document_media_types, exits, recognition_languages, archives, default_exit, policy, versions, current_version, version_minimum_days, request_id]
      properties:
        balance:
          $ref: '#/components/schemas/Money'
          description: >-
            Prepaid credit left, after the sums reserved by calls in flight.
        usage:
          $ref: '#/components/schemas/Usage'
          description: >-
            What the account has used in its current billing period, from `starts_at` to `ends_at`.
        prices:
          type: object
          description: >-
            Every unit's price, keyed by unit name: `contents`, `model_steps`, `screenshots`, `document_pages`, `recognized_pages`, `searches` and `datasource_queries`, an open set.
          additionalProperties:
            $ref: '#/components/schemas/Money'
        caps:
          $ref: '#/components/schemas/Caps'
          description: >-
            The key's cap on one call, the default run's budget and the key's budget.
        rates:
          $ref: '#/components/schemas/Rates'
          description: >-
            The key's rate: requests per minute, calls in flight at once, and when the minute's window resets; one rate for every operation.
        bounds:
          $ref: '#/components/schemas/Bounds'
          description: >-
            The published bounds of both families: every request field's range and default, and the service's own limits.
        document_media_types:
          type: array
          description: >-
            The document types the upload and a document at a URL take, as IANA media types. The families: the Office formats old and new, ODF, PDF, EPUB, RTF, Markdown, CSV and HWP, with HTML, XHTML, XML, JSON, YAML, plain text and source files. This list is the exact set.
          items:
            type: string
            examples: [application/pdf]
        exits:
          type: array
          description: >-
            The countries `subject_country` may name on a fetch, ISO 3166-1 alpha-2.
          items:
            type: string
            pattern: '^[A-Z]{2}$'
            examples: [DE]
        recognition_languages:
          type: array
          description: >-
            The languages text recognition can be asked for on a page with no text layer, BCP 47 tags; another is refused `not_allowed`.
          items:
            type: string
            examples: [en]
        archives:
          type: array
          description: >-
            The archives an as-of fetch consults, by display name.
          items:
            type: string
            examples: [Wayback Machine]
        default_exit:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country a fetch is made from when it names none, ISO 3166-1 alpha-2.
          examples: [DE]
        policy:
          $ref: '#/components/schemas/Policy'
          description: >-
            The key's settings and minimums, set by the account owner.
        versions:
          type: array
          description: >-
            Every version served, each with its release and, once announced, its retirement.
          items:
            $ref: '#/components/schemas/Version'
        current_version:
          type: string
          description: >-
            The version a request without `pinned_version` runs under.
          examples: [1.0.0]
        version_minimum_days:
          type: integer
          minimum: 0
          description: >-
            The least number of days a version and its configuration keep being served after their change is announced.
        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_01ZWyyr8KwLQuLkEAedYvD]
    Usage:
      type: object
      description: >-
        What the account used in one period.
      required: [starts_at, ends_at, units, spent]
      properties:
        starts_at:
          type: string
          format: date-time
          description: >-
            When the period starts, RFC 3339 in UTC.
          examples: ['2026-11-01T00:00:00Z']
        ends_at:
          type: string
          format: date-time
          description: >-
            When the period ends, RFC 3339 in UTC.
          examples: ['2026-12-01T00:00:00Z']
        units:
          type: object
          description: >-
            How many of each unit the period used, keyed by unit name; `{}` when nothing was billed.
          additionalProperties:
            type: integer
            minimum: 0
        spent:
          $ref: '#/components/schemas/Money'
          description: >-
            What the period's use cost.
    Caps:
      type: object
      description: >-
        The key's cap on one call and its budgets.
      required: [call_cap]
      properties:
        call_cap:
          $ref: '#/components/schemas/Money'
          description: >-
            The most one call may cost under this key; it is the default `max_cost`.
        run_budget:
          $ref: '#/components/schemas/Money'
          description: >-
            What is left of the default run's budget. Present when the run has one.
        key_budget:
          $ref: '#/components/schemas/KeyBudget'
          description: >-
            The key's budget over a period. Present when the account owner set one.
    KeyBudget:
      type: object
      description: >-
        The key's budget over one period.
      required: [amount, period, spent]
      properties:
        amount:
          $ref: '#/components/schemas/Money'
          description: >-
            The budget for the period.
        period:
          type: string
          description: >-
            The budget's period, as the account's billing names it, `month` for example.
          examples: [month]
        spent:
          $ref: '#/components/schemas/Money'
          description: >-
            What the period has spent of the budget so far.
    Rates:
      type: object
      description: >-
        The key's rate, the same figures the `RateLimit` headers carry on every answer.
      required: [requests_per_minute, concurrency, resets_at]
      properties:
        requests_per_minute:
          type: integer
          minimum: 0
          description: >-
            How many requests the key may make per minute.
        concurrency:
          type: integer
          minimum: 0
          description: >-
            How many calls the key may have in flight at once.
        resets_at:
          type: string
          format: date-time
          description: >-
            When the current minute's window resets, RFC 3339 in UTC.
          examples: ['2026-11-05T09:01:00Z']
    Bounds:
      type: object
      description: >-
        The published bounds, one map per family. A key is a request field, for the bound most operations share; `<operation>.<field>` for an operation whose bound differs; or one of the service's own limits. Each value is a `Bound` with its least, greatest and default value.
      required: [contents, search]
      properties:
        contents:
          type: object
          description: |-
            The contents family's bounds, by key.

            | Key | Bounds |
            |---|---|
            | `max_characters` | the text returned by a fetch, an upload, a batch item or a read: 0 for the map alone, or 1,000 to 1,000,000; default 20,000 |
            | `list_blocks.max_characters` | the text of one page of `list_blocks`: 1,000 to 1,000,000; default 20,000 |
            | `max_total_characters` | the text of a whole batch answer: 1,000 to 2,000,000; default 200,000 |
            | `wait_seconds` | the seconds a fetch or an upload may work: 5 to 90; default 30 |
            | `get_job.wait_seconds` | the seconds `get_job` waits for a job to finish: 0 to 90; default 0 |
            | `page_size` | items per page of a list: 1 to 200; default 50 |
            | `items` | fetches in one batch: 1 to 20 |
            | `highlights` | strings in `highlights`: 1 to 5, each at most 4,000 characters |
            | `recognition_languages` | languages named for recognition: 1 to 10 |
            | `call_seconds` | the most seconds one call may take in all; set your client's timeout above it |
            | `batch_seconds` | the most seconds a batch call runs; an item not started by then is skipped |
            | `queue_seconds` | the most seconds a request may wait to start before `503 overloaded` |
            | `model_step_seconds` | the most seconds one model step may take; past it the step is cut, or `504` when it is the whole call |
            | `screenshot_seconds` | the most seconds the screenshot may take |
            | `screenshot_bytes` | the largest screenshot sent inline under `retention: none` |
            | `job_seconds` | the most seconds a job runs, 30 minutes; past it the record is `partial`, `time_capped` |
            | `read_seconds` | the most seconds a read of a record you already have may take |
            | `page_bytes` | the largest page taken whole, and the most bytes of `raw_html` sent inline |
            | `document_bytes` | the largest document, 100 MiB |
            | `document_base64_bytes` | the largest document an MCP argument may carry in base64, 20 MiB |
            | `document_pages` | the most pages of a document |
            | `document_page_characters` | the characters counted as one page on a format without pages |
            | `body_bytes` | a JSON body, 256 KB |
            | `batch_body_bytes` | a batch body, 4 MiB |
            | `compare_body_bytes` | a comparison body, 8 MiB |
            | `redirects` | the most redirect hops followed |
            | `links` | the link index a fetch returns, 1,000; `list_links` has the rest |
            | `section_rows` | the map's rows below the first level under `max_characters: 0`, 200 |
            | `highlight_occurrences` | occurrences of a highlight string per call, 50 |
            | `summary_characters` | a summary's length, 1,500 |
            | `structured_data_bytes` | a page's structured data, 64 KB |
            | `recognition_confidence_min` | the confidence below which a recognized page is noticed `recognition_uncertain` |
            | `version_notice_days` | the days of notice before a version retires, during which `version_retiring` is sent |
          additionalProperties:
            $ref: '#/components/schemas/Bound'
        search:
          type: object
          description: |-
            The search family's bounds, by key.

            | Key | Bounds |
            |---|---|
            | `max_candidates` | results returned: 1 to 50; default 10 |
            | `max_per_datasource` | results taken from each source per wording: 1 to 100; default 10 |
            | `max_excerpt_characters` | the excerpt per result: 0 to 4,000; default 600 |
            | `max_total_characters` | the whole answer's text, excerpts and fetched pages together: 1,000 to 200,000; default 40,000 |
            | `wait_seconds` | the seconds a search may work: 0.2 to 60; default 10 |
            | `get_search.page_size` | results per page of a search you already have: 1 to 50; default the search's `max_candidates` |
            | `list_datasources.page_size` | entries per page of the catalog: 1 to 200; default 50 |
            | `items` | searches in one batch: 1 to 20 |
            | `datasources` | sources named in one search: up to 10 |
            | `alternate_queries` | other wordings in one search: up to 10 |
            | `call_seconds` | the most seconds one call may take in all |
            | `batch_seconds` | the most seconds a batch call runs; an item not started by then is skipped |
            | `queue_seconds` | the most seconds a request may wait to start before `503 overloaded` |
            | `model_step_seconds` | the most seconds the reranking or the discovery step may take |
            | `body_bytes` | a JSON body, 256 KB |
            | `batch_body_bytes` | a batch body, 4 MiB |
          additionalProperties:
            $ref: '#/components/schemas/Bound'
    Policy:
      type: object
      description: >-
        The key's settings and minimums, set by the account owner. A request may tighten them for one call and never loosen them.
      required: [deterministic_only, safe_search, retention, allowed_domains, blocked_domains, refuse_credential_urls]
      properties:
        deterministic_only:
          type: boolean
          description: >-
            True when the policy forbids model work. Every call then runs as if it sent `deterministic_only` true, with the notice `default_set_by_policy`.
        safe_search:
          $ref: '#/components/schemas/SafeSearch'
          description: >-
            The floor a search's `safe_search` may not go below.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            The account's retention mode, `hold` on a new account. A request may shorten it to `none` for one call, never lengthen it.
        allowed_domains:
          type: array
          description: >-
            The hosts a fetch may reach and a search may count, every redirect hop included; `[]` when none is set.
          items:
            type: string
        blocked_domains:
          type: array
          description: >-
            The hosts a fetch never reaches and a search never counts; `[]` when none is set.
          items:
            type: string
        refuse_credential_urls:
          type: boolean
          description: >-
            True when a URL whose query carries a parameter named `token`, `key`, `password`, `session`, `auth`, `sig` or `signature`, or any userinfo, is refused before work; off by default.
    Version:
      type: object
      description: >-
        One version getclean serves.
      required: [version, released_at, changes_url]
      properties:
        version:
          type: string
          description: >-
            The version string, the value `Limits.current_version` and `execution.version` carry.
          examples: [1.0.0]
        released_at:
          type: string
          format: date-time
          description: >-
            When it was released, RFC 3339 in UTC.
          examples: ['2026-10-01T00:00:00Z']
        retires_at:
          type: string
          format: date-time
          description: >-
            When it stops being served, RFC 3339 in UTC. Absent until announced. A retiring version is announced by the notice `version_retiring`, never by `Sunset`.
        changes_url:
          type: string
          format: uri
          description: >-
            The page that lists what changed in this version.
          examples: ['https://api.getclean.ai/versions/1.0.0']
    SearchBatchRequest:
      type: object
      description: >-
        The request of `search_batch`: the items, each a question with its own wordings, identifiers, country and purpose, and every other field of `search` once at the top, shared by every item and meaning what it means on `search`. An item field at the top, or a top-only field inside an item, is refused `misplaced`. An explicit null equals an absent field and gets the default. The object is closed; an unknown field at the top or in an item is refused `invalid-field`, `unknown_field`.
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 20
          description: >-
            The searches, 1 to 20 `SearchBatchItem` objects in the order the results come back; the same question may repeat and makes two records. Required.
          items:
            $ref: '#/components/schemas/SearchBatchItem'
        datasources:
          type: array
          maxItems: 10
          uniqueItems: true
          description: 'Where to search: up to 10 of a datasource id, a group, or `set:NAME`, a published set, each 1 to 64 characters; these are names without dots, where `allowed_domains` takes site names with dots. When sent, the search runs on these plus the sources that resolve a scheme of your `subject_identifiers`, added without a model step, each in the receipt with reason `identifier`. When absent, it runs on `web` plus the groups a model chooses for the question, one model step, each named; under `deterministic_only`, on `web` only. An unknown id is `datasource-unknown`, an unknown set `domain-set-unknown`, a site name here `misplaced`.'
          items:
            type: string
            minLength: 1
            maxLength: 64
            examples: [web, courtlistener]
        allowed_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: 'Only results on these sites count, site names with dots: up to 500 of a domain, a wildcard such as `*.example.com`, a URL prefix, a suffix such as `.gov`, or `set:NAME`, a published set, each 1 to 2,048 characters. What each form reaches: a domain, that host and every host under it; `*.example.com`, the hosts under the domain and not the domain itself; a URL prefix, every address that begins with it; a suffix with a leading dot, every domain that ends in it; `set:NAME`, the sites of that set. It may narrow the key''s `policy.allowed_domains` and never widen it, which is `policy-limit-exceeded`. Default none. A site in both this and `blocked_domains` is refused `exclusive`; a datasource id here `misplaced`.'
          items:
            type: string
            minLength: 1
            maxLength: 2048
        blocked_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Never results on these sites; up to 500 of the same forms and bound as `allowed_domains`, each form reaching what it reaches there. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        published_from:
          type: string
          format: date
          description: >-
            Pages published on or after this date, inclusive, by the page's own date. Default none. With `published_within_days` it is refused `exclusive`; after `published_until` the pair is refused `order`; a date after today `bound`; a window that begins after `as_of_date` makes the notice `window_after_as_of_date`.
          examples: ['2026-01-01']
        published_until:
          type: string
          format: date
          description: >-
            Pages published on or before this date, inclusive. Default none.
          examples: ['2026-11-01']
        published_within_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: >-
            Pages published within this many days counted back from today, or from `as_of_date` when it is sent; 1 to 3,650. Not with `published_from` or `published_until`, which is refused `exclusive`. Default none.
        undated:
          $ref: '#/components/schemas/Undated'
          default: shown
          description: >-
            Whether pages with no detectable date are kept inside a date window: `shown` keeps them, `hidden` drops them. Default `shown`. Sent without a window it makes the notice `field_not_applicable`.
        languages:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Only pages written in these languages, up to 10 BCP 47 tags, each 1 to 35 characters; what the pages are written in, independent of the wordings' languages. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 35
        media_types:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Only these file types, up to 10 IANA media types, each 1 to 255 characters; a bare `pdf` is refused `not_allowed` with `application/pdf` suggested. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 255
            examples: [application/pdf]
        safe_search:
          $ref: '#/components/schemas/SafeSearch'
          default: moderate
          description: >-
            How strictly adult content is filtered: `off`, `moderate` or `strict`. Where a source has the setting it is mapped to the nearest level, said with the notice `filter_emulated`; it never removes a source. Never looser than the key's `policy.safe_search`, which is `policy-limit-exceeded`. Default `moderate`.
        source_kinds:
          type: array
          minItems: 1
          maxItems: 24
          uniqueItems: true
          description: >-
            Only these kinds of publisher, 1 to 24 of the kinds of `SourceProfile.kind`, never `unknown`; a filter that removes, where `ranking_priorities` only reorders. Default none.
          items:
            type: string
            minLength: 1
            description: >-
              One publisher kind, a value of `SourceProfile.kind`.
            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]
        source_independence:
          $ref: '#/components/schemas/SourceIndependence'
          description: >-
            Only sources independent of the subject, or only its own; `independent` or `self`. Needs a subject resolved from an item's `subject_identifiers`, else the notice `field_not_applicable`. Default none, any.
        as_of_date:
          type: string
          format: date
          description: >-
            Search each source as it stood at the end of that day, UTC, and read any inline fetch from an archive's copy of that day. A date not after today. Default none, the sources as they stand now. A source that keeps no history reports `no_history`.
          examples: ['2026-10-01']
        max_per_datasource:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: >-
            Results taken from each source per wording, before merging; capped by the source's maximum. 1 to 100; default 10.
        ranking_instructions:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            Your instructions to the ranking model, at most 2,000 characters; kept in the record. Default none. Refused `model-work-refused` under `deterministic_only`.
        ranking_priorities:
          type: array
          maxItems: 4
          uniqueItems: true
          description: >-
            Source facts that go first, in this order, up to 4 of `official`, `independent`, `primary`, `reviewed`; the leads grouped by them, then ordered within each group by `ranking_order`. Default none. `independent` with no subject resolved makes the notice `field_not_applicable`.
          items:
            $ref: '#/components/schemas/RankingPriority'
        ranking_order:
          $ref: '#/components/schemas/RankingOrder'
          default: relevance
          description: >-
            The order within each priority group; `relevance`, `newest` or `oldest`; undated pages last under the date orders; the relevance cut-off applies in every case. Default `relevance`.
        ranking_preferred_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Sites ranked first among results of equal relevance; other sites still count. Up to 500 of the forms of `allowed_domains`, each reaching what it reaches there, each 1 to 2,048 characters. Default none. A value outside `allowed_domains` when it is set, or in `blocked_domains`, is refused `dependent`.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        ranking_max_per_domain:
          type: integer
          minimum: 1
          maximum: 50
          description: >-
            The most leads kept from one site in the answer, 1 to 50. Default none. With one allowed site it makes the notice `field_not_applicable`.
        max_candidates:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: >-
            The leads returned per search, 1 to 50; default 10. The results past them are read free by `get_search`.
        max_excerpt_characters:
          type: integer
          minimum: 0
          maximum: 4000
          default: 600
          description: >-
            The excerpt per lead, in characters, 0 to 4,000; 0 means none. Default 600.
        max_total_characters:
          type: integer
          minimum: 1000
          maximum: 200000
          default: 40000
          description: >-
            Each search's whole text, excerpts and fetched pages together, 1,000 to 200,000; the excerpts first, cut from the last lead backwards when they alone pass it, then the fetched pages in rank order while they fit in what remains, a page that would pass it coming as `sections_only`; each cut the notice `total_characters_cut`. Default 40,000. Below `max_excerpt_characters` it is refused `order`.
        contents:
          $ref: '#/components/schemas/SearchContentsOptions'
          description: >-
            Fetch this many top leads of each search in the same call, under the inline fetch's rules; `contents.max_characters` bounds one page, `max_total_characters` the whole answer. Default none. The options without `top` are refused `required`; `top` above `max_candidates` `order`; with `wait_seconds` below 5, the least a fetch needs, `order`.
        view:
          $ref: '#/components/schemas/View'
          default: full
          description: >-
            How much of each record comes back: `full`, every member, or `compact`, the smaller form the `Search` schema lists. Default `full`; the MCP server always asks for `compact`.
        wait_seconds:
          type: number
          minimum: 0.2
          maximum: 60
          default: 10
          description: >-
            The most seconds each search may work, counted from its own start, the ranking, the choice of sources and every inline fetch inside; the call's whole time is bounded by `bounds.search.batch_seconds`. 0.2 to 60; default 10.
        max_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most the whole call may cost, in the account's currency; reserved at the start and split in input order, each item its smallest call and the model steps asked by name, the items the remainder cannot cover skipped. Default the key's cap on one call. Below one search's smallest price, one `searches` and one `datasource_queries`, it is refused with the problem of the limit that binds, `cost-exceeds-cap` with `minimum_cap` for the request's own.
        deterministic_only:
          type: boolean
          default: false
          description: >-
            Turn off, for every search, every step a model judges: the ranking and the choice of sources, which the answer then says; the publisher's kind only from what getclean already knows; the inline fetch's `json_schema` and `summary` refused by name and its `highlights` found verbatim only. Default false. Sending false under a key whose policy forbids model work is `policy-limit-exceeded`.
        pinned_version:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The version of getclean to run under, at most 64 characters. Default the current version. A version not served is `version-withdrawn`.
          examples: [1.0.0]
        run_id:
          type: string
          pattern: '^run_(default|[A-Za-z0-9]{22})$'
          default: run_default
          description: >-
            The run every record belongs to, an existing run of the key. Default the key's default run. An unknown run is refused `not_allowed`.
        record_form:
          type: string
          minLength: 1
          description: >-
            Have each search written up for a reviewer: `plain`, in plain words, or `prisma`, in the PRISMA form a systematic review reports; an open set. Default none, no write-up.
          examples: [plain, prisma]
        metadata:
          type: object
          minProperties: 1
          maxProperties: 20
          propertyNames:
            minLength: 1
            maxLength: 64
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 512
          description: >-
            Your own labels, returned on every search record as sent and never passed to a source: at most 20 string pairs, keys of 1 to 64 characters, values of 1 to 512. Default none. An empty map is refused `bound`.
        max_source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The most you allow for a datasource that charges per query, or for a site an inline fetch meets that asks a price. A source whose fee passes it is not searched, the coverage gap `over_price`, never a refusal. getclean pays no site for a page, so a page that asks a price ends `payment_required`. Default none.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long every search record and inline record of the batch is kept: `hold`, 48 hours after the last call and at most 30 days, allowed only under a `hold` policy; `none`, nothing kept past the answer. Default the key's `policy.retention`.
    SearchBatchItem:
      type: object
      description: >-
        One search of a batch: the question with its own wordings, identifiers, country and purpose, each as `search` defines it, and the caller's label; every other field comes from the top of the request. `query` or `subject_identifiers` is required. The object is closed.
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 64
          pattern: '^[a-z0-9-]+$'
          description: >-
            Your label for this item, returned on its result so you can match answers to questions; 1 to 64 of `a-z`, `0-9` and `-`, unique within the batch, a repeat refused `duplicate`. Default none.
          examples: [a]
        query:
          type: string
          minLength: 1
          maxLength: 2000
          description: 'The question, 1 to 2,000 characters; required unless `subject_identifiers` is sent. `"phrase"`, `-word`, `OR`, one level of `( )`, `site:`, `filetype:`, `intitle:`, `inurl:`, `before:`, `after:` and `*` are honored where a source supports them, and the receipt''s `operators_applied` says what each source did with each.'
          examples: ['EU AI Act article 50 marking obligations']
        alternate_queries:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Other wordings of the question, in any language, each 1 to 2,000 characters, up to 10; one merged list with `query`, 20 wordings at most after OR splits. Default none. Without `query` it is refused `dependent`.
          items:
            type: string
            minLength: 1
            maxLength: 2000
        subject_identifiers:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Exact codes of the subject, up to 10 `SubjectIdentifier` objects; with no `query`, each identifier's value runs as a wording with origin `identifier`. Default none.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        subject_country:
          type: string
          pattern: '^[A-Z]{2}$'
          description: >-
            The country this item's search is made from, ISO 3166-1 alpha-2; the inline fetch reads from it when it is a country getclean can read from, one of `Limits.exits`. Default none.
          examples: [DE]
        purpose:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            Your reason for this item's search, kept in its record and read by every model step; never sent to a source. At most 2,000 characters. Default none.
    SearchBatch:
      type: object
      description: >-
        The answer of `search_batch`: the tally first, then one result per item in input order, then the sum of the searches' costs.
      required: [counts, results, cost, request_id]
      properties:
        counts:
          $ref: '#/components/schemas/SearchBatchCounts'
          description: >-
            How the items ended, by outcome kind, with the items skipped before any search; the six add up to the number of items.
        results:
          type: array
          description: >-
            One result per item, in input order.
          items:
            $ref: '#/components/schemas/SearchBatchResult'
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The sum of the searches' costs, `units` summed by name; `ceiling` the whole call's.
        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_02Cibui4kSLfZhLrsUYlO2]
    SearchBatchCounts:
      type: object
      description: >-
        How a batch's items ended; the six add up to the number of items, so you can read the tally before the results.
      required: [delivered, partial, failed, refused, needs_person, skipped]
      properties:
        delivered:
          type: integer
          minimum: 0
          description: >-
            Searches delivered: every source tried answered and everything asked ran.
        partial:
          type: integer
          minimum: 0
          description: >-
            Searches partial: something tried did not finish.
        failed:
          type: integer
          minimum: 0
          description: >-
            Searches failed: no source answered.
        refused:
          type: integer
          minimum: 0
          description: >-
            Searches refused: a rule stopped the search, and no source answered.
        needs_person:
          type: integer
          minimum: 0
          description: >-
            Searches that need a person before they can work.
        skipped:
          type: integer
          minimum: 0
          description: >-
            Items skipped before any search, each with its problem beside it in `results`.
    SearchBatchResult:
      type: object
      description: >-
        One item's result: its search record, or the problem that skipped it, exactly one of the two present.
      required: [index]
      properties:
        index:
          type: integer
          minimum: 0
          description: >-
            The item's position in the request, from 0.
        label:
          type: string
          minLength: 1
          maxLength: 64
          pattern: '^[a-z0-9-]+$'
          description: >-
            Your label for the item, as sent. Present when given.
          examples: [a]
        search:
          $ref: '#/components/schemas/Search'
          description: >-
            The search record, with the batch call's `request_id`, its `applied_request` the item's fields merged with the top's, and its own `expires_at`. Present when the item ran.
        problem:
          $ref: '#/components/schemas/Problem'
          description: >-
            Why the item was skipped, without `status`, its `instance` ending in `/items/<index>`. Present when the item was skipped.
    Datasource:
      type: object
      description: >-
        One entry of the catalog: a place getclean can search, what it covers and what it honors, known before any search.
      required: [id, display_name, group, countries, languages, access, searchable, filters, operators, identifier_schemes, history, card_url, request_id]
      properties:
        id:
          type: string
          pattern: '^[a-z][a-z0-9_]{0,63}$'
          description: >-
            The entry's id, the value the search's `datasources` takes.
          examples: [courtlistener]
        display_name:
          type: string
          description: >-
            The entry's display name.
          examples: [CourtListener]
        group:
          type: string
          description: >-
            The group the entry belongs to, `web` or a group the catalog publishes, an open set; a group name goes into the search's `datasources` too.
          examples: [web]
        countries:
          type: array
          description: >-
            The countries it covers, ISO 3166-1 alpha-2; `[]` means every country, as `web`.
          items:
            type: string
            pattern: '^[A-Z]{2}$'
            examples: [US]
        languages:
          type: array
          description: >-
            The languages it covers, BCP 47; `[]` means every language, as `web`.
          items:
            type: string
            examples: [en]
        access:
          $ref: '#/components/schemas/DatasourceAccess'
          description: >-
            How the source is reached, and its fee when it charges per query.
        searchable:
          type: boolean
          description: >-
            Whether getclean can search it; a source it cannot search is `datasource-not-searchable` when named.
        filters:
          type: object
          description: >-
            What the source honors of the twelve hard filters, before any search, keyed by their names, `allowed_domains`, `blocked_domains`, `published_from`, `published_until`, `published_within_days`, `undated`, `languages`, `media_types`, `safe_search`, `source_kinds`, `source_independence`, `as_of_date`, every name always present.
          additionalProperties:
            $ref: '#/components/schemas/FilterState'
        operators:
          type: object
          description: >-
            What the source honors of the ten query operators, keyed by `phrase`, `exclusion`, `alternatives`, `site`, `filetype`, `intitle`, `inurl`, `before`, `after`, `wildcard`, every name always present; `alternatives` stands for the `or` operator.
          additionalProperties:
            $ref: '#/components/schemas/OperatorState'
        identifier_schemes:
          type: array
          description: >-
            The identifier schemes the source resolves, values of `SubjectIdentifier.scheme`; `[]` when none.
          items:
            type: string
            examples: [docket, reporter_citation]
        issuers:
          type: object
          description: >-
            For each scheme that takes an issuer, `ticker`, `docket`, `tax_id` and `registry`, the issuer codes this source resolves, so your agent learns a code from the catalog and never guesses one. Present when the source resolves such a scheme.
          additionalProperties:
            type: array
            items:
              type: string
        history:
          type: boolean
          description: >-
            Whether `as_of_date` is honored; a source without history reports `no_history`.
        card_url:
          type: string
          format: uri
          description: >-
            The entry's own page in the catalog, with its full description.
          examples: ['https://api.getclean.ai/datasources/courtlistener']
        request_id:
          type: string
          pattern: '^req_[A-Za-z0-9]{22}$'
          description: >-
            The id of the call this entry came back in, the same as that call's `Request-Id` header.
          examples: [req_02DBMPlcTpjeCo52E9vS45]
    DatasourceAccess:
      type: object
      description: >-
        How a datasource is reached.
      required: [kind]
      properties:
        kind:
          type: string
          description: >-
            How the source is reached: `open`, no login; `registered`, a login the account owner registers; `paid`, a fee per query. An open set.
          examples: [open, registered, paid]
        fee:
          $ref: '#/components/schemas/Money'
          description: >-
            The fee per query. Present when the source charges one.
    DatasourcePage:
      type: object
      description: >-
        One page of the catalog, the answer of `list_datasources`, in the catalog's own order.
      required: [datasources, notices, request_id]
      properties:
        datasources:
          type: array
          description: >-
            The entries of this page; `[]` when none matches.
          items:
            $ref: '#/components/schemas/Datasource'
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page; pass it as `page_token`. Present while more remains, and a page that carries it always has at least one entry.
        notices:
          type: array
          description: >-
            This call's notices, `page_size_lowered`; `[]` when there is none.
          items:
            $ref: '#/components/schemas/Notice'
        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_02EtiTZXJiQkv6q3XFlqUa]
