API

ocr

Runs in your own browser. Recognises text in photos, scans and PDFs and exports it as plain text, Markdown or JSON with layout data. The most useful call in the catalogue for a model that has to work with paper: everything else downstream can read text, but nothing can read a scan.

v1 beta browser · 19 tokens

Call it

POST https://timbrica.com/v1/tools/ocr/runs
Authorization: Bearer $TIMBRICA_KEY
Idempotency-Key: <your retry-safe key>
Content-Type: application/json

Input

Field	Type	Required	Notes
`format`	string	no	Export format. `json` carries per-block layout and confidence; `txt` is the plain reading order; `md` keeps headings and lists. one of: txt, md, json default: txt

Input file

Your browser sets the file at the recipe's `upload` step. Do not stage it with /v1/uploads.
accepts: .jpg, .jpeg, .png, .webp, .tif, .tiff, .bmp, .pdf

Browser recipe

This tool runs in your own browser. The work order you receive carries this recipe with the placeholders filled in; the selectors below are a versioned contract, not implementation detail — they do not change without a version bump.

{
    "engine": "dom",
    "steps": [
        {
            "action": "upload",
            "selector": "[data-tmb-api=\"input-file\"]",
            "accept": [
                ".jpg",
                ".jpeg",
                ".png",
                ".webp",
                ".tif",
                ".tiff",
                ".bmp",
                ".pdf"
            ]
        },
        {
            "action": "click",
            "selector": "[data-tmb-api=\"run\"]"
        },
        {
            "action": "wait",
            "selector": "[data-tmb-api=\"download\"][data-tmb-format=\"{{format}}\"]",
            "timeout_s": 600,
            "appears": "after_run"
        },
        {
            "action": "click",
            "selector": "[data-tmb-api=\"download\"][data-tmb-format=\"{{format}}\"]",
            "appears": "after_run"
        }
    ],
    "result": {
        "kind": "download",
        "settles": "automatically"
    }
}

What each action obliges you to do — recipes use nothing else:

`upload`	Put the input file into the file input matched by `selector` (it may be visually hidden: set it directly, e.g. Playwright setInputFiles). The file must match `accept`.
`click`	Click the element once it is visible AND enabled. A control that stays disabled means an earlier step did not take effect.
`fill`	Replace the value of a text input with `value`, firing input/change events as typing would.
`select`	Choose the option whose value is `value` in a <select>.
`wait`	Wait until the element is visible, up to `timeout_s` seconds (default 30).

Race every step against the work order's abort_when selector (html[data-tmb-run="failed"]). If it matches, the tool refused the job — for example a video that would not get any smaller. Stop, and GET the run: error.detail says why. Nothing is charged.

Errors it can return

validation_failed insufficient_tokens

History

v1 — 2026-08-02 — Initial release (browser lane).

This contract cannot change without a new version and a line above: a test compares the published schema, pricing and limits against a committed lockfile and fails the build otherwise. Subscribe to /v1/changelog to be told when something moves.