Skip to main content

Quickstart — Your First QR via API

This guide walks you end-to-end through creating your first dynamic QR code with the QRForge Public API v1.

You will:

  1. Authenticate using an API key.
  2. (Optionally) create a dedicated Project.
  3. Create a QR code pointing to your URL.
  4. Fetch the QR by ID and by slug.

Base URL (Production)
https://api.qrforge.link

All examples below use curl, but the same pattern applies to any HTTP client.

1. Prerequisites​

Before calling the API, ensure you have:

  • A QRForge account with API access enabled.
  • At least one live API key, visible in the QRForge dashboard.

Authentication is performed via an HTTP header:

x-api-key: api_live_********************************

See: Authentication and API Keys.

2. (Optional) Create a Project​

If you do nothing, QRForge will use your default project. However, most integrations benefit from a dedicated project for API-created QRs.

Request​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: api_live_YOUR_KEY_HERE" \
  "https://api.qrforge.link/v1/projects" \
  -d '{
    "name": "API Project Alpha",
    "description": "Project created via public API for testing."
  }'

Successful response (example)​

{
  "ok": true,
  "version": "2025-11-14-v1",
  "request_id": "700f700f-c01f-4986-8010-ecb15d520b68",
  "project_id": "0nCicGb1mZfPukKp2Fcl",
  "name": "API Project Alpha",
  "description": "Project created via public API for testing.",
  "is_default": false,
  "has_custom_domain": false,
  "created_via": "api",
  "created_at": "2025-11-19T14:18:55.245Z",
  "updated_at": "2025-11-19T14:18:55.245Z"
}

You will reuse the project_id (0nCicGb1mZfPukKp2Fcl in this example) when creating QR codes.

See: Projects.

3. Create a QR Code​

Now create a dynamic URL QR code pointing to your destination URL.

If you want to target your default project, you can omit project_id.

Request (using an explicit project)​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: api_live_YOUR_KEY_HERE" \
  "https://api.qrforge.link/v1/qr-codes" \
  -d '{
    "project_id": "0nCicGb1mZfPukKp2Fcl",
    "redirect_url": "https://example.com/api-happy",
    "type": "url",
    "label": "API happy path"
  }'

Successful response (example)​

{
  "ok": true,
  "version": "2025-11-14-v1",
  "request_id": "6fc89a23-8656-46d1-82bd-04f6d4a2097e",
  "qr_id": "wUF83EsmkvjkgdsRSCAE",
  "project_id": "0nCicGb1mZfPukKp2Fcl",
  "slug": null,
  "type": "url",
  "label": "API happy path",
  "status": "active",
  "render_status": "pending",
  "destination_url": null,
  "redirect_url": "https://example.com/api-happy",
  "file_url_svg": null,
  "file_url_png": null,
  "analytics_enabled": true,
  "created_at": "2025-11-19T12:36:32.654Z",
  "updated_at": "2025-11-19T12:36:32.654Z",
  "last_rendered_at": null,
  "render_requested_at": "2025-11-19T12:36:32.654Z",
  "render_attempt": 1,
  "render_error": null
}

Immediately after creation, the QR may still be rendering (render_status: "pending"). A short time later, the QRForge renderer updates the document with:

  • render_status: "done"
  • slug: "qr-xxxxxxx"
  • file_url_svg / file_url_png

See: QR Codes.

4. Retrieve the QR by ID​

Once created, you can fetch the full QR document by its qr_id.

Request​

curl -X GET \
  -H "x-api-key: api_live_YOUR_KEY_HERE" \
  "https://api.qrforge.link/v1/qr-codes/wUF83EsmkvjkgdsRSCAE"

Example response​

{
  "ok": true,
  "version": "2025-11-14-v1",
  "request_id": "3ddfb20b-5ffa-4dc9-9edf-7a6bed2098f0",
  "qr_id": "wUF83EsmkvjkgdsRSCAE",
  "project_id": "0nCicGb1mZfPukKp2Fcl",
  "slug": "qr-1ap99pp",
  "type": "url",
  "label": "API happy path",
  "status": "active",
  "render_status": "done",
  "destination_url": "https://example.com/api-happy",
  "redirect_url": "https://example.com/api-happy",
  "file_url_svg": "https://...svg",
  "file_url_png": "https://...png",
  "created_at": "2025-11-19T12:36:32.654Z",
  "updated_at": "2025-11-19T12:36:36.092Z",
  "last_rendered_at": "2025-11-19T12:36:47.697Z",
  "render_requested_at": "2025-11-19T12:36:36.092Z",
  "render_attempt": 1,
  "render_error": null,
  "qr_data": {
    "url": "https://example.com/api-happy"
  },
  "qr_render_metadata": {
    "format_ratio": "1",
    "width": 300,
    "height": 300,
    "unit": "px",
    "padding": 0,
    "quiet_zone": 4,
    "border_style": "square",
    "dot_style": "",
    "eye_style": "",
    "foreground_color": "#000000",
    "background_color": "#FFFFFF",
    "bg_transparent": false,
    "error_correction": "M",
    "dpi": 300,
    "export_png": true,
    "output_alignment": "center"
  },
  "analytics_enabled": true
}

5. Retrieve the QR by slug​

For many integrations, it is more convenient to work with the public slug.

Request​

curl -X GET \
  -H "x-api-key: api_live_YOUR_KEY_HERE" \
  "https://api.qrforge.link/v1/qr-codes/find?slug=qr-1ap99pp"

The response body matches the GET /v1/qr-codes/{id} response format.

6. Update the QR (optional)​

You can update the label, redirect URL, or status using PATCH /v1/qr-codes/{id}.

Example — update label and redirect URL​

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "x-api-key: api_live_YOUR_KEY_HERE" \
  "https://api.qrforge.link/v1/qr-codes/wUF83EsmkvjkgdsRSCAE" \
  -d '{
    "label": "API updated label",
    "redirect_url": "https://example.com/api-updated"
  }'

If redirect_url changes, QRForge will automatically schedule a re-render in the background.

7. Handling Errors & Rate Limits​

All errors use a consistent envelope:

{
  "ok": false,
  "version": "2025-11-14-v1",
  "request_id": "5e7c1cfa-e2c2-4b4f-b2b4-8aa25531c9ef",
  "code": "invalid_request",
  "message": "Missing required field: redirect_url"
}

Key scenarios to handle:

  • unauthorized — missing or invalid x-api-key.
  • project_not_found — invalid or inaccessible project_id.
  • rate_limit_minute / rate_limit_day — API quotas exceeded.
  • invalid_payload / invalid_request — malformed or disallowed payload.

See:

8. Next Steps​

Once you have your first QR working end-to-end:

  • Wire these calls into your backend service.
  • Use projects to separate environments (e.g., Marketing, POS, Experiments).
  • Monitor quotas and observability via the QRForge dashboard.

For the full schema and all supported parameters, refer to the OpenAPI spec:

https://developer.qrforge.link/openapi/qrforge-v1.yaml

This is the single source of truth for QRForge API v1.