---
title: "List / filter codes"
method: GET
path: "/api/v1/codes"
tags: ["codes"]
---

# List / filter codes

`GET /api/v1/codes`

## Request

- Base URL: `https://app.qrtap.kg`
- URL: `https://app.qrtap.kg/api/v1/codes`
- Auth: HTTP bearer

Lists non-archived codes of your organization, newest first. Filter by `group` and/or `external_ref`. Add `include=stats` to get each code's all-time non-bot scan total in the same response — one call to sync all counters instead of N per-code `/stats` requests.

## Query parameters

- `group` string
- `external_ref` string
- `limit` integer
- `offset` integer
- `include` 'stats'

## Response `200`

Codes, newest first.

- object
  - `data` Code[], required
    - `id` string, uuid, required
    - `label` string, required
    - `target_url` string, nullable, required: Current destination URL.
    - `external_ref` string, nullable, required
    - `group` string, nullable, required
    - `state` string, required: Lifecycle state; API-created codes are `deployed`.
    - `design_template_id` string, uuid, nullable, required
    - `slug` string, required: Short-link slug. The QR encodes short_url = base + / + slug.
    - `short_url` string, uri, required: Stable printed link encoded in the QR. Never changes on retarget.
    - `png_url` string, uri, required: Artifact URL (PNG). Requires the same Bearer auth.
    - `svg_url` string, uri, required: Artifact URL (SVG). Requires the same Bearer auth.
    - `scans` integer: All-time non-bot scan count. Present only when listing with include=stats.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `401`: Missing, invalid or revoked API key.
- `429`: Limit exceeded — the request had no effect. `error` is `rate_limited` with `scope: "minute"` (a burst brake: wait `retry_after` seconds and continue) or `quota_exceeded` with `scope: "day"` (the workspace's daily quota, counted in UTC; it returns at `reset_at`, the next UTC midnight, and only a higher plan raises it before then).

---

[API](https://skmtc.dev/qrtap/apis/qrtap-rest-api.md) · [All operations](https://skmtc.dev/qrtap/apis/qrtap-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qrtap/apis/qrtap-rest-api/revisions/8af17ac525bd?raw)