{ "openapi": "3.1.0", "info": { "title": "Barcode.codes render API", "version": "2.0.0", "summary": "Barcode images from a URL, drawn by the Barcode.codes generator.", "description": "Draws any of the generator's 23 barcode types as SVG, PNG, WebP, JPEG, PDF or EPS from the type, the data and the generator's options in the URL. No key. Images are cached for a year; at most 120 new images per address per minute. It draws images only and does not look products up. Documentation: https://barcode.codes/barcode-api" }, "servers": [ { "url": "https://barcode.codes" } ], "paths": { "/render/{type}/{data}.{format}": { "get": { "operationId": "renderBarcode", "summary": "Draw a barcode", "parameters": [ { "name": "type", "in": "path", "required": true, "description": "The barcode type.", "schema": { "type": "string", "enum": [ "qrcode", "gs1dlqrcode", "datamatrix", "gs1datamatrix", "upca", "upce", "ean13", "ean8", "isbn", "issn", "ismn", "code128", "gs1-128", "code39", "code39ext", "code93", "code93ext", "interleaved2of5", "itf14", "pdf417", "azteccode", "microqrcode", "maxicode" ] }, "example": "qrcode" }, { "name": "data", "in": "path", "required": true, "description": "The data, percent-encoded (encodeURIComponent), at most as long as the type allows (qrcode 300, gs1dlqrcode 300, datamatrix 300, gs1datamatrix 300, upca 12, upce 8, ean13 13, ean8 8, isbn 17, issn 13, ismn 17, code128 80, gs1-128 150, code39 43, code39ext 43, code93 80, code93ext 80, interleaved2of5 30, itf14 14, pdf417 300, azteccode 300, microqrcode 35, maxicode 138); the whole path at most 1200 characters.", "schema": { "type": "string", "minLength": 1 }, "example": "https://barcode.codes/" }, { "name": "format", "in": "path", "required": true, "description": "The file format: svg, png, webp, jpg (or jpeg), pdf or eps.", "schema": { "type": "string", "enum": [ "svg", "png", "webp", "jpg", "pdf", "eps", "jpeg" ] }, "example": "svg" }, { "name": "x", "in": "query", "description": "X-dimension: the width of the narrowest bar or module, in millimeters. Applies to all types. Values: 0.1 to 3 mm, up to 4 decimals. Default: the type's standard: 0.33 mm for UPC and EAN, 0.495 mm for ITF-14 and GS1-128, 0.85 mm for MaxiCode, 0.33 mm for the others.", "schema": { "type": "number", "minimum": 0.1, "maximum": 3 } }, { "name": "height", "in": "query", "description": "Bar height in millimeters. Applies to 1D types. Values: 1 to 200 mm, up to 2 decimals. Default: the type's standard: 22.85 mm for UPC and EAN (18.23 for EAN-8), 31.75 mm for ITF-14 and GS1-128, 15 mm for the others.", "schema": { "type": "number", "minimum": 1, "maximum": 200 } }, { "name": "bwr", "in": "query", "description": "Bar width reduction (ink-spread compensation), in millimeters: each bar is drawn thinner by this amount. Applies to all types. Values: 0 to 0.5 mm, up to 4 decimals. Default: 0.", "schema": { "type": "number", "minimum": 0, "maximum": 0.5 } }, { "name": "qz", "in": "query", "description": "Quiet zone in modules: one number for every side, or four (top, right, bottom, left) separated by commas. Applies to all types. Values: 0 to 50 modules, one value or four. Default: the type's minimum: UPC-A 9 left and right, EAN-13 11 and 7, other 1D codes 10, 2D codes 4.", "schema": { "type": "string", "pattern": "^\\d{1,2}(,\\d{1,2},\\d{1,2},\\d{1,2})?$" } }, { "name": "hri", "in": "query", "description": "The text under the bars. Applies to 1D types. Values: true or false. Default: true.", "schema": { "type": "boolean" } }, { "name": "hrisize", "in": "query", "description": "Size of the text under the bars, in points on paper. Applies to 1D types except UPC, EAN, ISBN, ISSN and ISMN. Values: 4 to 36 pt, whole numbers. Default: 10.", "schema": { "type": "integer", "minimum": 4, "maximum": 36 } }, { "name": "hrialign", "in": "query", "description": "Alignment of the text under the bars. Applies to 1D types except UPC, EAN, ISBN, ISSN and ISMN. Values: left, center, right, justify. Default: center.", "schema": { "type": "string", "enum": [ "left", "center", "right", "justify" ] } }, { "name": "hrifont", "in": "query", "description": "Font of the text under the bars: OCR-B, or Helvetica (sans). Applies to 1D types except UPC, EAN, ISBN, ISSN and ISMN. Values: ocrb, sans. Default: ocrb.", "schema": { "type": "string", "enum": [ "ocrb", "sans" ] } }, { "name": "addon", "in": "query", "description": "EAN-2 or EAN-5 add-on digits after the main symbol. Applies to UPC-A, UPC-E, EAN-13, EAN-8, ISBN, ISSN, ISMN. Values: 2 or 5 digits, or empty. Default: empty.", "schema": { "type": "string", "pattern": "^(\\d{2}|\\d{5})?$" } }, { "name": "check", "in": "query", "description": "Add the optional check character (Code 39 mod 43, Interleaved 2 of 5 mod 10). Applies to Code 39, Code 39 Full ASCII, Interleaved 2 of 5. Values: true or false. Default: false.", "schema": { "type": "boolean" } }, { "name": "set", "in": "query", "description": "Code 128 code set: automatic (the shortest), or A, B or C only. Applies to Code 128. Values: auto, A, B, C. Default: auto.", "schema": { "type": "string", "enum": [ "auto", "A", "B", "C" ] } }, { "name": "fnc", "in": "query", "description": "Read ^FNC1 to ^FNC4 in the data as function characters. Applies to Code 128. Values: true or false. Default: false.", "schema": { "type": "boolean" } }, { "name": "bearer", "in": "query", "description": "Bearer bars: a frame 2 × X wide, a 4.83 mm frame for plate printing, or none. Applies to ITF-14. Values: frame-2x, frame-plate, none. Default: frame-2x.", "schema": { "type": "string", "enum": [ "frame-2x", "frame-plate", "none" ] } }, { "name": "ecc", "in": "query", "description": "QR Code error correction level. Applies to QR Code. Values: L, M, Q, H. Default: M.", "schema": { "type": "string", "enum": [ "L", "M", "Q", "H" ] } }, { "name": "qrversion", "in": "query", "description": "QR Code version (size), or auto for the smallest that fits. Applies to QR Code. Values: auto, or 1 to 40. Default: auto.", "schema": { "type": "string", "pattern": "^(auto|[1-9]|[1-3]\\d|40)$" } }, { "name": "dmshape", "in": "query", "description": "Data Matrix shape. Applies to Data Matrix. Values: square, rectangle. Default: square.", "schema": { "type": "string", "enum": [ "square", "rectangle" ] } }, { "name": "dmsize", "in": "query", "description": "Data Matrix size in rows x columns, or auto for the smallest that fits. Applies to Data Matrix. Values: auto, or a size such as 10x10 (square) or 8x18 (rectangle). Default: auto.", "schema": { "type": "string", "enum": [ "auto", "10x10", "12x12", "14x14", "16x16", "18x18", "20x20", "22x22", "24x24", "26x26", "32x32", "36x36", "40x40", "44x44", "48x48", "52x52", "64x64", "72x72", "80x80", "88x88", "96x96", "104x104", "120x120", "132x132", "144x144", "8x18", "8x32", "12x26", "12x36", "16x36", "16x48" ] } }, { "name": "pdfcols", "in": "query", "description": "PDF417 data columns, or 0 for automatic. Applies to PDF417. Values: 0 to 30, whole numbers. Default: 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 30 } }, { "name": "pdfrows", "in": "query", "description": "PDF417 rows (a minimum), or 0 for automatic. Applies to PDF417. Values: 0, or 3 to 90. Default: 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 90 } }, { "name": "pdfec", "in": "query", "description": "PDF417 error correction level, or auto (by data length). Applies to PDF417. Values: auto, or 0 to 8. Default: auto.", "schema": { "type": "string", "pattern": "^(auto|[0-8])$" } }, { "name": "pdfcompact", "in": "query", "description": "Compact PDF417 (fewer bars per row). Applies to PDF417. Values: true or false. Default: false.", "schema": { "type": "boolean" } }, { "name": "aztecformat", "in": "query", "description": "Aztec Code format: full range, or compact (1 to 4 layers). Applies to Aztec Code. Values: full, compact. Default: full.", "schema": { "type": "string", "enum": [ "full", "compact" ] } }, { "name": "azteclayers", "in": "query", "description": "Aztec Code layers, or 0 for the smallest that fits. Applies to Aztec Code. Values: 0 to 32, whole numbers. Default: 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 32 } }, { "name": "aztecec", "in": "query", "description": "Aztec Code error correction, in percent of the data. Applies to Aztec Code. Values: 5 to 95 %, whole numbers. Default: 23.", "schema": { "type": "integer", "minimum": 5, "maximum": 95 } }, { "name": "mqrversion", "in": "query", "description": "Micro QR Code version, or auto for the smallest that fits. Applies to Micro QR Code. Values: auto, M1, M2, M3, M4. Default: auto.", "schema": { "type": "string", "enum": [ "auto", "M1", "M2", "M3", "M4" ] } }, { "name": "mqrec", "in": "query", "description": "Micro QR Code error correction (Q on M4 only). Applies to Micro QR Code. Values: L, M, Q. Default: L.", "schema": { "type": "string", "enum": [ "L", "M", "Q" ] } }, { "name": "maximode", "in": "query", "description": "MaxiCode mode: 4 (standard), 5 (enhanced) or auto (5 when the data fits). Applies to MaxiCode. Values: auto, 4, 5. Default: auto.", "schema": { "type": "string", "enum": [ "auto", "4", "5" ] } }, { "name": "fg", "in": "query", "description": "Bar or module color. Applies to all types. Values: six hex digits, without #. Default: 000000.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } }, { "name": "bg", "in": "query", "description": "Background color. Colors below 20% estimated symbol contrast are refused. Applies to all types. Values: six hex digits, without #. Default: FFFFFF.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } }, { "name": "module", "in": "query", "description": "QR Code module shape. Applies to QR Code. Values: square, rounded, dots. Default: square.", "schema": { "type": "string", "enum": [ "square", "rounded", "dots" ] } }, { "name": "eyeframe", "in": "query", "description": "Shape of the three finder frames. Applies to QR Code. Values: square, rounded, circle. Default: square.", "schema": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, { "name": "eyeball", "in": "query", "description": "Shape of the three finder centers. Applies to QR Code. Values: square, rounded, circle. Default: square.", "schema": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, { "name": "gradient", "in": "query", "description": "A gradient from the module color to this color, or none. Applies to QR Code. Values: six hex digits without #, or none. Default: none.", "schema": { "type": "string", "pattern": "^([0-9a-fA-F]{6}|none)$" } }, { "name": "eyecolor", "in": "query", "description": "Another color for the finder patterns, or none. Applies to QR Code. Values: six hex digits without #, or none. Default: none.", "schema": { "type": "string", "pattern": "^([0-9a-fA-F]{6}|none)$" } }, { "name": "cta", "in": "query", "description": "A call-to-action frame with this text under the code (empty for none). Applies to QR Code. Values: text, at most 24 characters. Default: empty.", "schema": { "type": "string", "maxLength": 24 } }, { "name": "ctastyle", "in": "query", "description": "Call-to-action frame style: a bar below, or a box and bar. Needs cta. Applies to QR Code with cta. Values: bar, box. Default: bar.", "schema": { "type": "string", "enum": [ "bar", "box" ] } }, { "name": "ctacolor", "in": "query", "description": "Call-to-action frame color; the text turns black or white for contrast. Needs cta. Applies to QR Code with cta. Values: six hex digits, without #. Default: 000000.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } }, { "name": "utm_source", "in": "query", "description": "Adds utm_source to a web address in the data, as the generator's link tracking does. Applies to QR Code with an http or https address. Values: text, at most 100 characters. Default: empty.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "utm_medium", "in": "query", "description": "Adds utm_medium to a web address in the data, as the generator's link tracking does. Applies to QR Code with an http or https address. Values: text, at most 100 characters. Default: empty.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "utm_campaign", "in": "query", "description": "Adds utm_campaign to a web address in the data, as the generator's link tracking does. Applies to QR Code with an http or https address. Values: text, at most 100 characters. Default: empty.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "utm_term", "in": "query", "description": "Adds utm_term to a web address in the data, as the generator's link tracking does. Applies to QR Code with an http or https address. Values: text, at most 100 characters. Default: empty.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "utm_content", "in": "query", "description": "Adds utm_content to a web address in the data, as the generator's link tracking does. Applies to QR Code with an http or https address. Values: text, at most 100 characters. Default: empty.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "above", "in": "query", "description": "Label text above the code, in Helvetica or Courier. Applies to all types. Values: text, at most 80 characters. Default: empty.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "below", "in": "query", "description": "Label text below the code. Applies to all types. Values: text, at most 80 characters. Default: empty.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "labelsize", "in": "query", "description": "Label text size, in points. Applies to all types. Values: 4 to 48 pt, whole numbers. Default: 9.", "schema": { "type": "integer", "minimum": 4, "maximum": 48 } }, { "name": "labelfont", "in": "query", "description": "Label font: sans (Helvetica) or mono (Courier). Applies to all types. Values: sans, mono. Default: sans.", "schema": { "type": "string", "enum": [ "sans", "mono" ] } }, { "name": "labelalign", "in": "query", "description": "Label alignment. Applies to all types. Values: left, center, right. Default: center.", "schema": { "type": "string", "enum": [ "left", "center", "right" ] } }, { "name": "margin", "in": "query", "description": "Blank margin outside the quiet zone, in millimeters. Applies to all types. Values: 0 to 50 mm, up to 1 decimals. Default: 0.", "schema": { "type": "number", "minimum": 0, "maximum": 50 } }, { "name": "border", "in": "query", "description": "Border width at the outer edge, in millimeters. Applies to all types. Values: 0 to 10 mm, up to 1 decimals. Default: 0.", "schema": { "type": "number", "minimum": 0, "maximum": 10 } }, { "name": "radius", "in": "query", "description": "Rounded corners of the border and background, in millimeters. Applies to all types. Values: 0 to 50 mm, up to 1 decimals. Default: 0.", "schema": { "type": "number", "minimum": 0, "maximum": 50 } }, { "name": "bordercolor", "in": "query", "description": "Border color. Applies to all types. Values: six hex digits, without #. Default: 000000.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } }, { "name": "rotate", "in": "query", "description": "Rotation in degrees. Applies to all types. Values: 0, 90, 180, 270. Default: 0.", "schema": { "type": "string", "enum": [ "0", "90", "180", "270" ] } }, { "name": "transparent", "in": "query", "description": "A transparent background (SVG, PNG and WebP; JPEG, PDF and EPS keep the background color). Applies to all types. Values: true or false. Default: false.", "schema": { "type": "boolean" } }, { "name": "dpi", "in": "query", "description": "Resolution of PNG, WebP and JPEG files: whole printer dots per module, and the DPI written in PNG and JPEG. Applies to all types, PNG, WebP and JPEG. Values: 72 to 1200 DPI, whole numbers. Default: 300.", "schema": { "type": "integer", "minimum": 72, "maximum": 1200 } }, { "name": "readback", "in": "query", "description": "Read the drawing back with the decoder and report it in the x-barcode-readback header: match, mismatch; read=\"…\", or fail. A styled QR Code is always read back and refused (422) when it does not read.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The barcode file. SVG carries its print size in millimeters; PNG and JPEG carry the DPI; images are at most 4 million pixels.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "public, max-age=31536000, immutable" } }, "Link": { "description": "The canonical URL of this file.", "schema": { "type": "string" } }, "X-Barcode-Size": { "description": "The print size in millimeters, and for an image its pixels and DPI.", "schema": { "type": "string" } }, "X-Barcode-Readback": { "description": "With readback=true, or for a styled QR Code: match, mismatch; read=\"…\", or fail.", "schema": { "type": "string" } } }, "content": { "image/svg+xml": { "schema": { "type": "string" }, "examples": { "qrcode": { "summary": "QR Code", "externalValue": "https://barcode.codes/render/qrcode/https%3A%2F%2Fbarcode.codes%2F.svg" }, "gs1dlqrcode": { "summary": "GS1 Digital Link QR", "externalValue": "https://barcode.codes/render/gs1dlqrcode/https%3A%2F%2Fid.gs1.org%2F01%2F09506000134352.svg" }, "datamatrix": { "summary": "Data Matrix", "externalValue": "https://barcode.codes/render/datamatrix/barcode.codes.svg" }, "gs1datamatrix": { "summary": "GS1 DataMatrix", "externalValue": "https://barcode.codes/render/gs1datamatrix/%2801%2909506000134352%2817%29271231%2810%29LOT42.svg" }, "upca": { "summary": "UPC-A", "externalValue": "https://barcode.codes/render/upca/03600029145.svg" }, "upce": { "summary": "UPC-E", "externalValue": "https://barcode.codes/render/upce/0123456.svg" }, "ean13": { "summary": "EAN-13", "externalValue": "https://barcode.codes/render/ean13/590123412345.svg" }, "ean8": { "summary": "EAN-8", "externalValue": "https://barcode.codes/render/ean8/9638507.svg" }, "isbn": { "summary": "ISBN", "externalValue": "https://barcode.codes/render/isbn/978-1-56581-231-4.svg" }, "issn": { "summary": "ISSN", "externalValue": "https://barcode.codes/render/issn/0311-175X%2000.svg" }, "ismn": { "summary": "ISMN", "externalValue": "https://barcode.codes/render/ismn/979-0-2605-3211-3.svg" }, "code128": { "summary": "Code 128", "externalValue": "https://barcode.codes/render/code128/BC-2026-0042.svg" }, "gs1-128": { "summary": "GS1-128", "externalValue": "https://barcode.codes/render/gs1-128/%2801%2909506000134352%2810%29LOT42.svg" }, "code39": { "summary": "Code 39", "externalValue": "https://barcode.codes/render/code39/CODE39.svg" }, "code39ext": { "summary": "Code 39 Full ASCII", "externalValue": "https://barcode.codes/render/code39ext/Code%2039%20Full%20ASCII.svg" }, "code93": { "summary": "Code 93", "externalValue": "https://barcode.codes/render/code93/CODE93.svg" }, "code93ext": { "summary": "Code 93 Full ASCII", "externalValue": "https://barcode.codes/render/code93ext/Code%2093%20Full%20ASCII.svg" }, "interleaved2of5": { "summary": "Interleaved 2 of 5", "externalValue": "https://barcode.codes/render/interleaved2of5/12345678.svg" }, "itf14": { "summary": "ITF-14", "externalValue": "https://barcode.codes/render/itf14/1540014128876.svg" }, "pdf417": { "summary": "PDF417", "externalValue": "https://barcode.codes/render/pdf417/barcode.codes.svg" }, "azteccode": { "summary": "Aztec", "externalValue": "https://barcode.codes/render/azteccode/barcode.codes.svg" }, "microqrcode": { "summary": "Micro QR Code", "externalValue": "https://barcode.codes/render/microqrcode/BARCODE.CODES.svg" }, "maxicode": { "summary": "MaxiCode", "externalValue": "https://barcode.codes/render/maxicode/Barcode.codes%20MaxiCode.svg" } } }, "image/png": { "schema": { "type": "string", "format": "binary" }, "examples": { "qrcode": { "summary": "QR Code as PNG", "externalValue": "https://barcode.codes/render/qrcode/https%3A%2F%2Fbarcode.codes%2F.png" } } }, "image/webp": { "schema": { "type": "string", "format": "binary" }, "examples": { "qrcode": { "summary": "QR Code as WebP", "externalValue": "https://barcode.codes/render/qrcode/https%3A%2F%2Fbarcode.codes%2F.webp" } } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" }, "examples": { "qrcode": { "summary": "QR Code as JPEG", "externalValue": "https://barcode.codes/render/qrcode/https%3A%2F%2Fbarcode.codes%2F.jpg" } } }, "application/pdf": { "schema": { "type": "string", "format": "binary" }, "examples": { "qrcode": { "summary": "QR Code as PDF", "externalValue": "https://barcode.codes/render/qrcode/https%3A%2F%2Fbarcode.codes%2F.pdf" } } }, "application/postscript": { "schema": { "type": "string", "format": "binary" }, "examples": { "qrcode": { "summary": "QR Code as EPS", "externalValue": "https://barcode.codes/render/qrcode/https%3A%2F%2Fbarcode.codes%2F.eps" } } } } }, "400": { "description": "unknown_format: The path does not end in a format the API writes: .svg, .png, .webp, .jpg, .pdf, .eps. empty_data: There is no data between the type and the format. data_too_long: The data is longer than the type allows. invalid_data: The type cannot encode the data, with the reason, such as a wrong check digit or GS1 data the GS1 Barcode Syntax Engine refuses. unknown_parameter: A query parameter that the API does not know. invalid_parameter: A parameter with a value outside its range, one that does not apply to the type or format, or colors with too little contrast. too_large: The file would be too large: an SVG over 256 KB, a PDF or EPS over 1 MB, or an image over 4 million pixels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_type: A barcode type the API does not draw. not_found: A path that is not /render/{type}/{data}.{format}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: A method other than GET, HEAD or OPTIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "path_too_long: The path or the query is longer than 1200 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "does_not_scan: A styled QR Code that the decoder does not read back as the data; the generator refuses to save it too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 120 new images from one address in a minute; wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "render_failed: The drawing failed for another reason; the message says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "unknown_format", "empty_data", "data_too_long", "invalid_data", "unknown_parameter", "invalid_parameter", "too_large", "unknown_type", "not_found", "method_not_allowed", "path_too_long", "does_not_scan", "rate_limited", "render_failed" ] }, "message": { "type": "string" }, "parameter": { "type": "string", "description": "The parameter at fault: type, data, format or a query parameter." } } } } } } } }