For developers

Tekomata API

Read a photo or PDF into data with the AI model of your choice, in a standard form, with the page and the place on the document where each value was read; write blog posts with AI, and hear when each is done by webhook. Read the balance and top it up by bank transfer. Paid from the shop's Tekomata credit — try it below with your integration's access token.

2. Reading documents (OCR)

From a photo or PDF to data, with the AI model of your choice.

Permissions: documents:readdocuments:extractdocuments:deletedocuments:managedocuments:scan

  1. 1
    The shop

    The shop creates a document type on its screen (for example "Nota belanja", a purchase receipt), with the fields to read: number, date, total, list of items.

  2. 2
    The shop

    Optional, and the most effective fix for reads that keep missing: knowledge for that document type, up to 10,000 characters. For example the abbreviations its sender uses, which column holds the price, how dates are written. The shop can write it on its screen (Asisten AI → Jenis dokumen → the type → "Pengetahuan untuk membaca dokumen ini"), or you can through the API, in the next step. Every read of that type carries it.

  3. 3
    Your systemGET /v1/document-types/{id}/knowledge

    Optional: see its knowledge and the characters left. Add with POST …/knowledge/entries ({"title", "content"}), change with PUT …/knowledge/entries/{entry}, delete with DELETE (permission documents:manage). Free, no AI.

  4. 4
    Your systemPOST /v1/document-types/{id}/knowledge/scans/images

    Optional, paid (permission documents:scan): send sample documents, photos or PDF, up to 8 photos or pages, in the "images" part. AI proposes knowledge; ask GET …/knowledge/scans/{scan} until succeeded, then save what you want with POST …/scans/{scan}/accept ({"items": [...]}). Nothing is saved before that.

  5. 5
    Your systemPOST /v1/document-types

    Or create one yourself through the API (permission documents:manage): a name, its fields (key, description, type, isNullable; a list with columns), a model if you want, "reportPages", and "reportBoxes" (mark where each value sits as a box; on when not sent, needs reportPages; switch it off to make photo reads slightly cheaper). Change it with PUT /v1/document-types/{id} (all fields are replaced; the id stays, old reads do not change), switch it off or on with PATCH {"isActive": false}.

  6. 6
    Your systemGET /v1/document-types

    Get the shop's document types and their ids, with their fields.

  7. 7
    Your systemGET /v1/document-types/models

    Optional: the models that can read, per vendor, with the price of one page and whether the model reads a whole PDF or page by page. The first one is the default.

  8. 8
    Your systemPOST /v1/document-types/{id}/runs/estimate

    Optional: send the same file to learn its cost without reading anything. "estimate" is a normal read, "most" the most expensive possible; both in rupiah.

  9. 9
    Your systemPOST /v1/document-types/{id}/runs

    Send the file (multipart, field "file"), and if you want: "provider" and "model" together; "pages" to read only certain pages of a PDF, for example 1-3,7; "maxCharge", a cost limit in rupiah (a read that could cost more is refused 422 over_max_charge before it is read); "boxes", true or false, to switch the value-position boxes on or off for this read only, whatever the type's setting; and "clientReference". Response 202: a read with status pending, with its id.

  10. 10
    Tekomata

    AI reads in the background. Done: webhook document_read.succeeded with runId. Failed: document_read.failed with the reason.

  11. 11
    Your systemGET /v1/document-types/{id}/runs/{run}

    Get the values and how much was charged. Each value carries "value" exactly as printed, "normalized" in one standard form for its field type ("Rp 16.650.000,00" becomes "16650000.00", "1 Oktober 2026" becomes "2026-10-01"), the model's confidence, and "pages" and "quote": every page and the text where the value was read ("page" is its first page; pages outside those sent are dropped), and "boxes": the boxes where the value is printed, one per line of text, holding "page", "x", "y", "w", "h" as fractions of the page from the top-left corner (0 to 1) and "exact". exact true means it was found in the PDF's own text, letter for letter; false means the model's estimate (a photo, a scanned PDF, or text that was not found). The image of a PDF page to place the boxes on is at GET …/runs/{run}/pages/{page} (JPEG, free); for a photo, the boxes are placed on the photo itself. "pageCount" on a PDF read is its number of pages, and "reportBoxes" on the read says whether boxes were looked for (the type's setting when it was queued, or that read's "boxes"); if false, every value's "boxes" is empty. Showing or hiding boxes you already have is up to your side: draw them or do not. "truncated" on the read means a list was cut off at its row limit.

  12. 12
    Your systemDELETE /v1/document-types/{id}/runs/{run}

    Optional: delete the read and its file once you have stored the data. Its cost stays recorded. Or set automatic deletion: PUT /v1/document-types/retention with {"days": 30}.

  • Photos in JPG, PNG, GIF, or WebP up to 5 MB; PDFs up to 20 MB. Pages per document at most the shop's limit: 50 if unchanged, up to 500 through PUT /v1/document-types/limits. A model that reads a whole PDF ("readsPdf") takes a PDF of up to 100 pages in one call when "pages" is not sent. Otherwise the PDF is read as images in parts of 50 pages (20 for a type with a list) and then merged: single values from the most confident part, list rows in order. Each part is charged its tokens, the per-read price once. Read only part of it with "pages".
  • The list of reads (GET …/runs) holds only a summary: id, file name, status, model (provider/model) and time. The values and the cost are in GET …/runs/{run}.
  • In the sandbox (a developer's local copy, not tekomata.com) read results are made up, free, and not stored: they do not appear in the list, and the checks of a real read (a switched-off type, the page limit, a broken PDF, a 5 MB photo) are skipped.
  • Want to decide the thousands separator or date format yourself? Use "value", the text exactly as printed, or make the field a text type.
  • The content type of a field (text, number, money, date, yes/no, choice) is set by the shop on its screen. Numbers are read the Indonesian way: 1.250 is one thousand two hundred and fifty.
  • A model that cannot read here is refused 422 model_not_offered before anything is sent. An insufficient balance is refused 402.
  • AI uses a document type's knowledge as a reference, never copied in as a value: values are still only what is printed on the document. If a type keeps misreading something, add one line there. Scans are limited to 20 per shop per day, and in the sandbox their results are made up, free, and not stored. Because it is sent with every read, long knowledge adds a little token cost to each read, already counted in estimate and maxCharge.
  • Correcting a read's values and proposing a document type from samples still happen on the shop's screen.