Overview
An HTTP API at https://api.libscanner.com: reading codes in an image, creating DataMatrix and QR Code images, parsing and validating GS1 strings. Inside are the same readers that are sold as the unir and dmr libraries, and the same generator as dmgen.
| Method | What it does | Cost |
|---|---|---|
POST /v1/decode | Reads DataMatrix, QR, Code 128, GS1-128 and EAN/UPC in a JPEG or PNG image | 1 request |
POST /v1/generate | Creates a PNG with a DataMatrix (including GS1 and Chestny ZNAK) or a QR Code | 1 request |
POST /v1/gs1/parse | Splits a code string into GS1 fields and checks its structure — no image needed | 0.1 request |
GET /v1/usage | The plan of the key, usage and remaining limits | free |
Every answer is JSON in UTF-8 (except the PNG of /v1/generate). Plan prices and limits are on the API page.
API key
- Sign up on the website and confirm your email — without that the API answers 403.
- In your account, under “API”, create a key. It is shown only once; the server keeps only its hash. You can have several keys — say, one per system — each with its own permissions:
decodeandgenerate. - Send the key with every request, in one of two headers:
Authorization: Bearer lsk_live_…
X-API-Key: lsk_live_…The key is an account secret: do not put it into web page code or a mobile app that reaches your users. Revoke a compromised key in your account — it stops working immediately. Plan limits are shared by all keys of the account.
Quick start
An image file as the request body, with GS1 parsing:
curl "https://api.libscanner.com/v1/decode?gs1=true&lang=en" \
-H "Authorization: Bearer lsk_live_…" \
-H "Content-Type: image/jpeg" \
--data-binary @label.jpgCreate a Chestny ZNAK DataMatrix and save the PNG:
curl https://api.libscanner.com/v1/generate \
-H "Authorization: Bearer lsk_live_…" \
-H "Content-Type: application/json" \
-d '{"data": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz", "gs1": "cz", "module_px": 10}' \
-o code.pngPOST /v1/decode
The image is a JPEG or PNG up to 8 MB, 4096 px on a side and 16 megapixels. It is passed in one of three ways:
- As the request body —
Content-Type: image/jpegorimage/png(application/octet-streamworks too: the format is detected from the file signature). Parameters go in the query string. - As a form,
multipart/form-data— the file in theimagefield, parameters as form fields or in the query string. - As JSON —
image_base64(the file in base64; adata:URL, as a browser produces it, is accepted) orimage_url; parameters as fields of the same JSON. Exactly one of the two.
| Parameter | Values | Meaning |
|---|---|---|
mode | single, multi | single (default) — stop at the first code found, fast; multi — every code in the image, up to 64 |
symbologies | datamatrix, qr, code128, gs1-128, ean | what to look for, comma-separated; everything by default. A shorter list is faster |
budget_ms | 100–3000 | time budget per image, ms; 1000 by default. A request asking for more gets 3000 ms, all others get the default; the applied budget is returned in budget_ms |
gs1 | true, false | add GS1 field parsing and a structure check to every code |
lang | ru, en | language of GS1 field names and check messages; ru by default |
A form with a file:
curl https://api.libscanner.com/v1/decode \
-H "Authorization: Bearer lsk_live_…" \
-F image=@label.png -F mode=multi -F symbologies=datamatrix,qrAn image by URL:
curl https://api.libscanner.com/v1/decode \
-H "Authorization: Bearer lsk_live_…" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://example.com/label.jpg", "mode": "multi", "gs1": true, "lang": "en"}'image_url must be a public http or https URL on port 80 or 443. The image is downloaded with a 5 second timeout and at most two redirects; internal network and loopback addresses are refused (400 IMAGE_URL_FORBIDDEN). At most 20 such requests a minute per account.
Decode response
{
"status": "ok",
"elapsed_ms": 41.2,
"budget_ms": 1000,
"codes": [{
"symbology": "datamatrix",
"text": "0104601234567893215Abc12Xyz!-\u001d93dGVz",
"text_hri": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz",
"bytes_base64": "MDEwNDYwMTIzNDU2Nzg5MzIxNUFiYzEyWHl6IS0dOTNkR1Z6",
"quad": [[212.5, 98.0], [431.0, 101.5], [428.5, 320.0], [210.0, 316.5]],
"gs1": {
"fields": {"01": "04601234567893", "21": "5Abc12Xyz!-", "93": "dGVz"},
"elements": [{"ai": "01", "name": "GTIN", "value": "04601234567893"}, …],
"check": [{"level": "ok", "text": "GTIN 04601234567893: check digit is correct."}, …]
}
}],
"usage": {"day": 12, "day_limit": 1000, "month": 340, "month_limit": 10000}
}| Field | Meaning |
|---|---|
status | ok — at least one code was read; not_found — no code was found; not_decoded — a symbol was found but could not be read (blurred, cropped, damaged). The answer is 200 in every case: the image was accepted and processed |
elapsed_ms, budget_ms | recognition time (without the upload) and the applied budget |
codes[].symbology | datamatrix, qr, code128, gs1-128, ean-13, ean-8, upc-a, upc-e |
codes[].text | the code as text; the GS1 separator is the real character U+001D, not the text “<GS>”. Bytes that are not valid UTF-8 are interpreted as ISO-8859-1 |
codes[].bytes_base64 | the exact bytes of the symbol — to compare and store a marking code losslessly |
codes[].quad | the four corners of the symbol in the image, pixels, [x, y] |
codes[].text_hri, codes[].gs1 | only with gs1=true: the human readable form “(01)…(21)…” and the parse (fields — identifier → value, the first one if repeated; elements — every field in order with its name; check — checks with level ok, warn or error). For a code that is not a GS1 string gs1 is null |
usage | requests counted today and in the period, with the plan limits — this request included |
POST /v1/generate
The body is JSON. A DataMatrix (ISO/IEC 16022) is created by default, a QR Code (ISO/IEC 18004) with symbology: "qr". The answer is a PNG; with Accept: application/json it is JSON with the image in base64 and its dimensions.
| Parameter | Values | Meaning |
|---|---|---|
data | string | what to encode (required): up to 3116 bytes for DataMatrix, up to 7089 for QR |
symbology | datamatrix, qr | kind of code; datamatrix by default |
gs1 | off, gs1, cz | DataMatrix only: gs1 — validate the data against the GS1 rules and encode as GS1 DataMatrix; cz — the same plus the Chestny ZNAK profile; off by default |
ecc | L, M, Q, H | QR only: error correction level (about 7, 15, 25 and 30 % of the symbol); H by default |
module_px | 1–40 | pixels per module; 8 by default |
quiet_zone | 1–16 | quiet zone width, modules; 2 for DataMatrix and 4 for QR by default |
format | png | image format |
lang | ru, en | language of the explanation of invalid data |
The group separator in GS1 data is the byte 0x1D, the text <GS> or the bracketed form (01)…(21)…. Data that fails validation gives 422 GS1_INVALID with an explanation of what is wrong (“GTIN …: wrong check digit”); data that does not fit into the symbol gives 422 DATA_INVALID.
curl https://api.libscanner.com/v1/generate \
-H "Authorization: Bearer lsk_live_…" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"data": "https://libscanner.com", "symbology": "qr", "ecc": "M"}'
{"format": "png", "symbology": "qr", "width": 264, "height": 264, "size": "25x25",
"image_base64": "iVBORw0KGgo…", "usage": {"day": 3, "day_limit": 30, "month": 3, "month_limit": 300}}size is the symbol size in modules, rows × columns; width and height are the image size with the quiet zone, pixels.
POST /v1/gs1/parse
Parsing a code string without an image — say, a string read by a barcode scanner. GS1 fields, the GTIN check digit, serial number length and characters, presence and lengths of the Chestny ZNAK verification codes (91 + 92 or 93), missing separators, the expiry date. The format is checked; the status of the item in the marking system is not queried. Costs 0.1 request.
| Parameter | Values | Meaning |
|---|---|---|
code | string up to 4096 bytes | the code string (required); the separator is the byte 0x1D, “<GS>” or “⟨GS⟩” |
lang | ru, en | language of field names and check messages; ru by default |
curl https://api.libscanner.com/v1/gs1/parse \
-H "Authorization: Bearer lsk_live_…" \
-H "Content-Type: application/json" \
-d '{"code": "0104601234567893215Abc12Xyz!-<GS>93dGVz", "lang": "en"}'The answer: is_gs1, text (the string with separators normalised to U+001D), text_hri, fields, elements, check — as in the decode response — and usage. A string that does not parse as GS1 is not an error: is_gs1: false, fields: null and one explanation in check. The check item about the expiry date is marked "kind": "expiry".
GET /v1/usage
The plan and the remaining limits; not counted.
curl https://api.libscanner.com/v1/usage -H "Authorization: Bearer lsk_live_…"
{"plan": {"paid": false, "slug": "free", "name": "Free", "valid_until": null},
"usage": {"day": 4.1, "day_limit": 30, "month": 57.3, "month_limit": 300},
"day_resets_at": "2026-11-19T21:00:00Z", "month_resets_at": "2026-11-30T21:00:00Z"}month_resets_at is the end of the calendar month on the free plan and the end of the current paid period on paid plans. Fractions come from string parsing at 0.1 request.
Limits and billing
- A plan has a daily and a per-period request limit shared by all keys of the account. The day starts at 00:00 Moscow time. The free plan gives 30 requests a day and 300 per calendar month.
- Only an accepted request is counted: decoding and generation cost 1 request, parsing a string 0.1. A
not_foundanswer is counted: the image was accepted and processed. - Not counted: 4xx refusals (bad image, wrong parameter, exhausted limit), 503 and failures on our side (5xx), and
GET /v1/usage. - Per key — at most 5 requests a second and 2 at once;
image_urlrequests — at most 20 a minute per account.
Errors
The error shape is {"error": {"code", "message", "request_id"}}. code is stable — branch on it; message is for humans and may change. Quote request_id when writing to support.
| Status | code | When |
|---|---|---|
| 400 | INVALID_PARAMETER, IMAGE_REQUIRED, IMAGE_URL_INVALID, IMAGE_URL_FORBIDDEN, IMAGE_TOO_COMPLEX | a wrong parameter; no image; the URL is not acceptable or points into an internal network; the JPEG has too many progressive scans |
| 401 | INVALID_KEY | the key is missing, invalid or revoked |
| 403 | SCOPE, EMAIL_NOT_VERIFIED | the key has no permission for the method; the account email is not confirmed |
| 413 | IMAGE_TOO_LARGE | the image is over 8 MB, 4096 px on a side or 16 megapixels |
| 415 | UNSUPPORTED_IMAGE | neither JPEG nor PNG |
| 422 | INVALID_IMAGE, IMAGE_URL_UNAVAILABLE, GS1_INVALID, DATA_INVALID | the image file is damaged; no 200 answer from the URL within 5 seconds; the data fails GS1 validation or does not fit into the symbol |
| 429 | DAY_LIMIT, MONTH_LIMIT | the plan limit is exhausted; the body carries usage, the Retry-After header — seconds until the reset |
| 429 | RATE_LIMIT, CONCURRENCY_LIMIT | more than 5 requests a second or 2 at once per key (or 20 URLs a minute); with Retry-After |
| 503 | BUSY | the server is busy or the API is temporarily switched off; retry after Retry-After seconds, the request is not counted |
Retrying makes sense for 429 with RATE_LIMIT/CONCURRENCY_LIMIT and for 503 — after the pause from Retry-After. A retry will not fix other 4xx answers.
Image storage
- On paid plans images are not stored — neither read nor unread.
- On the free plan, images in which no code was found or read are kept for up to a year to improve recognition. Images that were read are not stored.
- Codes from the answers are not stored on any plan; only the number of requests is recorded.
- The servers are located in Russia.
OpenAPI
The full specification (OpenAPI 3.1) — https://api.libscanner.com/openapi.json. Clients can be generated from it (openapi-generator), Postman and Insomnia import it, and AI assistants read it too. For Python, see the Python tab of this documentation.
Need a method the API does not have, or a stream of camera frames? We will adapt it to your task or suggest a library. Contact us →