QR Dex API Documentation

Create and manage QR codes programmatically. Integrate QR code generation into your apps, workflows, and automation tools.

Get API Key Jump to Endpoints OpenAPI Spec

Quick Start

Create your first QR code with a single API call. Replace YOUR_API_KEY with a real key from your team settings. 

curl -X POST https://qrdex.io/api/v1/qr_codes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": {
      "title": "My Website",
      "qr_type": "url",
      "url": "https://example.com"
    }
  }'

Authentication

All API requests require a valid API key passed in the Authorization header using the Bearer scheme. 

Authorization: Bearer YOUR_API_KEY

Plan requirement: API access is available on the Growth plan and above. View pricing

API keys are scoped to a team. All QR codes created with a key belong to that team.

You can create and revoke API keys from your team settings page.

All API responses are returned as JSON with Content-Type: application/json.

Endpoints

The QR Dex API is organized around REST. Base URL: https://qrdex.io/api/v1

GET /api/v1/qr_codes

Retrieve a paginated list of QR codes belonging to your team.

Query Parameters

Parameter Type Required Description
page integer No Page number (default: 1)
per_page integer No Results per page (default: 25, max: 100)
qr_type string No Filter by type: url, email, telephone, sms, whatsapp, wifi

Example Request

curl https://qrdex.io/api/v1/qr_codes \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": 1,
      "title": "My Website",
      "qr_type": "url",
      "short_url": "abc12xyz",
      "full_short_url": "https://qrdex.io/abc12xyz",
      "scans_count": 142,
      "track_scans": true,
      "foreground_color": "#000000",
      "background_color": "#FFFFFF",
      "shape": "rounded",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z",
      "image_url": "https://qrdex.io/api/v1/qr_codes/1/image",
      "svg_image_url": "https://qrdex.io/api/v1/qr_codes/1/image?format=svg",
      "png_image_url": "https://qrdex.io/api/v1/qr_codes/1/image?format=png"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Try it

GET /api/v1/qr_codes/:id

Retrieve a single QR code by its ID, including all type-specific fields.

Path Parameters

Parameter Type Required Description
id integer Yes The QR code ID

Example Request

curl https://qrdex.io/api/v1/qr_codes/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": 1,
    "title": "My Website",
    "qr_type": "url",
    "short_url": "abc12xyz",
    "full_short_url": "https://qrdex.io/abc12xyz",
    "scans_count": 142,
    "track_scans": true,
    "foreground_color": "#000000",
    "background_color": "#FFFFFF",
    "shape": "rounded",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:22:00Z",
    "image_url": "https://qrdex.io/api/v1/qr_codes/1/image",
    "svg_image_url": "https://qrdex.io/api/v1/qr_codes/1/image?format=svg",
    "png_image_url": "https://qrdex.io/api/v1/qr_codes/1/image?format=png",
    "url": "https://example.com",
    "telephone_number": null,
    "email_address": null,
    "email_subject": null,
    "message": null,
    "wifi_ssid": null,
    "wifi_encryption": null,
    "wifi_password": null,
    "wifi_hidden": null,
    "redirect_url": "https://example.com",
    "has_logo": false,
    "logo_url": null
  }
}

Try it

GET /api/v1/qr_codes/:id/image

Download the QR code as an SVG or PNG image. The image uses the QR code's configured foreground color, background color, and logo.

Path Parameters

Parameter Type Required Description
id integer Yes The QR code ID

Query Parameters

Parameter Type Required Description
format string No Use svg or png. Default: svg.
size integer No PNG width and height in pixels. Default: 1024, min: 128, max: 4096. Ignored for SVG.

Response

Returns an image with Content-Type: image/svg+xml or image/png. You can embed it directly in an <img> tag or save it to a file.

Responses include an ETag. Send it back in an If-None-Match header and you'll get 304 Not Modified when the image hasn't changed — the image only changes when the QR code, its colors, its logo, or the requested format/size change.

If the encoded content is too large to render — for example a long URL on an untracked code that also has a logo — the endpoint returns 422 Unprocessable Entity instead of an image.

Example Requests

curl https://qrdex.io/api/v1/qr_codes/1/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o qr-code.svg

curl "https://qrdex.io/api/v1/qr_codes/1/image?format=png&size=1024" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o qr-code.png

Usage

Every QR code response includes an image_url field — use it directly as an image source.

In HTML: <img src="https://qrdex.io/api/v1/qr_codes/1/image" alt="QR Code">

The rendered image respects the QR code's foreground color, background color, and uploaded logo.

Try it

POST /api/v1/qr_codes

Create a new QR code. The required fields vary based on the qr_type you choose.

Body Parameters

All parameters are nested inside a qr_code object.

Parameter Type Required Description
title string Yes Display name for the QR code
qr_type string Yes One of: url, email, telephone, sms, whatsapp, wifi
url string Conditional Required when qr_type is "url"
telephone_number string Conditional Required when qr_type is telephone, sms, or whatsapp
email_address string Conditional Required when qr_type is "email"
email_subject string No Subject line for email type
message string No Body text for sms, whatsapp, or email types
wifi_ssid string Conditional Required when qr_type is "wifi"
wifi_encryption string No For wifi type: WPA, WEP, or nopass
wifi_password string No Password for wifi type
wifi_hidden boolean No Whether the wifi network is hidden
foreground_color string No Hex color code as #RGB or #RRGGBB (default: #000000). Invalid values are rejected with 422.
background_color string No Hex color code as #RGB or #RRGGBB (default: #FFFFFF). Invalid values are rejected with 422.
shape string No QR code shape (default: rounded)
track_scans boolean No Enable scan tracking (default: true)
logo file No Optional multipart upload for a centered QR logo. Supported formats: PNG, JPEG, and WebP. Maximum size 5 MB.

Example Request

curl -X POST https://qrdex.io/api/v1/qr_codes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": {
      "title": "My Website",
      "qr_type": "url",
      "url": "https://example.com"
    }
  }'

Multipart Logo Upload

curl -X POST https://qrdex.io/api/v1/qr_codes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "qr_code[title]=Branded Campaign" \
  -F "qr_code[qr_type]=url" \
  -F "qr_code[url]=https://example.com" \
  -F "qr_code[foreground_color]=#0F172A" \
  -F "qr_code[background_color]=#FFFFFF" \
  -F "qr_code[logo]=@/path/to/logo.png"

Example Response (201 Created)

{
  "data": {
    "id": 2,
    "title": "My Website",
    "qr_type": "url",
    "short_url": "xk9m2pqr",
    "full_short_url": "https://qrdex.io/xk9m2pqr",
    "scans_count": 0,
    "track_scans": true,
    "foreground_color": "#000000",
    "background_color": "#FFFFFF",
    "shape": "rounded",
    "created_at": "2025-01-31T12:00:00Z",
    "updated_at": "2025-01-31T12:00:00Z",
    "image_url": "https://qrdex.io/api/v1/qr_codes/2/image",
    "svg_image_url": "https://qrdex.io/api/v1/qr_codes/2/image?format=svg",
    "png_image_url": "https://qrdex.io/api/v1/qr_codes/2/image?format=png"
  }
}

Try it

PATCH /api/v1/qr_codes/:id

Update an existing QR code. Only the fields you provide will be changed; all other fields remain unchanged.

Path Parameters

Parameter Type Required Description
id integer Yes The QR code ID

Body Parameters

Same parameters as the Create endpoint (nested inside qr_code), but all fields are optional. Only provided fields are updated.

Example Request

curl -X PATCH https://qrdex.io/api/v1/qr_codes/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": {
      "title": "Updated Title"
    }
  }'

Try it

DELETE /api/v1/qr_codes/:id

Soft-delete a QR code. The QR code will no longer be active or scannable, but the record is retained.

Path Parameters

Parameter Type Required Description
id integer Yes The QR code ID

Example Request

curl -X DELETE https://qrdex.io/api/v1/qr_codes/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": 1,
    "deleted": true
  }
}

Try it

Error Handling

The API uses standard HTTP status codes to indicate the outcome of a request. Errors return a JSON body with a descriptive message.

HTTP Status Codes

Code Meaning
200 OK -- Request succeeded.
201 Created -- A new resource was successfully created.
401 Unauthorized -- Invalid or missing API key.
403 Forbidden -- You do not have permission to access this resource.
404 Not Found -- The requested QR code does not exist.
422 Unprocessable Entity -- Validation error or plan limit reached.

Error Response Format

{
  "error": "Description of what went wrong."
}

Common Errors

401

Invalid API key

The provided API key is missing, malformed, or has been revoked. Double-check the key in your team settings.

404

QR code not found

The QR code ID does not exist, or it belongs to a different team.

422

Plan limit reached

Your team has reached the maximum number of QR codes for your current plan. Upgrade your plan to create more.

Rate Limiting

API requests are limited to 100 requests per minute per API key. If you exceed this limit, the API will return a 429 Too Many Requests response.

Check the following response header to monitor your remaining quota: 

X-RateLimit-Remaining: 95

If you need a higher rate limit for your use case, please contact us to discuss enterprise plans.

Ready to get started?

Create a free account to get your API key and start generating QR codes programmatically in minutes.

Sign Up and Get API Key