API-Übersicht

Die qr3.app REST-API ist unter https://qr3.app/v1/ erreichbar.

Versionierung

Die API ist über den URL-Pfad versioniert (/v1/). Breaking Changes führen immer zu einer neuen Hauptversion.

Request-Format

Content-Type: application/json
Authentifizierung: Authorization: Bearer qr3_sk_xxx
Idempotenz: POST-Requests können mit Idempotency-Key: <uuid> idempotent gemacht werden

Response-Format

Alle erfolgreichen Responses geben JSON zurück:

{
  "id": "qr_abc123",
  "type": "url",
  "url": "https://example.com",
  "short_url": "https://qr3.app/r7f3Kx",
  "created_at": "2026-03-15T10:00:00.000Z"
}

Listen-Responses haben immer eine meta.pagination-Struktur:

{
  "data": [...],
  "meta": {
    "request_id": "req_xxx",
    "pagination": {
      "has_more": true,
      "next_cursor": "qr_abc",
      "total_count": 142
    }
  }
}

Fehlerformat (RFC 7807)

Alle Fehler folgen dem Standard RFC 7807 Problem Details:

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found",
  "instance": "/v1/codes/qr_xxx"
}

Status	Fehlertyp	Beschreibung
400	`bad-request`	Ungültiges JSON oder fehlende Pflichtfelder
401	`authentication`	Fehlender oder ungültiger API-Key
403	`forbidden`	Keine Berechtigung für diese Ressource
404	`not-found`	Ressource nicht gefunden
409	`conflict`	Idempotency-Key-Konflikt
422	`validation-error`	Eingabedaten fehlerhaft (mit `errors`-Array)
429	`rate-limited`	Rate-Limit überschritten
500	`internal`	Interner Serverfehler

Paginierung

Die API verwendet Cursor-basierte Paginierung:

# Erste Seite
GET /v1/codes?limit=20

# Nächste Seite
GET /v1/codes?limit=20&cursor=qr_lastid

Rate Limits

Jede Antwort enthält:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1742040120

Interaktive API-Referenz

Teste alle Endpoints direkt im Browser:

→ API-Referenz öffnen (Scalar, interaktiv, mit Try-it-out)