Tekomata API

For developers

API changes

The rules

  • New fields or endpoints can be added at any time, without notice. Ignore fields you do not recognise yet.
  • Anything removed or renamed is announced on this page at least 30 days before it takes effect.
  • An AI model that is switched off or has its price changed is also announced here at least 30 days before. The model a read used is always recorded on that read.
  • Error codes are not changed without being recorded on this page. A code that until now answered a caller's mistake wrongly is fixed and recorded here on the day it takes effect; the message text is meant for people to read and can change.

2026-11-08

  • AddedDocument reads: every value carries "boxes", the boxes where that value is printed (page, x, y, width, height as fractions of the page, and "exact": true when found in the PDF text, false when estimated by the model). PDF reads carry "pageCount", and GET /v1/document-types/{id}/runs/{run}/pages/{page} returns the page image (JPEG, free of charge) to place those boxes on. It can be switched off: "reportBoxes": false on the document type (POST/PUT /v1/document-types; a PUT without this field keeps the setting), or "boxes": false on a single read (and "boxes": true switches it on for a single read); the read carries the "reportBoxes" it used. Reads before this date and document types with pages switched off have no boxes. In the sandbox the boxes are made up.

2026-11-06

  • ChangedCatalogue import (POST /v1/products/import/batches): one file at a time per shop, including the partner and invoice imports on the app screens. While a file from the same shop is still being read, the next upload is answered 409 import_running and creates no batch. A file that takes too long to read (more than 2 minutes), has more than 25,000,000 cells, or more than 1,000 sheets ends failed with the code too_slow_opened or too_large_opened, and nothing is saved.
  • ChangedCatalogue import (POST /v1/products/import/batches) reads .xlsx with limits on its contents after it is opened, not only on the upload size: a file that expands past them (a giant text list, a single cell over 256 KB, more than 1,048,576 rows, comments or a DOCTYPE in its XML) ends failed with the code too_large_opened, and nothing is saved. Ordinary Excel, Google Sheets, LibreOffice and WPS files are not affected.
  • ChangedImage limits per shop, the same for the API, the app screens and bulk photos: at most 10 generated at the same time, 100 a day (counted from 00.00 WIB at the time it starts; ones that fail or are refused by the model count too), and at most 2 at the same time while images across all shops fill half of Tekomata's capacity. POST /v1/images/generations answers 429 daily_limit or images_busy (besides too_many_running); an image already queued can fail with the same code. A refusal does not deduct from the balance and is not counted.
  • ChangedPOST /v1/images/generations refuses fields it does not recognise with 422 unknown_field (for example "size"), and no longer ignores them. Its fields: prompt, aspect, provider, model, clientReference.

2026-10-27

  • AddedImage generator (new permission images:generate), free prompt first: send a "prompt" to POST /v1/images/generations and the AI draws it in the background, in a 1:1, 4:5 or 9:16 shape and with a model chosen from GET /v1/images/models. News through the webhooks image_generation.succeeded and image_generation.failed; the result at GET /v1/images/generations/{id}, its file at …/{id}/image. Paid from the shop balance; free in the sandbox.
  • ChangedA webhook address created by an integration stops receiving events as soon as that integration loses its event permission or is switched off; previously events kept being sent to the existing address.
  • ChangedBlog articles: a provider and model that are not offered (or a provider without a model) are now refused with 422 model_not_offered, not 503 ai_unavailable; 503 is left for a server with no model at all. The 2000 limit on "prompt" is counted per character, not per byte.
  • ChangedPUT /v1/document-types/{id} without "isActive" or "reportPages" keeps the values of that type, and no longer switches them back on.
  • ChangedPUT /v1/billing/low-balance without "threshold" is refused with 422 invalid; send null to switch the warning off (previously it switched it off silently). Cancelling a top-up that was already approved or rejected is answered 409 already_decided; cancelling one that was already cancelled is answered 200.
  • ChangedGET /v1/webhooks/{id}/deliveries: a "limit" above 201 is read as 201 (previously it fell back to 50), and "offset" is documented. A knowledge scan that is not a multipart upload is answered 400 malformed, not 413.
  • ChangedThe documentation now matches the behaviour: the list of reads holds summaries (not full reads) along with accuracy; the pages limit follows the shop page limit; models that read a whole PDF accept up to 100 pages at once; GIF is accepted; the error codes every call can get, type_off, too_many_running, not_on_plan and others, are listed; the fields credited, target, locale, assetId and others are written up; the sandbox is explained.
  • ChangedReading documents is on for every shop, so reads are no longer refused with 403 extraction_off. "readingEnabled" on GET /v1/document-types now means there is a model that can read with its key; when there is none, reads are refused with 503 no_model.
  • AddedDocument reads use the knowledge of their document type (abbreviations, where fields sit, how dates are written), sent to the AI as reference, never as values. Long knowledge adds a little token cost per read, already counted in estimate and maxCharge.
  • AddedGET /v1/document-types/{id}/knowledge, POST …/knowledge/entries, PUT and DELETE …/knowledge/entries/{entry} (documents:read and documents:manage): view, add, change and delete the knowledge of a document type. POST …/knowledge/scans/images (new permission documents:scan, paid), GET …/knowledge/scans/{scan} and POST …/scans/{scan}/accept: the AI proposes knowledge from sample documents, you choose what is saved.

2026-10-15

  • AddedPOST /v1/document-types, PUT and PATCH /v1/document-types/{id} (new permission documents:manage): an integration creates, changes, and switches on or off its own document types. A read with a type that is switched off is refused (409 type_off).
  • Added"pages" on every value: all the pages where that value is printed. "page" stays, holding its first page. A document type with "reportPages": false does not ask for pages at all (cheaper).
  • ChangedPages named by the model outside the pages that were sent are now dropped from page and pages.
  • AddedGET and PUT /v1/document-types/limits: the page limit per document for each shop, 50 unless changed, up to 500. A document over 50 pages (20 for types with a list) is read in parts and then merged; each part is charged its tokens, the per-read price once. "truncated" on a read marks a list cut off at its row limit.
  • AddedGET and PUT /v1/billing/low-balance and the balance.low webhook: told once when the balance drops below the number you set, until the balance rises again.
  • ChangedEvery error message to an integration is now in English, including "error" on a failed read and in the document_read.failed webhook. The codes are unchanged.

2026-10-14

  • AddedIdempotency-Key on every call that writes: a repeat with the same key is answered with the first answer and is not charged twice.
  • AddedclientReference on document reads and background articles, returned in the answer and the webhook; GET …/runs?clientReference=.
  • AddedDocument reads: "normalized" according to the field type (number, money, date, yes/no, choice), "page" and "quote" where the value was read, "pages" to read only certain pages, and "maxCharge".
  • AddedPOST /v1/document-types/{id}/runs/estimate: the cost of a read before it is sent.
  • AddedDELETE /v1/document-types/{id}/runs/{run} and PUT /v1/document-types/retention (permission documents:delete): delete reads and their files, now or automatically after a number of days.
  • Added/v1/webhooks (permission webhooks:manage): an integration sets up and manages its own webhook addresses.
  • AddedPOST /v1/token and GET /v1/whoami are in openapi.json, so code generators can build a client that can sign in.
  • Removedcharged.tokens and charged.base in the blog article answer: the cost is given as a single rupiah total, charged.total. Removed without 30 days because this rule did not exist yet; from now on the rule applies.
  • AddedBalance and top-ups (GET /v1/billing/balance, /v1/billing/top-ups), with the webhooks top_up.approved and top_up.rejected.
  • AddedBackground blog articles (POST /v1/blog/generations) and the document_read.* and blog_generation.* webhooks.
  • AddedReading documents (OCR) through the API, with a choice of vendor and model per read.

2026-09-20

  • AddedAPI opened: writing blog articles with AI.