Create QR code via REST API: Guide with curl examples

Step 1: Create key

In the dashboard under Account, section "Access for CLI, scripts and agents", you create a key. For initial tests, "read only" is sufficient. Choose a short duration, e.g., 30 days. The key starts with sqr_live_ and is displayed only once. Store it as an environment variable so it does not end up in your shell history, for example via your password manager.

Step 2: The first request

The API is located at https://sameqr.com/api/v1. The key belongs in the Authorization header, never in the URL:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/konto
curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

The first request shows your account, your plan, and your limits; the second shows your QR codes with ID, name, target, labels, scan count, and the _rev status.

Step 3: Create a QR code

To create, you need a second key with 'read + write'. With a read-only key, the API responds to modifying requests with 403 and the code NUR_LESEN. A new QR code requires at least a name and a target:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Scan the new QR code with your mobile device before proceeding. To create a QR code, your email address must be confirmed, and the QR code counts against the quota of your plan.

Step 4: Change the target

Target changes are particularly protected. You need a 'full' key and send the current state of the QR code as the X-Confirm header. The read request provides the state:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr/<id>

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

Only the included fields are changed. If the state differs because someone has changed the QR code in the meantime, nothing is overwritten. Via the API, there are a maximum of 10 target changes per hour and 30 per day; in the dashboard, there is no such limit. In the free plan, the number of target changes per QR code is limited.

Step 5: Understand errors and limits

Errors always return in the same format: an error object with status, QR code, and message. Evaluate them in your program instead of simply continuing.

• 401: Key is missing, incorrect, expired, or revoked.
• 403: The key lacks the necessary level, or your plan does not allow the action.
• 400 with BESTAETIGUNG_FEHLT: For target changes, offline, or deletion, X-Confirm with the current state is missing.
• 409: Someone changed the QR code in the meantime.
• 429: Too many enquiries. 120 per minute per key, 60 per hour in the Free plan, 300 in Start, 1,000 in Pro, and 5,000 in Agentur.

All enquiries are described in /api/v1/openapi.json; the documentation is available at sameqr.com/entwickler.

Conclusion: why Same-QR

The Same-QR REST API is clean, well-documented, and included in every plan. It can do everything the dashboard can, protects printed QR codes with confirmation and limits against accidental target changes, allows keys in three levels, and responds with understandable errors.

Get started right away: sign up for free at sameqr.com, 20 dynamic QR codes are free forever. API, CLI and MCP server are included in every plan, and the documentation is at sameqr.com/entwickler.

Frequently asked questions