API Documentation

The QRScanner API lets you decode (scan) a QR code from an image. Send an image — either as a file upload or as a base64 string — and the API returns the decoded content. This documentation describes how to authenticate, make requests, and handle responses.

Base URL

All API requests are made to a single endpoint:

POST https://qrscanner.net/api/qr-code-scanner

Authentication

To access the QRScanner API, include your API key in the request header as a Bearer token. Each request is authenticated with your API key and counts toward your plan's quota. You can generate or regenerate your API key from the dashboard (an active API plan is required).

Header:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key.

API Endpoint

Image Input Methods

The API accepts a POST request with a single required file parameter. You can provide the image in one of two ways:

Option A — multipart/form-data (file upload):
Header:
    Authorization: Bearer YOUR_API_KEY
    Content-Type: multipart/form-data
Form Data:
    file: (file) The image containing the QR code.

Option B — application/json (base64 string):
Header:
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json
JSON Body:
    { "file": "data:image/png;base64,iVBORw0KG..." }

Optional fields (both methods):
    tool: defaults to "qrcode".
    ext:  image extension (e.g. "png", "jpg") — used only with a base64
          string when the type cannot be detected automatically.

The file value may be a raw base64 string or a full data: URI; both standard and URL-safe base64 are accepted.

Curl Request Example

Replace YOUR_API_KEY with your API key.

# File upload (multipart/form-data)
curl -X POST "https://qrscanner.net/api/qr-code-scanner" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "file=@/path/to/qr-code.png"

# JSON with a base64 image string
curl -X POST "https://qrscanner.net/api/qr-code-scanner" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"file":"data:image/png;base64,iVBORw0KG..."}'

Response Format

The API always responds with JSON. The shape of the response depends on whether the request succeeded.

Success Response

{ "success": true, "data": "https://example.com", "error": null }

success: true when the QR code was decoded.

data: the decoded QR code content (e.g. a URL, text, or other encoded payload).

error: null on success.

Error Responses

When the image cannot be decoded, the request returns HTTP 422:

{ "success": false, "data": null, "error": "Unable to scan the QR code." }

Validation Errors

A missing or invalid file returns HTTP 422 with a field-keyed message:

{ "file": ["The file field is required."] }                          // file missing
{ "file": ["The uploaded file must be an image."] }                  // non-image upload
{ "file": ["The file is not a valid base64 string."] }               // bad base64
{ "file": ["The file must be an uploaded image or a base64 image string."] }

Authentication & Quota Errors

{ "error": true, "message": "Unauthorized" }                        // HTTP 401 (missing Bearer token)
{ "error": true, "message": "Invalid API token" }                   // HTTP 401 (token not recognised)
{ "error": true, "message": "API not registered" }                  // HTTP 404
{ "error": true, "message": "Purchase API plan to get more quota" } // HTTP 402 (no remaining quota)

Rate Limit Exceeded

Requests are throttled per API key. When you exceed the allowed number of requests within a time window, the API returns HTTP 429 with a Retry-After header (seconds to wait before retrying):

{ "error": true, "success": false, "message": "Too many requests per minute" }

Gateway Error

If the upstream scanner service is unreachable, the request returns HTTP 502 with a generic message (internal details are logged server-side, not exposed):

{ "success": false, "data": null, "error": "The scanner service is temporarily unavailable. Please try again later." }

Authentication Failed

If the request cannot be authenticated with the scanner service, it returns HTTP 401. No quota is consumed — retry after a short delay:

{ "success": false, "data": null, "error": "Authentication failed. Please try again later." }

success: false for any error.

data: null when no result is available.

error / message: a description of what went wrong.