apyhub
Back
▣ DATA EXTRACTION · DEVELOPER TOOLS

Decode QR & Barcode API

What it does

The Barcode Reader API finds every QR code and barcode in an image and returns the decoded content in reading order. Send the image as image_base64 or image_url.

It reads QR, Data Matrix, PDF417, Aztec, Code 128, EAN-13, UPC-A and other common symbologies. Set formats to look for specific types only. Set multiple to false to return only the first match. The default, true, returns all of them.

The response has a count and a results array. Each result gives the decoded text, its format and content_type, and its position and orientation in the image. Known payloads such as Wi-Fi, vCard, EPC and crypto addresses also come back as parsed fields. QR results include the ec_level. When the raw bytes differ from the text, you get them in bytes_base64.

Teams use the Barcode Reader API to decode QR codes from screenshots and tickets and to read product barcodes from packaging photos. Others scan shipping labels in bulk or add a QR code scanner to image uploads.

To check a payment or GS1 payload after decoding it, send it to the Validate Payment & Generate QR API. To create codes, use the Generate QR Code API or the Generate Barcode API.

POST
Read every QR code and barcode in an image
https://api.eu.apyhub.com/callable-labs/read-qr-barcode-image/decode

QUICKSTART

GUIDE

Quickstart

Decode a QR code or barcode from an image by sending either an image URL or base64 image data.

curl -X POST "https://api.eu.apyhub.com/callable-labs/read-qr-barcode-image/decode" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.phototourl.com/free/2026-09-16-eaa7b05b-0601-419d-802f-9567cf8fda07.png"
  }'

What you'll get back

Returns a JSON object with a count integer and a results array. count is the number of symbols decoded, and each item in results is an object with format, text, content_type, position, and orientation fields, plus optional decoded details like parsed, ec_level, bytes_base64, and symbology_identifier.

{
  "count": 1,
  "results": [
    {
      "format": "qr",
      "text": "Hello ApyHub",
      "content_type": "text",
      "position": {
        "top_left": [1, 1],
        "top_right": [199, 0],
        "bottom_right": [200, 200],
        "bottom_left": [0, 199]
      },
      "orientation": 0,
      "ec_level": "L",
      "symbology_identifier": "]Q1"
    }
  ]
}
TRY ITLIVE · 20 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
Supply exactly one of `image_base64` or `image_url`.
By image URL*
Public HTTP(S) URL of the image to decode. Supply exactly one of `image_base64` or `image_url`. Fetched over a size-guarded, SSRF-protected connection; max 5 MB.

About this endpoint

What it does

Decodes every QR code and barcode found in an image and returns the decoded symbols in reader order. You can supply the image either as a public URL or as base64, and optionally restrict decoding to specific symbologies.

Request Body

ParameterTypeDescription
image_base64StringImage to decode as base64: PNG, JPEG, WebP, GIF, BMP or TIFF, with or without a data: prefix. Supply exactly one of image_base64 or image_url. Max 5 MB.
image_urlStringPublic HTTP(S) URL of the image to decode. Supply exactly one of image_base64 or image_url. Fetched over a size-guarded, SSRF-protected connection; max 5 MB.
formatsString ArrayRestrict detection to these symbologies for speed and accuracy: qr, microqr, datamatrix, pdf417, aztec, code128, code39, code93, ean13, ean8, upca, upce, itf, codabar, databar, maxicode. Omit to scan every supported symbology. Unknown values return bad_image.
multipleBooleanReturn every symbol found. Default true. Set false to return only the first symbol.

Response

Returns a JSON object with a count integer field and a results array field. count is the number of symbols decoded, and each item in results is an object describing one decoded symbol and the data recovered from it.

ParameterTypeDescription
countIntegerNumber of symbols decoded.
resultsObject ArrayDecoded symbols, in reader order.
results[].formatStringSymbology of the symbol, e.g. qr, microqr, datamatrix, pdf417, aztec, code128, ean13 or upca.
results[].textStringDecoded text of the symbol.
results[].content_typeStringClassification of the text: url, wifi, vcard, mecard, email, sms, tel, geo, event, whatsapp, epc, crypto or text.
results[].positionObjectFour corner points in pixels: top_left, top_right, bottom_right and bottom_left, each as [x, y].
results[].orientationIntegerRotation of the symbol in degrees.
results[].parsedObjectFields recovered for known content types, e.g. ssid/password/security for Wi-Fi, name/email/phone for vCard, iban/name/amount for EPC/SEPA. null when the type has no structured fields.
results[].ec_levelStringError-correction level (L, M, Q, H) for QR symbols, otherwise null.
results[].bytes_base64StringBase64 of the raw bytes when they differ from the text (binary payloads), otherwise null.
results[].symbology_identifierStringISO/IEC 15424 symbology identifier, e.g. ]Q1, when available.

Notes

The image source is limited to 5 MB whether you send image_base64 or image_url. Images are downscaled to 4096 px on the longest side, and transparency is flattened onto white so transparent codes still read. When using image_url, the image is fetched over an SSRF-protected connection, and formats only accepts the listed symbologies; unknown values return bad_image.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLGenerate Simple QR Code APIDosvak LLCCALLGenerate QR Code APIApyHubCALLValidate Payment & Generate QR APICallable LabsCALLGenerate Branded QR Code APIDosvak LLC

From the blog

Reads that touch this API.

Generate Barcode API vs Generate QR Code API: Full Comparison & Use CasesJul 9, 2026OCR in Python: Extract Text From Images, Scans, Receipts, and InvoicesSep 1, 2026How to Read and Understand API Documentation: A Simple Guide for DevelopersJul 9, 2026HTTP Status Codes: A Developer's Cheat Sheet (With Fixes for the Common Errors)Aug 5, 2026