> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Manage QR codes, templates, analytics and reports from your own code.

> [!NOTE]
>
> The GetQR API is in beta and is available to selected workspaces. Details may change before the general release.

The GetQR API is a REST API for what you do in the dashboard: create and update QR codes, download their images, read scan analytics and export reports. Authenticate with your account API key and call versioned endpoints under `/api/v1`.

## What you can do

> [card] [QR codes](https://docs.getqr.com/api/endpoints/qr-codes.md)
>
> Create, list, update, pause, duplicate, delete and download QR codes.

> [card] [Analytics](https://docs.getqr.com/api/endpoints/analytics.md)
>
> Scan totals and breakdowns for one QR code or the whole workspace.

> [card] [Reports](https://docs.getqr.com/api/endpoints/reports.md)
>
> Export a one-off report or schedule recurring report emails.

> [card] [Templates](https://docs.getqr.com/api/endpoints/templates.md)
>
> Save designs and apply them to new QR codes.

> [card] [Bulk QR creations](https://docs.getqr.com/api/endpoints/bulk-qr-creations.md)
>
> Create up to 100 QR codes at once from JSON or a CSV file.

> [card] [Files](https://docs.getqr.com/api/endpoints/files.md)
>
> Upload PDFs, images, videos and logos for your QR codes.

> [card] [Health](https://docs.getqr.com/api/endpoints/health.md)
>
> Check that the API is up. No API key needed.

## Guides

> [card] [QR types](https://docs.getqr.com/api/guides/qr-types.md)
>
> The data format for each of the 16 QR types.

> [card] [Customization](https://docs.getqr.com/api/guides/customization.md)
>
> Dot styles, corners, colors, frames and logos.

> [card] [Access rules](https://docs.getqr.com/api/guides/access-rules.md)
>
> Schedules, scan limits, passwords, pausing and deleting.

## Base URL

All endpoints live under one base URL:

```text theme={null}
https://getqr.com/api/v1
```

## Versioning

The API version is part of the path: every endpoint lives under `/api/v1/`.

* Breaking changes ship under a new version prefix such as `/api/v2/`, and `/api/v1/` keeps working.
* Additive changes, such as new optional fields or new endpoints, can appear within v1. Ignore response fields your code doesn't recognize.

## Quickstart

**1. Get your API key**

Generate or reveal your key in your account settings. See [Authentication](https://docs.getqr.com/api/authentication.md).

**2. Check that the API is reachable**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

The response is `{ "status": "ok", "version": "v1" }`.

**3. Create your first QR code**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

The API answers `201` with the new QR code, including its `id` and `shortLink`.

**4. Download the image**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Requests and responses

* **Format.** Send request bodies as JSON with `Content-Type: application/json`. The exception is the CSV upload for [bulk creation](https://docs.getqr.com/api/endpoints/bulk-qr-creations.md), which uses `multipart/form-data`.
* **Responses.** Responses are JSON. Downloads, such as QR images and bulk ZIP archives, return the file itself.
* **Dates.** Dates are ISO 8601 strings in UTC, for example `2026-08-01T10:00:00.000Z`.
* **Query parameters.** Boolean parameters take the strings `true` or `false`.
* **Partial updates.** `PATCH` endpoints change only the fields you send.
* **Secrets.** Responses never include passwords or internal identifiers. A password-protected QR code only reports `passwordProtected: true`.
* **Workspace.** Every request runs in the workspace your API key belongs to. You don't pass a workspace ID. See [Access and roles](https://docs.getqr.com/api/authentication.md#access-and-roles).
* **Errors.** Failed requests return an `error` object with a stable `code`. See [Errors](https://docs.getqr.com/api/errors.md).

## Pagination

List endpoints (QR codes, templates and scheduled reports) take two query parameters:

| Parameter | Description |
| - | - |
| `page` | Page to return. Defaults to `1`. |
| `pageSize` | Results per page, up to `100`. Defaults to `100`. |

They answer with a `data` array and a `pagination` object:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Field | Description |
| - | - |
| `page` | The page you received. |
| `pageSize` | The page size you received. |
| `total` | Number of results across all pages. |
| `hasMore` | `true` while another page is waiting. |

Request the next page while `hasMore` is `true`. A `pageSize` over `100` returns [`422`](https://docs.getqr.com/api/errors#validation-errors).

## Idempotency

A network error can leave you unsure whether a request went through. To retry [Create a QR code](https://docs.getqr.com/api/endpoints/qr-codes.md#create-a-qr-code) safely, send an `Idempotency-Key` header with a unique value of your choice:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* Repeating the request with the same key within 24 hours returns the original response instead of creating a second QR code.
* The `x-idempotent-replay` response header is `true` for a replayed response and `false` for a new one.
* If the first request with that key is still running, the API answers `409 conflict`. Retry once it finishes.
* Reusing a key with a different request body answers `422 unprocessable_entity`.
* Without the header, an identical request body sent within 30 seconds is treated as a duplicate.

Bulk creations take an `idempotencyKey` field in the request body instead. See [Bulk QR creations](https://docs.getqr.com/api/endpoints/bulk-qr-creations.md).

## Rate limits

Each API key can send up to 600 requests per minute. See [Rate limits](https://docs.getqr.com/api/rate-limits.md).

## Coming later

Print-ready packs are planned for a later release.

## What's next

> [card] [Authentication](https://docs.getqr.com/api/authentication.md)

> [card] [QR codes](https://docs.getqr.com/api/endpoints/qr-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.