Upload contents
Read a document you hold, or one at a URL that needs more time than a fetch gives. You get the same record a fetch makes, the content with its structure intact, the map of its sections, the facts of the source, a fingerprint and the price, with pages saying how many pages were read, which failed and which were recognized from their image, and the record is kept for later reads.
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 needscontents: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,Locationnaming the record, andContentsUploadwithcontentsset, the record with itscost. - The parse goes on:
202 Accepted,Locationnaming the job,Retry-Aftersaying when to read it, andContentsUploadwithjobset.get_jobreads the job, andget_contentsreads the record oncecontents_idis 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
documentandurlis required; both at once is refusedexclusive, neitherrequired. - A boolean is the text
trueorfalse; a number is decimal text. json_schema,max_cost,max_source_priceandmetadataare JSON parts, read as JSON whateverContent-Typethe 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 is422 invalid-field,syntax, placeform. - The
documentpart’sfilenameandContent-Typeare hints. The bytes decide the type, amongLimits.document_media_types; where the bytes alone cannot tell, the declared type decides, then the extension, then plain text. Expect: 100-continueis honored. A declaredContent-Lengthpast 101 MiB, and every refusal the method, the path and the headers decide,401,403 insufficient-scopeforcontents:fetch, the400for a missingIdempotency-Key,415and409 idempotency-key-in-flight, is answered before100 Continue. The scope a form field decides,contents:model, is checked once the form is read and before any work. Thedocumentpart’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.basissays which. - Blocks are
text,headingandtablewhere the format carries structure;imagefor an embedded image, served at itsurlwith its digest;mathwhere the format carries equations;codefor a source file, one block per file,code_languagefrom the extension. The other kinds occur only in an HTML file, which takes a page’s kinds. page_numberandpage_labelstand on every block of a paged format and on none of an unpaged one.pagesis present for every document; on an unpaged format itscountis the text’s size in units ofbounds.contents.document_page_characterscharacters, rounded up. A slide is a page.- XML, JSON and YAML keep every key or element name, one
name: valueline 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_cellandformula_cells. - A DOCX keeps its bold, italics and strikethroughs; tracked changes are shown as accepted, with the notice
tracked_changesand the count. A PDF keeps them only where it carries the structure for them; without it, the noticemarks_not_readsays so, and a strikethrough drawn as a line over text is not detected. - A footnote reference stays as
[^n]; the note’s block carriesnote_forwhere 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.recognizedwith its confidence and a picture of the page;execution.modelslists the steprecognitionwith its version, andlanguage_detectionwhen the languages were detected; a page that yields no word stands infailed_pages; a recognized block carriesconfidence. A recognized page bills onedocument_pagesunit and onerecognized_pagesunit. Handwriting and formulas without equation structure come as flattened text or not at all, with no notice. highlightson recognized text match the recognized words;nearforgives case and end punctuation, and neitherexactnornearforgives 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_kindswork as onfetch_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 andsign_in_neededapply to it; no screenshot is made. - The fingerprint is the sha-256 over the markdown written from the document’s blocks.
source.document_digestis 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,sourcecarriesurlascaptured_urlor not at all; nofinal_urland nostatus_code;redirects[];carrierupload; noaccess_kind;filenameas sent;media_typeas the bytes showed it;title,authors, the dates andlanguageas the document’s properties declare them; nopublisher,canonical_urlorarchive;robotsnot_applicable; novisitor.scopeismain, the whole document;hidden_textandleft_outare absent, present on an HTML file. The table underContentssays 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 noticefield_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 with202, Location, Retry-After and the job in the body, stored before the answer is sent.
completed:contents_idis set and the record is delivered or partial.failed:problemis set when nothing was made; elsecontents_idis set and the record carriesfailed,refusedorneeds_person.canceledwith pages done: a recordpartial,canceled, the pages kept and billed. With none: no record and nothing billed.costis the units so far on every read, the final figure oncefinished.- The job is kept 30 days after its end, then answers
410 job-expiredfor 30 days to the owning account, then404. 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 inviolations, place form:
Idempotency-Keyabsent:400 invalid-request.- A body that is not
multipart/form-data, or carries a content coding:415 unsupported-media-type. documentandurlboth present:invalid-field,exclusive; neither:required.captured_urlorcaptured_atwithurl:dependent.captured_urlwith a scheme other than http or https, orcaptured_atthat is not an RFC 3339 instant:syntax.scope,as_of_date,subject_countryorsubject_language, which belong to a page and not to a file:unknown_field.- The
documentpart over 100 MiB:413 body-too-large. - Every rule of
fetch_contentson the fields the two share, with the same kinds:- a
formatsvalue, ablock_kindsvalue orretentionoutside its set:not_allowed; a duplicate value:duplicate; max_charactersbetween 1 and 999, or any other bound passed:bound;json_schemaorsummaryunderdeterministic_only:model-work-refused;json_schema,summaryordeterministic_only: falseunder a key whose policy forbids model work:403 policy-limit-exceeded;max_costbelow the smallest call’s price:cost-exceeds-cap;- a malformed
baseline_fingerprint:syntax; ajson_schemathat is not valid JSON Schema:syntax, and one whose root is nottype: object, that has noproperties, or whosepatternneeds backtracking:not_allowed; - an unknown
run_id:not_allowed;retention: holdunder anonepolicy:403 policy-limit-exceeded; an unknown field:unknown_field;pinned_versionnot served:version-withdrawn.
- a
- 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, withurl;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
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
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 currentexpires_atandreplayedtrue on everycost. 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, withRetry-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.
1 - 255^[!-~]{1,255}$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
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.
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.
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.
1 - 2048"https://example.com/filings/annual-2025.pdf"
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.
1 - 2048"https://shop.example/offer"
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.
^sha-256=:[A-Za-z0-9+/]{43}=:$"sha-256=:Ab3QtW7hCl7ACP+qfkR6P97Od1HtkFFDIcl9B4pPos0=:"
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.
0 <= x <= 1000000The 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.
1 - 5 elementsOne of the formats the field lists.
1Keep 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.
1 - 10 elementsOne of the block kinds the field lists.
1Words 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.
1 - 5 elements1 - 4000Your 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.
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.
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.
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.
1 - 10 elements1 - 35The 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.
5 <= x <= 90The 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.
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.
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.
hold, none 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.
1 - 64"1.0.0"
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.