Skip to main content
POST
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.

Authorizations

Authorization
string
header
required

An API key from https://app.getclean.ai, or an access token issued by https://auth.getclean.ai/realms/getclean, sent as Authorization: Bearer <key> on every call. The scopes a key carries and what a 401 and a 403 say are on the keys and sign-in page.

Headers

Idempotency-Key
string
required

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.

Required string length: 1 - 255
Pattern: ^[!-~]{1,255}$
traceparent
string

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.

Body

multipart/form-data

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.

document
file

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
string

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.

Required string length: 1 - 2048
Example:

"https://example.com/filings/annual-2025.pdf"

captured_url
string

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.

Required string length: 1 - 2048
Example:

"https://shop.example/offer"

captured_at
string<date-time>

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.

Example:

"2026-11-04T08:41:03Z"

baseline_fingerprint
string

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.

Pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
Example:

"sha-256=:Ab3QtW7hCl7ACP+qfkR6P97Od1HtkFFDIcl9B4pPos0=:"

max_characters
integer
default:20000

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.

Required range: 0 <= x <= 1000000
formats
string[]

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.

Required array length: 1 - 5 elements

One of the formats the field lists.

Minimum string length: 1
block_kinds
string[]

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.

Required array length: 1 - 10 elements

One of the block kinds the field lists.

Minimum string length: 1
highlights
string[]

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.

Required array length: 1 - 5 elements
Required string length: 1 - 4000
json_schema
object

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
boolean
default:false

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
boolean
default:false

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
string[]

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.

Required array length: 1 - 10 elements
Required string length: 1 - 35
wait_seconds
number
default:30

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.

Required range: 5 <= x <= 90
max_cost
object

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
object

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
enum<string>

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.

Available options:
hold,
none
pinned_version
string

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.

Required string length: 1 - 64
Example:

"1.0.0"

run_id
string
default:run_default

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.

Pattern: ^run_(default|[A-Za-z0-9]{22})$
metadata
object

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.

Response

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.

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.

request_id
string
required

This call's id, the same as the Request-Id header.

Pattern: ^req_[A-Za-z0-9]{22}$
Example:

"req_01MWhgMG0UHPXXGtnjhJJO"

contents
object

The record, with the members its outcome carries and its cost. Present on a 201.

job
object

The job, stored before this answer is sent, so a read of it never misses. Present on a 202.