Developer documentation

Barcode Reading and Generation API

HTTP API: send an image, get the DataMatrix, QR, Code 128, GS1-128 and EAN codes; create DataMatrix and QR Code images, parse GS1 fields and check the structure of Chestny ZNAK marking codes.

4 methodsdecode, generate a code, parse a GS1 string, check the remaining limits
300 requestsa month free, 30 a day — the key is in your account
OpenAPI 3.1specification — https://api.libscanner.com/openapi.json

For AI assistants: this page in Markdown · all documentation in one file · llms.txt

Version 1.0

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.

MethodWhat it doesCost
POST /v1/decodeReads DataMatrix, QR, Code 128, GS1-128 and EAN/UPC in a JPEG or PNG image1 request
POST /v1/generateCreates a PNG with a DataMatrix (including GS1 and Chestny ZNAK) or a QR Code1 request
POST /v1/gs1/parseSplits a code string into GS1 fields and checks its structure — no image needed0.1 request
GET /v1/usageThe plan of the key, usage and remaining limitsfree

Every answer is JSON in UTF-8 (except the PNG of /v1/generate). Plan prices and limits are on the API page.

API key

  1. Sign up on the website and confirm your email — without that the API answers 403.
  2. 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: decode and generate.
  3. 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.jpg

Create 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.png

POST /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/jpeg or image/png (application/octet-stream works too: the format is detected from the file signature). Parameters go in the query string.
  • As a form, multipart/form-data — the file in the image field, parameters as form fields or in the query string.
  • As JSON — image_base64 (the file in base64; a data: URL, as a browser produces it, is accepted) or image_url; parameters as fields of the same JSON. Exactly one of the two.
ParameterValuesMeaning
modesingle, multisingle (default) — stop at the first code found, fast; multi — every code in the image, up to 64
symbologiesdatamatrix, qr, code128, gs1-128, eanwhat to look for, comma-separated; everything by default. A shorter list is faster
budget_ms100–3000time 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
gs1true, falseadd GS1 field parsing and a structure check to every code
langru, enlanguage 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,qr

An 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}
}
FieldMeaning
statusok — 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_msrecognition time (without the upload) and the applied budget
codes[].symbologydatamatrix, qr, code128, gs1-128, ean-13, ean-8, upc-a, upc-e
codes[].textthe 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_base64the exact bytes of the symbol — to compare and store a marking code losslessly
codes[].quadthe four corners of the symbol in the image, pixels, [x, y]
codes[].text_hri, codes[].gs1only 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
usagerequests 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.

ParameterValuesMeaning
datastringwhat to encode (required): up to 3116 bytes for DataMatrix, up to 7089 for QR
symbologydatamatrix, qrkind of code; datamatrix by default
gs1off, gs1, czDataMatrix 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
eccL, M, Q, HQR only: error correction level (about 7, 15, 25 and 30 % of the symbol); H by default
module_px1–40pixels per module; 8 by default
quiet_zone1–16quiet zone width, modules; 2 for DataMatrix and 4 for QR by default
formatpngimage format
langru, enlanguage 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.

ParameterValuesMeaning
codestring up to 4096 bytesthe code string (required); the separator is the byte 0x1D, “<GS>” or “⟨GS⟩”
langru, enlanguage 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_found answer 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_url requests — 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.

StatuscodeWhen
400INVALID_PARAMETER, IMAGE_REQUIRED, IMAGE_URL_INVALID, IMAGE_URL_FORBIDDEN, IMAGE_TOO_COMPLEXa wrong parameter; no image; the URL is not acceptable or points into an internal network; the JPEG has too many progressive scans
401INVALID_KEYthe key is missing, invalid or revoked
403SCOPE, EMAIL_NOT_VERIFIEDthe key has no permission for the method; the account email is not confirmed
413IMAGE_TOO_LARGEthe image is over 8 MB, 4096 px on a side or 16 megapixels
415UNSUPPORTED_IMAGEneither JPEG nor PNG
422INVALID_IMAGE, IMAGE_URL_UNAVAILABLE, GS1_INVALID, DATA_INVALIDthe 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
429DAY_LIMIT, MONTH_LIMITthe plan limit is exhausted; the body carries usage, the Retry-After header — seconds until the reset
429RATE_LIMIT, CONCURRENCY_LIMITmore than 5 requests a second or 2 at once per key (or 20 URLs a minute); with Retry-After
503BUSYthe 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 →