RecodeQR API Documentation

This API allows programmatic management and generation of QR codes. Access is over HTTPS, with data in JSON format. Use https://recodeqr.com as the base for all endpoint examples.

API Endpoints Summary

Generate QR Codes

Description	Endpoint Details
Generate QR Code - Basic	`GET /api/generate`
Generate QR Code - Advanced	`POST /api/generate`

Manage QR Codes

Description	Endpoint Details
List QR Codes	`GET /api/qr-codes`
Create a New QR Code	`POST /api/qr-codes`
Retrieve a Specific QR Code	`GET /api/qr-codes/<code_id>`
Fully Update a QR Code	`PUT /api/qr-codes/<code_id>`
Partially Update a QR Code	`PATCH /api/qr-codes/<code_id>`
Delete a QR Code	`DELETE /api/qr-codes/<code_id>`
Download a QR Code Image	`GET /api/qr-codes/<code_id>.<format>`

Authentication

Authenticate by including your API Key in the Authorization header, prefixed with Bearer. For example:

Authorization: Bearer <YOUR_API_KEY_SECRET>

API keys are workspace-specific. Operations are automatically scoped to the key's associated workspace. You can manage your API keys under Workspace Settings > API in your RecodeQR dashboard.

Rate Limiting

All API responses will include the following headers to help you track your rate limit usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current time window.
`X-RateLimit-Remaining`	Requests remaining in the current time window.
`X-RateLimit-Reset`	Seconds until the rate limit resets.

Please monitor these headers to ensure your application stays within the defined limits. Specific endpoints may have their own distinct rate limits, detailed in their respective sections.

General Error Responses

Code	Meaning
`200`	OK
`201`	Created
`204`	No Content
`400`	Bad Request (client error, check `errors` object in response)
`401`	Unauthorized (invalid/missing API Key)
`402`	Payment Required (account/plan limits exceeded)
`403`	Forbidden (insufficient permissions/scopes for API Key)
`404`	Not Found (resource or endpoint missing)
`429`	Too Many Requests (rate limit exceeded)
`5xx`	Server Error

QR Code Management

Manage QR codes in your API key's workspace. These endpoints create and manage QR codes that are saved to your account.

QR Code Object

The standard QR code object structure returned by management endpoints:

{
  "code_id": "qr_abcdef123",
  "name": "Sample QR",
  "destination": "link",
  "dynamic": true,
  "data": {
    "url": "https://example.com/destination"
  },
  "styles": {
    "logo_url": null,
    "bg_color": "#FFFFFF",
    "fg_color": "#000000",
    "remove_logo_bg": false
  },
  "enabled": true,
  "total_scans": 0,
  "scan_limit": null,
  "not_before": null,
  "not_after": null
}

QR Code Data by Destination

When creating or updating a QR code, the data field in the request body depends on the chosen destination. Below are the expected parameters for each destination type.

Destination: `link`

Encodes a URL.

Parameter	Type	Required	Description
`url`	string	Yes	The URL to encode. Must start with `http://` or `https://`.

Destination: `text`

Encodes plain text.

Parameter	Type	Required	Description
`text`	string	Yes	The text to encode (max 1024 chars).

Destination: `email`

Creates a pre-filled email.

Parameter	Type	Required	Description
`address`	string	Yes	The recipient's email address.
`subject`	string	No	The email subject (max 255 chars).
`body`	string	No	The email body content (max 1000 chars).

Destination: `vcard`

Encodes a virtual contact card.

Parameter	Type	Required	Description
`first_name`	string	Yes	First name of the contact (max 255 chars).
`last_name`	string	No	Last name of the contact (max 255 chars).
`phone`	string	No	Phone number (e.g., `+1234567890`, max 20 chars).
`email`	string	No	Email address.
`org`	string	No	Organization/Company (max 255 chars).
`title`	string	No	Job title (max 255 chars).
`url`	string	No	Website URL.
`note`	string	No	Additional notes (max 255 chars).

Destination: `sms`

Creates a pre-filled SMS message.

Parameter	Type	Required	Description
`phone`	string	Yes	Recipient phone number (e.g., `+1234567890`, max 20 chars).
`message`	string	No	The SMS message content (max 255 chars).

Destination: `phone`

Encodes a phone number to initiate a call.

Parameter	Type	Required	Description
`phone`	string	Yes	Phone number to call (e.g., `+1234567890`, max 20 chars).

Destination: `wifi`

Encodes WiFi network credentials.

Parameter	Type	Required	Description
`ssid`	string	Yes	The name of the WiFi network (SSID, max 32 chars).
`encryption`	string	No	Network encryption type. Choices: `WPA`, `WEP`, `nopass` (default).
`password`	string	No	The WiFi network password (max 63 chars). Required if encryption is not `nopass`.
`hidden`	boolean	No	Whether the SSID is hidden (default: `false`).

Destination: `event`

Encodes an iCalendar event.

Parameter	Type	Required	Description
`title`	string	Yes	Event title (max 255 chars).
`date_start`	string	Yes	Event start date and time (ISO 8601 format, e.g., `YYYY-MM-DDTHH:MM:SS`).
`date_end`	string	Yes	Event end date and time (ISO 8601 format). Must be after `date_start`.
`location`	string	No	Event location (max 255 chars).
`description`	string	No	Event description (max 255 chars).
`timezone`	string	No	Timezone for the event (e.g., `America/New_York`, `Europe/London`). Default: `UTC`. Must be a valid IANA timezone.

Destination: `mecard`

Encodes a MeCard contact card (simpler format than vCard).

Parameter	Type	Required	Description
`first_name`	string	Yes	First name of the contact (max 255 chars).
`last_name`	string	No	Last name of the contact (max 255 chars).
`phone`	string	No	Phone number (e.g., `+1234567890`, max 20 chars).
`email`	string	No	Email address.
`url`	string	No	Website URL.
`note`	string	No	Additional notes (max 255 chars).

Destination: `crypto`

Encodes a cryptocurrency payment request.

Parameter	Type	Required	Description
`currency`	string	No	Cryptocurrency type. Choices: `bitcoin` (default), `ethereum`.
`address`	string	Yes	Recipient's cryptocurrency address (max 256 chars).
`amount`	decimal	No	Amount to send (e.g., `0.05`). Default: `0`.
`label`	string	No	A label for the address (max 64 chars).
`message`	string	No	A message for the transaction (max 64 chars).

Uploading Logos for QR Codes

When customizing your QR codes with a logo, you can provide the logo image in one of two ways within the styles object:

styles.logo_url: A publicly accessible URL to your logo image.
styles.logo: A base64 encoded string of your logo (as data URI).

For example:

"styles": {
  "logo_url": "https://example.com/my_logo.png",
  // OR: "logo": "data:image/png;base64,..."
}

The supported formats are .png, .jpg, .jpeg, .svg. Maximum file size: 1MB.

1. List QR Codes

GET https://recodeqr.com/api/qr-codes

Retrieves a paginated list of QR codes belonging to the workspace associated with the API key.

Query Parameters

Parameter	Description	Example
`page`	The page number for pagination (optional, default: 1).	`https://recodeqr.com/api/qr-codes?page=2`
`page_size`	The number of items per page (optional, default: 10).	`https://recodeqr.com/api/qr-codes?page_size=20`

Response Codes

Code	Description
`200 OK`	The request succeeded.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	Insufficient permissions/scopes.

Example Request

curl -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     "https://recodeqr.com/api/qr-codes?page=1&page_size=5"

Example Response

{
  "data": [
    {
      "code_id": "qr_12345",
      "name": "My Website Link",
      "destination": "link",
      "dynamic": true,
      "data": {"url": "https://mywebsite.com"},
      "styles": {"logo_url": null, "bg_color": "#FFFFFF", "fg_color": "#000000", "remove_logo_bg": false},
      "enabled": true,
      "total_scans": 150,
      "scan_limit": null,
      "not_before": null,
      "not_after": null
    },
    {
      "code_id": "qr_def456uvw",
      "name": "Contact Card",
      "destination": "mecard",
      "dynamic": false,
      "data": {"first_name": "John", "last_name": "Doe", "email": "[email protected]"},
      "styles": {"logo_url": "/media/logos/my_logo.png", "bg_color": "#EEEEEE", "fg_color": "#111111", "remove_logo_bg": true},
      "enabled": true,
      "total_scans": 25,
      "scan_limit": null,
      "not_before": null,
      "not_after": null
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 5,
  "page_count": 1
}

2. Create a New QR Code

POST https://recodeqr.com/api/qr-codes

Creates a new QR code in the API key's associated workspace.

Request Body (JSON)

Parameter	Type	Req.	Description
`name`	string	Yes	Name for the QR code.
`destination`	string	Yes	Type (eg., "link", "text", "mecard").
`dynamic`	boolean	No	Default: `true` if destination supports it.
`data`	object	Yes	Data specific to `destination` (eg., `{"url": "https://..."}`).
`styles`	object	No	Styling (eg., `{"logo_url": "...", "bg_color": "..."}`).
`scan_limit`	integer	No	Max scans (for dynamic codes).
`not_before`	string	No	Activation ISO datetime (for dynamic codes).
`not_after`	string	No	Deactivation ISO datetime (for dynamic codes).

Response Codes

Code	Description
`201 Created`	The QR code was successfully created.
`400 Bad Request`	Invalid input data.
`401 Unauthorized`	The API key is missing or invalid.
`402 Payment Required`	Plan limits exceeded.
`403 Forbidden`	Insufficient permissions/scopes.

Example Request

curl -X POST -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Product Launch", "destination": "link", "dynamic": true, "data": {"url": "https://recodeqr.com/new-product"}}' \
     "https://recodeqr.com/api/qr-codes"

Example Response

{
  "code_id": "qr_new789ghi",
  "name": "New Product Launch",
  "destination": "link",
  "dynamic": true,
  "data": {"url": "https://recodeqr.com/new-product"},
  "styles": {"logo_url": null, "bg_color": "#FFFFFF", "fg_color": "#000000", "remove_logo_bg": false},
  "enabled": true,
  "total_scans": 0,
  "scan_limit": null,
  "not_before": null,
  "not_after": null
}

3. Retrieve a Specific QR Code

GET https://recodeqr.com/api/qr-codes/<code_id>

Fetches details of a specific QR code by its ID.

Path Parameters

Parameter	Description
`code_id`	The ID of the QR code.

Response Codes

Code	Description
`200 OK`	The request succeeded.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	Insufficient permissions/scopes.
`404 Not Found`	The specified QR code does not exist.

Example Request

curl -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     "https://recodeqr.com/api/qr-codes/qr_12345"

Example Response

{
  "code_id": "qr_12345",
  "name": "My Website Link",
  "destination": "link",
  "dynamic": true,
  "data": {"url": "https://mywebsite.com"},
  "styles": {"logo_url": null, "bg_color": "#FFFFFF", "fg_color": "#000000", "remove_logo_bg": false},
  "enabled": true,
  "total_scans": 150,
  "scan_limit": null,
  "not_before": null,
  "not_after": null
}

4. Fully Update a QR Code

PUT https://recodeqr.com/api/qr-codes/<code_id>

Updates an existing QR code using a full replacement of writable fields.

Path Parameters

Parameter	Description
`code_id`	The ID of the QR code to update.

Request Body (JSON)
Provide all writable fields intended for update.

Response Codes

Code	Description
`200 OK`	The QR code was successfully updated.
`400 Bad Request`	Invalid input data or restricted field update.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	Insufficient permissions/scopes.
`404 Not Found`	The specified QR code does not exist.

Example Request

curl -X PUT -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     -H "Content-Type: application/json" \
     -d '{"name": "My Updated Website Link", "destination": "link", "data": {"url": "https://mywebsite.com/updated"}, "enabled": false}' \
     "https://recodeqr.com/api/qr-codes/qr_12345"

Example Response

{
  "code_id": "qr_12345",
  "name": "My Updated Website Link",
  "destination": "link",
  "dynamic": true,
  "data": {"url": "https://mywebsite.com/updated"},
  "styles": {"logo_url": null, "bg_color": "#FFFFFF", "fg_color": "#000000", "remove_logo_bg": false},
  "enabled": false,
  "total_scans": 150,
  "scan_limit": null,
  "not_before": null,
  "not_after": null
}

5. Partially Update a QR Code

PATCH https://recodeqr.com/api/qr-codes/<code_id>

Updates specific fields of an existing QR code.

Static (dynamic: false): Can update: name.
Dynamic (dynamic: true): Can update: name, data, destination, enabled, scan_limit, not_before, not_after.

Path Parameters

Parameter	Description
`code_id`	The ID of the QR code to update.

Request Body (JSON)
Include only the fields to be updated.

Response Codes

Code	Description
`200 OK`	The QR code was successfully updated.
`400 Bad Request`	Invalid input data or restricted field update.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	Insufficient permissions/scopes.
`404 Not Found`	The specified QR code does not exist.

Example Request

curl -X PATCH -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     -H "Content-Type: application/json" \
     -d '{"name": "Website Link (Paused)", "enabled": false}' \
     "https://recodeqr.com/api/qr-codes/qr_12345"

Example Response

{
  "code_id": "qr_12345",
  "name": "Website Link (Paused)",
  "destination": "link",
  "dynamic": true,
  "data": {"url": "https://mywebsite.com/updated"},
  "styles": {"logo_url": null, "bg_color": "#FFFFFF", "fg_color": "#000000", "remove_logo_bg": false},
  "enabled": false,
  "total_scans": 150,
  "scan_limit": null,
  "not_before": null,
  "not_after": null
}

6. Delete a QR Code

DELETE https://recodeqr.com/api/qr-codes/<code_id>

Permanently deletes a specific QR code.

Path Parameters

Parameter	Description
`code_id`	The ID of the QR code to delete.

Response Codes

Code	Description
`204 No Content`	The QR code was successfully deleted.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	Insufficient permissions/scopes.
`404 Not Found`	The specified QR code does not exist.

Example Request

curl -X DELETE -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     "https://recodeqr.com/api/qr-codes/qr_12345"

7. Download a QR Code Image

GET https://recodeqr.com/api/qr-codes/<code_id>.<format>

Downloads the image of a specific, existing QR code.

Path Parameters

Parameter	Description
`code_id`	The ID of the QR code.
`format`	Desired image format (`png`, `jpeg`, `svg`, `pdf`).

Response Codes

Code	Description
`200 OK`	The request succeeded, image is returned.
`401 Unauthorized`	The API key is missing or invalid.
`403 Forbidden`	Insufficient permissions/scopes.
`404 Not Found`	The specified QR code or format does not exist.

Example Request

curl -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     -o my_qr_code.png \
     "https://recodeqr.com/api/qr-codes/qr_12345.png"

QR Code Generation

On-the-fly QR image generation. These endpoints do not save the QR codes to your account. For persistent QR codes, use the QR Code Management (/api/qr-codes) endpoints.

This section offers two methods:

Basic (GET): For simple, quick QR codes with minimal styling.
Advanced (POST): For more control over styling, data types, and dynamic linking features.

1. Generate QR Code (Basic)

GET https://recodeqr.com/api/generate

Generates a simple QR code image. Authentication via API Key is optional but provides higher rate limits.

Query Parameters

Parameter	Type	Req.	Description (URL-encode values)
`data`	string	Yes	Content to encode (eg., URL). Must be URL-encoded.
`format`	string	No	Image format (default: `png`). Options: `png`, `jpeg`, `svg`.
`bg_color`	string	No	Hex background color (eg., `%23FFFFFF`).
`fg_color`	string	No	Hex foreground color (eg., `%23000000`).

Response Codes

Code	Description
`200 OK`	The request succeeded, image is returned.
`400 Bad Request`	Missing `data` parameter or invalid format.
`429 Too Many Requests`	Rate limit exceeded.

Example Request

curl "https://recodeqr.com/api/generate?data=https%3A%2F%2Fexample.com&format=png" \
     --output basic_qr.png

2. Generate QR Code (Full Customization)

POST https://recodeqr.com/api/generate

Generates a QR code image with advanced options. Authentication via API Key is optional but provides higher rate limits.

Request Body (JSON)

Parameter	Type	Req./Opt.	Description
`destination`	string	Req	QR type (eg., "link").
`format`	string	Req	Output: "png", "svg", "jpeg".
`data`	object	Req	eg., `{"url": "https://example.com"}`.
`styles`	object	Opt	Styling options.
`styles.logo_url`	string	Opt	External URL for logo.
`styles.logo`	string	Opt	Base64 data URI for logo.
`styles.bg_color`	string	Opt	Hex background color.
`styles.fg_color`	string	Opt	Hex foreground color.
`styles.remove_logo_bg`	boolean	Opt (default: `false`)	Attempt to remove logo background.

Response Codes

Code	Description
`200 OK`	The request succeeded, image is returned.
`400 Bad Request`	Invalid input data.
`429 Too Many Requests`	Rate limit exceeded.

Example Request (Unauthenticated)

curl -X POST -H "Content-Type: application/json" \
     -d '{"destination": "link", "format": "png", "data": {"url": "https://example.com/summer-promo"}, "styles": {"bg_color": "#EFEFEF", "fg_color": "#333333"}}' \
     "https://recodeqr.com/api/generate" --output advanced_qr.png

Example Request (Authenticated for higher rate limit)

curl -X POST -H "Authorization: Bearer <YOUR_API_KEY_SECRET>" \
     -H "Content-Type: application/json" \
     -d '{"destination": "link", "format": "svg", "data": {"url": "https://example.com/app-link"}, "styles": {"fg_color": "#007AFF"}}' \
     "https://recodeqr.com/api/generate" --output app_link_qr.svg

Rate Limiting for QR Code Generation Endpoints

These endpoints have their own rate limits, which are separate from the QR Code Management endpoints. The limits are:

Unauthenticated: 100 requests/minute/IP.
Authenticated (API Key): 1000 requests/minute/key.
Exceeding these limits results in a 429 Too Many Requests error.

Refer to the general rate limiting section for details on tracking these limits via response headers.

Have a question? Contact support - we're happy to help.

RecodeQR API Documentation

API Endpoints Summary

Generate QR Codes

Manage QR Codes

Authentication

Rate Limiting

General Error Responses

QR Code Management

QR Code Object

QR Code Data by Destination

Destination: link

Destination: text

Destination: email

Destination: vcard

Destination: sms

Destination: phone

Destination: wifi

Destination: event

Destination: mecard

Destination: crypto

Uploading Logos for QR Codes

1. List QR Codes

2. Create a New QR Code

3. Retrieve a Specific QR Code

4. Fully Update a QR Code

5. Partially Update a QR Code

6. Delete a QR Code

7. Download a QR Code Image

QR Code Generation

1. Generate QR Code (Basic)

2. Generate QR Code (Full Customization)

Rate Limiting for QR Code Generation Endpoints

Destination: `link`

Destination: `text`

Destination: `email`

Destination: `vcard`

Destination: `sms`

Destination: `phone`

Destination: `wifi`

Destination: `event`

Destination: `mecard`

Destination: `crypto`