{"openapi":"3.1.0","info":{"title":"Barcode Hub API","version":"latest","description":"Barcode Hub decodes barcodes from image uploads, raw image payloads, and\nURLs. Successful decode responses contain only the decode result body.\n"},"servers":[{"url":"http://localhost:8080"}],"tags":[{"name":"decode","description":"Barcode decoding operations."}],"paths":{"/decode":{"post":{"tags":["decode"],"operationId":"decodeMultipart","summary":"Decode barcodes from one uploaded image file.","description":"Accepts `multipart/form-data` with exactly one uploaded image file.\nUploads with zero files or more than one file are rejected with 400.\n","parameters":[{"$ref":"#/components/parameters/Types"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Image file to decode."}}},"encoding":{"file":{"contentType":"image/png, image/jpeg, image/webp, image/gif, image/bmp, image/tiff"}}}}},"responses":{"200":{"$ref":"#/components/responses/DecodeSuccess"},"400":{"$ref":"#/components/responses/BadRequest"},"405":{"$ref":"#/components/responses/MethodDisabled"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"504":{"$ref":"#/components/responses/GatewayTimeout"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"tags":["decode"],"operationId":"decodeBinary","summary":"Decode barcodes from a raw image request body.","description":"Accepts raw binary image bytes. The request Content-Type must be an\nallowed `image/*` media type.\n","parameters":[{"$ref":"#/components/parameters/Types"}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary","description":"Raw image bytes to decode."}},"image/jpeg":{"schema":{"type":"string","format":"binary","description":"Raw image bytes to decode."}},"image/webp":{"schema":{"type":"string","format":"binary","description":"Raw image bytes to decode."}},"image/gif":{"schema":{"type":"string","format":"binary","description":"Raw image bytes to decode."}},"image/bmp":{"schema":{"type":"string","format":"binary","description":"Raw image bytes to decode."}},"image/tiff":{"schema":{"type":"string","format":"binary","description":"Raw image bytes to decode."}}}},"responses":{"200":{"$ref":"#/components/responses/DecodeSuccess"},"400":{"$ref":"#/components/responses/BadRequest"},"405":{"$ref":"#/components/responses/MethodDisabled"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"504":{"$ref":"#/components/responses/GatewayTimeout"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"parameters":{"Url":{"name":"url","in":"query","required":true,"description":"Image URL to fetch and decode. Supported schemes are configured by deployment policy.\n\nFetched resource Content-Type must be one of: image/png, image/jpeg, image/webp, image/gif, image/bmp, image/tiff.","schema":{"type":"string","pattern":"^(https?|data|file):"},"examples":{"httpImage":{"summary":"HTTP image","value":"https://example.com/image.jpg"},"dataBase64":{"summary":"Base64 data URL","value":"data:image/png;base64,iVBORw0KGgo="},"fileUrl":{"summary":"Local file URL","value":"file:///data/input/image.png"}}},"Types":{"name":"types","in":"query","required":false,"description":"Comma-separated list of requested barcode types. Canonical example:\n`types=EAN13,UPCA`. Requested values must stay inside the configured\nallowlist; otherwise the request is rejected with 400.\n","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/BarcodeType"},"default":["EAN13","EAN8","UPCA","UPCE","QRCode","DataMatrix"]},"examples":{"retail":{"summary":"Retail product barcodes","value":["EAN13","UPCA"]},"mixed":{"summary":"Linear and matrix codes","value":["EAN13","UPCA","QRCode"]}}}},"responses":{"DecodeSuccess":{"description":"Decode completed successfully. The barcode array may be empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeResult"},"examples":{"oneBarcode":{"summary":"One EAN-13 result","value":{"barcodes":[{"text":"4607084351323","data":"NDYwNzA4NDM1MTMyMw==","type":"EAN13","valid":"yes"}]}},"empty":{"summary":"No barcodes found","value":{"barcodes":[]}}}}}},"BadRequest":{"description":"Bad request, such as invalid `types` or multiple uploaded files.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"bad_request","message":"Request is invalid.","details":{}}}}}},"MethodDisabled":{"description":"This HTTP method is disabled by configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"method_disabled","message":"This decode method is disabled.","details":{}}}}}},"PayloadTooLarge":{"description":"POST or PUT request body exceeds configured byte limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"payload_too_large","message":"Request body exceeds configured limits.","details":{}}}}}},"UnsupportedMediaType":{"description":"Request Content-Type is not an allowed image media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unsupported_media_type","message":"Only image/* content types are accepted.","details":{}}}}}},"UnprocessableContent":{"description":"GET resource violates configured size or image dimension limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unprocessable_content","message":"Fetched resource violates configured limits.","details":{}}}}}},"GatewayTimeout":{"description":"External resource fetch timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"resource_timeout","message":"Resource download timed out.","details":{}}}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"Unexpected server error.","details":{}}}}}}},"schemas":{"DecodeResult":{"additionalProperties":false,"properties":{"barcodes":{"items":{"$ref":"#/components/schemas/Barcode"},"type":"array"}},"required":["barcodes"],"type":"object","title":"DecodeResult"},"Barcode":{"additionalProperties":false,"properties":{"text":{"description":"Decoded text returned by ZXing-C++.","type":"string"},"data":{"contentEncoding":"base64","description":"Standard base64 representation of raw decoded payload bytes, without a data: prefix.","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string"},"type":{"$ref":"#/components/schemas/BarcodeType"},"valid":{"$ref":"#/components/schemas/BarcodeValidity"}},"required":["text","data","type","valid"],"type":"object"},"BarcodeType":{"enum":["Codabar","Code39","Code39Std","Code39Ext","Code32","PZN","Code93","Code128","ITF","ITF14","DataBar","DataBarOmni","DataBarStk","DataBarStkOmni","DataBarLtd","DataBarExp","DataBarExpStk","EAN13","EAN8","EAN5","EAN2","ISBN","UPCA","UPCE","Telepen","TelepenAlpha","TelepenNumeric","OtherBarcode","DXFilmEdge","PDF417","CompactPDF417","MicroPDF417","Aztec","AztecCode","AztecRune","QRCode","QRCodeModel1","QRCodeModel2","MicroQRCode","RMQRCode","DataMatrix","MaxiCode"],"type":"string","description":"Canonical ZXing-C++ barcode format ID emitted by Barcode Hub."},"BarcodeValidity":{"enum":["yes","no","unknown"],"type":"string","description":"Decoder validity mapped from ZXing-C++: true=yes, false=no, absent=unknown."},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","details"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable error summary."},"details":{"type":"object","additionalProperties":true,"description":"Optional structured diagnostic details."}}}}}}}}