# Barcode Reading and Generation API 1.0 — HTTP

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

Source page: https://libscanner.com/en/docs/api/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](https://libscanner.com/en/docs/universal-reader/1.2/cpp.md) and [dmr](https://libscanner.com/en/docs/datamatrix-gs1/1.2/cpp.md) libraries, and the same generator as [dmgen](https://libscanner.com/en/docs/datamatrix-generator/1.1/cpp.md).

| 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](https://libscanner.com/en/api).

## API key

1. Sign up on the website and confirm your email — without that the API answers 403.
2. In your account, under [“API”](https://libscanner.com/en/cabinet/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:

```bash
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:

```bash
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:

```bash
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.

| 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:

```bash
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:

```bash
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

```bash
{
  "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`.

```bash
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 |

```bash
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.

```bash
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.

| 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](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](https://libscanner.com/docs/api/1.0/python.md) of this documentation.
