Read a scan with OCR
Reads the words in a scan with OCR: an image, or the pages of a PDF without text; the text is kept.
$0.005 per page read
From your agent’s balance. A call that fails costs nothing.
An example
Read the scanned delivery receipt so we can search it later.
Your agent callsfiles_ocr$0.005 per page read
The example business is Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. The reply is the one the tool really gives.
{
"file_id": "3a5c7e9b-1d4f-4a6c-8e0a-2c4e6a8c0b3e",
"languages": [
"deu",
"eng"
]
}Use it when
A scan or a photo of a document should become text that can be read and found.
- For looking at the scan yourself, use
documents_page_images.
What it does
Read the words in a scan with OCR (Tesseract): an image (PNG, JPEG, TIFF, WebP) or the pages of a PDF that have no text of their own, up to 100 pages (pages with text keep it). The text is kept: files_read_text and account_search find it afterwards, free. languages: up to 3 (default: the account's, see files_ocr_settings). max_pages is the most this call may read; it holds $0.005 for each until the reading is done, then charges the pages read. OCR reads what is printed; making sense of it is your work.
What comes back
When it finishes: the file_id, pages_read and total_pages, the languages used, and the text (up to 20,000 characters; files_read_text has the rest). Every reply also carries cost_usd and balance_usd.
Inputs
| Name | Type | What it is |
|---|---|---|
file_idRequired | string | The file_id files_upload returned. Exactly 36 characters. |
languages | array of strings | Up to 3 of eng, deu, fra, spa, ita, nld, por, swe. Up to 3 items. One of: eng,deu,fra,spa,ita,nld,por,swe. |
max_pages | integer | 1 to 100. Default: 100. |
The call
Over MCP, call files_ocr on https://api.conecto.chat/mcp/files. Over REST:
curl -X POST https://api.conecto.chat/v1/tools/files_ocr \
-H "Authorization: Bearer $CONECTO_KEY" \
-H "Content-Type: application/json" \
-d '{"file_id":"3a5c7e9b-1d4f-4a6c-8e0a-2c4e6a8c0b3e","languages":["deu","eng"]}'When it refuses
A refused call costs nothing and says what to do next.
| Code | When | What to do |
|---|---|---|
not_found404 | No file of the business has that file_id. | Find it with files_list. |
invalid_input400 | A language is not one OCR reads here, or there are more than 3. | Use up to 3 of eng, deu, fra, spa, ita, nld, por, swe. |
unsupported_type400 | The file is not an image (PNG, JPEG, TIFF, WebP) or a PDF. | Read other files with files_read_text. |
not_image400 | The file says it is an image but cannot be read as one. | Upload it again as PNG or JPEG. |
already_read409 | The scan was read with OCR already. | Read its text free with files_read_text. |
nothing_to_read409 | Every page has text of its own. | Read it free with files_read_text. |
in_progress409 | This scan is being read right now. | Read it with files_read_text in a minute. |
ocr_in_progress409 | Another scan of the business is being read; OCR reads one at a time. | Call again once that call is done (account_get_call shows it). |
too_many_pages413 | The scan has more pages to read than max_pages. | Pass the max_pages the message names. |
too_large413 | The image is over 40 megapixels. | Shrink it with image_transform first. |
pdf_locked422 | The PDF is password-protected. | Ask for a copy without a password. |
invalid_pdf422 | The file is not a PDF that can be read. | Ask for another copy. |
ocr_failed422 | OCR could not read the file. | Try a sharper scan. |
timeout422 | Reading the scan took too long. | Read fewer pages at a time with max_pages. |
crashed422 | Reading the scan needed more memory or time than a file may use. | Split the scan, or send smaller pages. |
busy503 | Files are being read for other calls right now. | Try again in a minute; nothing was charged. |
unavailable503 | OCR is not switched on here yet. | Nothing was charged; try again later. |
More Files tools
All 13 tools- Upload a file
files_uploadStores a file in the business's file store from its bytes, its text or a public link, with a download link.$0.001 a call - Get an upload link
files_upload_linkA one-time link to upload one file of up to 25 MB, to use yourself or hand to a person.Free - Find files
files_listThe business's files, newest first, filtered by name, words inside, tags, type, correspondent, document date or fields.Free* - Get a file
files_getOne file's details and a fresh download link, with the text of a small text file if asked.Free* - Read a file's words
files_read_textThe words in a file as Conecto read them: text files, PDFs, office files, HTML, and scans once read with OCR.Free* - Say what files are
files_editSays what one file is, or up to 100 at once: title, notes, document date, correspondent, type, tags and fields.$0.005 per file changed - Define a tag, type, field or correspondent
files_defineAdds, renames or deletes a tag, a document type, a custom field or a correspondent to file things with.$0.001 a call - List tags, types, fields and correspondents
files_definitionsThe tags, document types, custom fields and correspondents the business files with, each with how many files use it, and the OCR settings.Free*
Give this to your agent.
Set up Conecto from https://conecto.chat/SKILL.md