{
  "openapi": "3.1.0",
  "info": {
    "title": "libscanner API",
    "version": "1.0.0",
    "summary": "Read and generate DataMatrix, QR and linear barcodes; parse and validate GS1 and Chestny ZNAK marking codes.",
    "description": "Cloud API of [libscanner.com](https://libscanner.com): the same readers that are sold as libraries (dmr, unir), behind HTTP.\n\n**Authentication.** Every request carries an API key: `Authorization: Bearer lsk_live_…` (or `X-API-Key`). Keys are issued in the account at https://libscanner.com/cabinet/api.\n\n**Limits.** Each plan has a daily and a monthly request limit shared by all keys of the account; the day starts at 00:00 Moscow time. A request is counted only when it is accepted: `4xx` and `503` answers are free, a `not_found` answer is counted. Decoding and generation cost one request, `/v1/gs1/parse` costs 0.1. On top of that: at most 5 requests per second and 2 simultaneous requests per key.\n\n**Images.** JPEG and PNG, up to 8 MB, 4096 px on a side and 16 megapixels.\n\n**Storage.** On paid plans images are not stored. On the free plan images in which no code was read are kept for up to a year to improve recognition. Decoded codes are never stored.\n\n**Errors.** `{\"error\": {\"code\", \"message\", \"request_id\"}}`; `code` is stable, `message` is for humans.",
    "contact": {
      "name": "libscanner",
      "url": "https://libscanner.com/api",
      "email": "libscanner@yandex.com"
    },
    "termsOfService": "https://libscanner.com/offer"
  },
  "servers": [
    {
      "url": "https://api.libscanner.com"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "decode",
      "description": "Reading codes from images"
    },
    {
      "name": "generate",
      "description": "Creating code images"
    },
    {
      "name": "gs1",
      "description": "GS1 and Chestny ZNAK marking codes"
    },
    {
      "name": "account",
      "description": "Plan and usage"
    }
  ],
  "paths": {
    "/v1/decode": {
      "post": {
        "tags": [
          "decode"
        ],
        "operationId": "decode",
        "summary": "Read the codes in an image",
        "description": "Reads DataMatrix, QR, Code 128, GS1-128 and EAN/UPC codes in a JPEG or PNG image. The image is passed in one of three ways: as the raw request body (`Content-Type: image/jpeg` or `image/png`), as the `image` field of `multipart/form-data`, or in JSON as `image_base64` or `image_url`. The parameters go in the query string, as form fields, or as JSON fields.\n\n`image_url` must be a public `http`/`https` URL on port 80 or 443; it is fetched with a 5 second timeout and at most 2 redirects. No more than 20 `image_url` requests per minute per account.",
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "multi"
              ],
              "default": "single"
            },
            "description": "`single` — stop at the first code found (fast); `multi` — find every code in the image (up to 64)."
          },
          {
            "name": "symbologies",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of what to look for: `datamatrix`, `qr`, `code128`, `gs1-128`, `ean`. Everything by default.",
            "example": "datamatrix,qr"
          },
          {
            "name": "budget_ms",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 100,
              "maximum": 3000,
              "default": 1000
            },
            "description": "Time budget for one image, ms. The budget that was actually applied is returned in `budget_ms` of the response: requests asking for more than the default run with a 3000 ms budget, all others with the default one."
          },
          {
            "name": "gs1",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Add GS1 parsing and a structure check (GTIN check digit, field lengths, separators, Chestny ZNAK verification codes) to every code."
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ru",
                "en"
              ],
              "default": "ru"
            },
            "description": "Language of the GS1 field names and check messages."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "image"
                ],
                "properties": {
                  "image": {
                    "type": "string",
                    "format": "binary"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "single",
                      "multi"
                    ],
                    "default": "single",
                    "description": "`single` — stop at the first code found (fast); `multi` — find every code in the image (up to 64)."
                  },
                  "symbologies": {
                    "type": "string",
                    "example": "datamatrix,qr",
                    "description": "Comma-separated list of what to look for: `datamatrix`, `qr`, `code128`, `gs1-128`, `ean`. Everything by default."
                  },
                  "budget_ms": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 3000,
                    "default": 1000,
                    "description": "Time budget for one image, ms. The budget that was actually applied is returned in `budget_ms` of the response: requests asking for more than the default run with a 3000 ms budget, all others with the default one."
                  },
                  "gs1": {
                    "type": "boolean",
                    "default": false,
                    "description": "Add GS1 parsing and a structure check (GTIN check digit, field lengths, separators, Chestny ZNAK verification codes) to every code."
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "ru",
                      "en"
                    ],
                    "default": "ru",
                    "description": "Language of the GS1 field names and check messages."
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Exactly one of `image_base64` and `image_url`.",
                "properties": {
                  "image_base64": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "The image file in base64 (a `data:` URL is accepted)."
                  },
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public http(s) URL of the image."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "single",
                      "multi"
                    ],
                    "default": "single",
                    "description": "`single` — stop at the first code found (fast); `multi` — find every code in the image (up to 64)."
                  },
                  "symbologies": {
                    "type": "string",
                    "example": "datamatrix,qr",
                    "description": "Comma-separated list of what to look for: `datamatrix`, `qr`, `code128`, `gs1-128`, `ean`. Everything by default."
                  },
                  "budget_ms": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 3000,
                    "default": 1000,
                    "description": "Time budget for one image, ms. The budget that was actually applied is returned in `budget_ms` of the response: requests asking for more than the default run with a 3000 ms budget, all others with the default one."
                  },
                  "gs1": {
                    "type": "boolean",
                    "default": false,
                    "description": "Add GS1 parsing and a structure check (GTIN check digit, field lengths, separators, Chestny ZNAK verification codes) to every code."
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "ru",
                      "en"
                    ],
                    "default": "ru",
                    "description": "Language of the GS1 field names and check messages."
                  }
                }
              },
              "example": {
                "image_url": "https://example.com/label.jpg",
                "mode": "multi",
                "gs1": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The image was accepted. `status` tells whether a code was read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DecodeResponse"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is wrong (`INVALID_PARAMETER`), there is no image (`IMAGE_REQUIRED`), the URL is not acceptable (`IMAGE_URL_INVALID`, `IMAGE_URL_FORBIDDEN`) or the JPEG has too many progressive scans (`IMAGE_TOO_COMPLEX`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_PARAMETER",
                    "message": "mode must be single or multi",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key has no `decode` permission (`SCOPE`) or the account email is not confirmed (`EMAIL_NOT_VERIFIED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "SCOPE",
                    "message": "This key has no permission for decode",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "413": {
            "description": "The image is over 8 MB, 4096 px on a side or 16 megapixels.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IMAGE_TOO_LARGE",
                    "message": "The image is larger than 8 MB",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "415": {
            "description": "Not a JPEG or PNG image.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "UNSUPPORTED_IMAGE",
                    "message": "Only JPEG and PNG images are supported",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "422": {
            "description": "The image file is damaged (`INVALID_IMAGE`) or `image_url` could not be downloaded (`IMAGE_URL_UNAVAILABLE`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IMAGE_URL_UNAVAILABLE",
                    "message": "Could not download image_url: no 200 response within 5 seconds",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_KEY",
                    "message": "API key is missing, invalid or revoked",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "429": {
            "description": "A limit is exhausted: `DAY_LIMIT` or `MONTH_LIMIT` of the plan (the body also carries `usage`), `RATE_LIMIT` (more than 5 requests per second for the key, or more than 20 `image_url` requests per minute for the account) or `CONCURRENCY_LIMIT` (more than 2 simultaneous requests for the key).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitError"
                },
                "example": {
                  "error": {
                    "code": "DAY_LIMIT",
                    "message": "Daily request limit of the plan is exhausted",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  },
                  "usage": {
                    "day": 30,
                    "day_limit": 30,
                    "month": 112,
                    "month_limit": 300
                  }
                }
              }
            }
          },
          "503": {
            "description": "The service is busy (`BUSY`) or the API is temporarily switched off. Retry after `Retry-After` seconds. Not counted against the limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "BUSY",
                    "message": "The service is busy, retry in a few seconds",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/generate": {
      "post": {
        "tags": [
          "generate"
        ],
        "operationId": "generate",
        "summary": "Create a DataMatrix or QR Code image",
        "description": "Encodes `data` into a DataMatrix symbol (ISO/IEC 16022) or a QR Code (ISO/IEC 18004) and returns a PNG image. For DataMatrix, with `gs1` set to `gs1` or `cz` the data is validated against the GS1 General Specifications (and the Chestny ZNAK profile) and encoded as GS1 DataMatrix; the group separator is written as the byte 0x1D, `<GS>` or in bracketed form `(01)…(21)…`. QR Code is for links and text: `gs1` is not available for it.\n\nThe answer is `image/png`; with `Accept: application/json` it is JSON with the image in base64 and its dimensions.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              },
              "example": {
                "data": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz",
                "gs1": "cz",
                "module_px": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The code image.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateResponse"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is wrong (`INVALID_PARAMETER`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_PARAMETER",
                    "message": "data is required",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key has no `generate` permission (`SCOPE`) or the account email is not confirmed (`EMAIL_NOT_VERIFIED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "SCOPE",
                    "message": "This key has no permission for generate",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "422": {
            "description": "The data does not pass GS1 validation (`GS1_INVALID`) or cannot be encoded into the symbol (`DATA_INVALID`). The message explains what is wrong, in the language of `lang`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "GS1_INVALID",
                    "message": "GTIN 04601234567890: неверная контрольная цифра",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_KEY",
                    "message": "API key is missing, invalid or revoked",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "429": {
            "description": "A limit is exhausted: `DAY_LIMIT` or `MONTH_LIMIT` of the plan (the body also carries `usage`), `RATE_LIMIT` (more than 5 requests per second for the key, or more than 20 `image_url` requests per minute for the account) or `CONCURRENCY_LIMIT` (more than 2 simultaneous requests for the key).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitError"
                },
                "example": {
                  "error": {
                    "code": "DAY_LIMIT",
                    "message": "Daily request limit of the plan is exhausted",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  },
                  "usage": {
                    "day": 30,
                    "day_limit": 30,
                    "month": 112,
                    "month_limit": 300
                  }
                }
              }
            }
          },
          "503": {
            "description": "The service is busy (`BUSY`) or the API is temporarily switched off. Retry after `Retry-After` seconds. Not counted against the limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "BUSY",
                    "message": "The service is busy, retry in a few seconds",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/gs1/parse": {
      "post": {
        "tags": [
          "gs1"
        ],
        "operationId": "parseGs1",
        "summary": "Parse and validate a GS1 string",
        "description": "Splits a GS1 string into application identifiers and checks the structure of a marking code without an image: GTIN check digit, serial number length and characters, presence and lengths of the Chestny ZNAK verification fields (91 + 92 or 93), missing group separators, expiry date. It checks the format only — the status of the item in the marking system is not queried.\n\nThe separator may be the byte 0x1D, `<GS>` or `⟨GS⟩`. Costs 0.1 request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "maxLength": 4096,
                    "description": "The code string as read from the symbol."
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "ru",
                      "en"
                    ],
                    "default": "ru",
                    "description": "Language of the GS1 field names and check messages."
                  }
                }
              },
              "example": {
                "code": "0104601234567893215Abc12Xyz!-\u001d93dGVz",
                "lang": "en"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The parsed string. `is_gs1` is false when it does not parse as GS1.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseResponse"
                }
              }
            }
          },
          "400": {
            "description": "`code` is missing or too long.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_PARAMETER",
                    "message": "code is required",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account email is not confirmed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "EMAIL_NOT_VERIFIED",
                    "message": "Confirm the account email to use the API",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_KEY",
                    "message": "API key is missing, invalid or revoked",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "429": {
            "description": "A limit is exhausted: `DAY_LIMIT` or `MONTH_LIMIT` of the plan (the body also carries `usage`), `RATE_LIMIT` (more than 5 requests per second for the key, or more than 20 `image_url` requests per minute for the account) or `CONCURRENCY_LIMIT` (more than 2 simultaneous requests for the key).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitError"
                },
                "example": {
                  "error": {
                    "code": "DAY_LIMIT",
                    "message": "Daily request limit of the plan is exhausted",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  },
                  "usage": {
                    "day": 30,
                    "day_limit": 30,
                    "month": 112,
                    "month_limit": 300
                  }
                }
              }
            }
          },
          "503": {
            "description": "The service is busy (`BUSY`) or the API is temporarily switched off. Retry after `Retry-After` seconds. Not counted against the limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "BUSY",
                    "message": "The service is busy, retry in a few seconds",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "account"
        ],
        "operationId": "usage",
        "summary": "Plan and remaining limits",
        "description": "Not counted against the limits.",
        "responses": {
          "200": {
            "description": "The plan of the account and what is used.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_KEY",
                    "message": "API key is missing, invalid or revoked",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  }
                }
              }
            }
          },
          "429": {
            "description": "A limit is exhausted: `DAY_LIMIT` or `MONTH_LIMIT` of the plan (the body also carries `usage`), `RATE_LIMIT` (more than 5 requests per second for the key, or more than 20 `image_url` requests per minute for the account) or `CONCURRENCY_LIMIT` (more than 2 simultaneous requests for the key).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitError"
                },
                "example": {
                  "error": {
                    "code": "DAY_LIMIT",
                    "message": "Daily request limit of the plan is exhausted",
                    "request_id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b"
                  },
                  "usage": {
                    "day": 30,
                    "day_limit": 30,
                    "month": 112,
                    "month_limit": 300
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "`Authorization: Bearer lsk_live_…`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable code."
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string",
                "description": "Quote it when writing to support."
              }
            }
          }
        }
      },
      "LimitError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Error"
          },
          {
            "type": "object",
            "properties": {
              "usage": {
                "$ref": "#/components/schemas/Usage"
              }
            }
          }
        ]
      },
      "Usage": {
        "type": "object",
        "required": [
          "day",
          "day_limit",
          "month",
          "month_limit"
        ],
        "description": "Requests counted today and in the current period, with the plan limits. Fractions appear because `/v1/gs1/parse` costs 0.1 request.",
        "properties": {
          "day": {
            "type": "number"
          },
          "day_limit": {
            "type": "integer"
          },
          "month": {
            "type": "number"
          },
          "month_limit": {
            "type": "integer"
          }
        }
      },
      "CheckItem": {
        "type": "object",
        "required": [
          "level",
          "text"
        ],
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "ok",
              "warn",
              "error"
            ]
          },
          "text": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "expiry"
            ],
            "description": "Present when the item is about the expiry date, not the code structure."
          }
        }
      },
      "Gs1Element": {
        "type": "object",
        "required": [
          "ai",
          "name",
          "value"
        ],
        "properties": {
          "ai": {
            "type": "string",
            "description": "Application identifier, e.g. `01`."
          },
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      },
      "Gs1": {
        "type": "object",
        "required": [
          "fields",
          "elements",
          "check"
        ],
        "properties": {
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Application identifier → value (the first one if an identifier repeats)."
          },
          "elements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Gs1Element"
            },
            "description": "Every field in the order of the string."
          },
          "check": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CheckItem"
            }
          }
        }
      },
      "Code": {
        "type": "object",
        "required": [
          "symbology",
          "text",
          "bytes_base64"
        ],
        "properties": {
          "symbology": {
            "type": [
              "string",
              "null"
            ],
            "description": "`datamatrix`, `qr`, `code128`, `gs1-128`, `ean-13`, `ean-8`, `upc-a` …",
            "example": "datamatrix"
          },
          "text": {
            "type": "string",
            "description": "The code as text; the GS1 group separator is the real character U+001D. Bytes that are not valid UTF-8 are interpreted as ISO-8859-1.",
            "example": "0104601234567893215Abc12Xyz!-\u001d93dGVz"
          },
          "text_hri": {
            "type": "string",
            "description": "Human readable form; only with `gs1=true` for GS1 codes.",
            "example": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz"
          },
          "bytes_base64": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "The exact bytes of the symbol."
          },
          "quad": {
            "type": "array",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "items": {
                "type": "number"
              }
            },
            "description": "Four corners of the symbol in image pixels, `[x, y]` each."
          },
          "gs1": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Gs1"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with `gs1=true`; null when the code is not a GS1 string."
          }
        }
      },
      "DecodeResponse": {
        "type": "object",
        "required": [
          "status",
          "elapsed_ms",
          "budget_ms",
          "codes",
          "usage"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "not_found",
              "not_decoded"
            ],
            "description": "`ok` — at least one code was read; `not_found` — no code was found; `not_decoded` — a symbol was found but could not be read."
          },
          "elapsed_ms": {
            "type": "number",
            "description": "Recognition time, without upload."
          },
          "budget_ms": {
            "type": "integer",
            "description": "The time budget that was applied."
          },
          "codes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Code"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "GenerateRequest": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "string",
            "maxLength": 7089,
            "description": "The string to encode: up to 3116 bytes for DataMatrix, up to 7089 for QR."
          },
          "symbology": {
            "type": "string",
            "enum": [
              "datamatrix",
              "qr"
            ],
            "default": "datamatrix"
          },
          "gs1": {
            "type": "string",
            "enum": [
              "off",
              "gs1",
              "cz"
            ],
            "default": "off",
            "description": "DataMatrix only. `gs1` — validate and encode as GS1 DataMatrix; `cz` — the same plus the Chestny ZNAK profile."
          },
          "module_px": {
            "type": "integer",
            "minimum": 1,
            "maximum": 40,
            "default": 8,
            "description": "Pixels per module."
          },
          "quiet_zone": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16,
            "description": "Quiet zone width, modules; 2 for DataMatrix and 4 for QR by default."
          },
          "format": {
            "type": "string",
            "enum": [
              "png"
            ],
            "default": "png"
          },
          "lang": {
            "type": "string",
            "enum": [
              "ru",
              "en"
            ],
            "default": "ru",
            "description": "Language of the GS1 field names and check messages."
          },
          "ecc": {
            "type": "string",
            "enum": [
              "L",
              "M",
              "Q",
              "H"
            ],
            "default": "H",
            "description": "QR only: error correction level (about 7, 15, 25 and 30 % of the symbol)."
          }
        }
      },
      "GenerateResponse": {
        "type": "object",
        "required": [
          "image_base64",
          "format",
          "symbology",
          "usage"
        ],
        "properties": {
          "image_base64": {
            "type": "string",
            "contentEncoding": "base64"
          },
          "format": {
            "type": "string",
            "enum": [
              "png"
            ]
          },
          "width": {
            "type": "integer",
            "description": "Image width, px."
          },
          "height": {
            "type": "integer",
            "description": "Image height, px."
          },
          "size": {
            "type": "string",
            "description": "Symbol size in modules, rows x columns.",
            "example": "26x26"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "symbology": {
            "type": "string",
            "enum": [
              "datamatrix",
              "qr"
            ]
          }
        }
      },
      "ParseResponse": {
        "type": "object",
        "required": [
          "is_gs1",
          "text",
          "fields",
          "elements",
          "check",
          "usage"
        ],
        "properties": {
          "is_gs1": {
            "type": "boolean"
          },
          "text": {
            "type": "string",
            "description": "The string with separators normalised to U+001D."
          },
          "text_hri": {
            "type": "string",
            "example": "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz"
          },
          "fields": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "elements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Gs1Element"
            }
          },
          "check": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CheckItem"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "required": [
          "plan",
          "usage",
          "day_resets_at",
          "month_resets_at"
        ],
        "properties": {
          "plan": {
            "type": "object",
            "required": [
              "paid",
              "slug",
              "name",
              "valid_until"
            ],
            "properties": {
              "paid": {
                "type": "boolean"
              },
              "slug": {
                "type": "string",
                "example": "free"
              },
              "name": {
                "type": "string"
              },
              "valid_until": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Paid until; null on the free plan."
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "day_resets_at": {
            "type": "string",
            "format": "date-time"
          },
          "month_resets_at": {
            "type": "string",
            "format": "date-time",
            "description": "End of the calendar month (free plan) or of the current subscription period (paid plans)."
          }
        }
      }
    }
  }
}
