GET /api/v1/label
Generate a printable label (PDF or PNG).
Returns a barcode laid out on a standard label size, with the encoded text shown above the barcode by default. PDFs are sized exactly to the label dimensions so thermal printers pick up the size automatically.
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
text | yes | — | The data to encode (max 7089 chars) |
type | yes | — | code128, qr, microqr, datamatrix, upca, ean13, ean8 |
size | no | 4x6 | Label size — inches: 4x6, 4x4, 4x3, 4x2, 3.5x1.125, 3x3, 3x2, 3x1, 2x3, 2.25x1.25, 2.25x0.75, 2x1, 1.75x0.5, 1.5x1.5; mm: 100x150, 100x50, 70x50, 62x100, 50x30, 50x25, 40x20, 38x25, 25x10 |
orientation | no | landscape | portrait or landscape |
qty | no | 1 | Number of pages, 1–500 (pdf format only) |
showtext | no | true | Show the encoded text above the barcode |
format | no | pdf | pdf or png (png renders page 1 only, at 300 DPI) |
PDF captions use a built-in Latin-1 (WinAnsi) font, so non-Latin text (e.g. CJK) may not render in format=pdf captions — use format=png (full Unicode font) for non-Latin captions.
Examples
A 2x1" thermal label PDF:
/api/v1/label?text=SKU-12345&type=code128&size=2x150 copies in one PDF:
/api/v1/label?text=LOT-2026-08&type=qr&size=2x1&qty=50Barcode-only PNG label (no caption):
/api/v1/label?text=SKU-12345&type=qr&size=50x30&format=png&showtext=falseMigrating from /api/generate-barcode
The legacy /api/generate-barcode endpoint still works but is deprecated (Deprecation: true response header, with a Link: </api/v1/label>; rel="successor-version" header pointing at its replacement). It maps 1:1 onto /api/v1/label — same text, type, size, orientation, and qty parameters. The legacy endpoint always returns a PDF with the text shown (there is no format or showtext parameter).
Behavior changes on the legacy endpoint
Successful responses are byte-for-byte what they were, but four things changed when the endpoint moved onto the v1 stack:
- Error bodies changed shape. Errors used to be
{"error": "<string>"}and are now{"error": {"code": "...", "message": "..."}}. - The endpoint is now rate-limited. It shares the same per-IP limit as the v1 endpoints, so a
429is possible where it never was before. formatandshowtextare now validated. Both were previously ignored; an invalid value for either is now a400even though the endpoint still ignores valid ones (PDF with text, always).- Responses now include CORS headers, so browser callers can reach the endpoint cross-origin.