Skip to main content
Much of what research rests on is not a web page. It is a contract in a data room, a filing as a PDF, a spreadsheet of a budget, a scan of minutes from 1998. upload_contents reads the file and returns a record, the same kind a fetched page gives, so every later step works on a file as it does on a page: the outline, the sections, the highlights, the comparison.

Upload a file

Send the file as document. The SDKs take a path, the bytes, or a stream.
Replace FILE_PATH with the path of the file, and IDEMPOTENCY_KEY with a value of your own that is new for each upload. An upload must have this key, so that a file sent twice is not read and charged twice. The SDKs make the key for you. A file can be up to 100 MiB. It is deleted when the read ends, and only the record is stored. For a file that is on the web, send its address as url in place of document.

Wait for a long file

A short file comes back in the same call. A long one, such as a scan of 300 pages, is read as a job, because a read that stopped early would lose pages. The call then returns the job, and the record follows when the job is done. With wait set, the SDKs follow the job and return the record. A job reads the pages in order. If a spending limit or the job’s 30 minutes ends it, the record has the pages read so far and its outcome is partial.

Read what came from the file

The record has pages, which says how the read went. This response is cut to that field.
Part of the response
Each block and each section of the record has the page it is on, as page_number, and the number printed on that page, as page_label, so a citation can say “page iv” as the document does. What the record has depends on what the file has.
A document can be one of 22 types, from PDF and the Office formats to Markdown, CSV, JSON, and images. get_limits lists them. An archive file such as a ZIP, and audio or video, are not read, and the record’s outcome says so.

Choose the format of the content

A record of a file comes in the same formats as a record of a web page. The content is the same in each, and each format is for another reader.
Send the formats you want in formats. For what each format has, see Fetch what a page says, not what surrounds it.

Trust a scan as far as it deserves

A page without text in it is read from its picture. pages.recognized has each such page with a confidence from 0 to 1 and a picture of the page, so you can check a reading against what it was read from. A page read below the published bar makes the notice recognition_uncertain.
Send the weak pages to a person, and not all 312, which is what the number is for. To help the reading, name the languages of the scan in recognition_languages. Handwriting, and a formula that is only a picture, come as flat text or not at all.

Record where a saved page came from

A page behind a sign-in cannot be fetched by its address. A person can open it, save it, and upload the file. Send the page’s address as captured_url and the time it was saved as captured_at, and the record says where and when the page was seen.

Check what a file costs

An upload costs one unit for the file, one for each page read, and one more for each page recognized from its picture. A long scan is the most expensive call there is. To learn a document’s size before you pay for its pages, fetch its address with max_characters set to 0 and a low max_cost: the response has the page count and the outline.