REST API · v1

API-Dokumentation

Alle Endpunkte, alle Parameter, alle Antwortformate. Kein SDK notwendig.

Einstieg

Die kürze.at REST-API ermöglicht das programmatische Erstellen und Verwalten von Kurzlinks und QR-Codes. Sie ist verfügbar ab dem Pro-Tarif.

  1. Melden Sie sich an und navigieren Sie zu Dashboard → Einstellungen → API-Schlüssel
  2. Erstellen Sie einen neuen API-Schlüssel mit den gewünschten Berechtigungen
  3. Senden Sie den Schlüssel als Bearer-Token im Authorization-Header

Authentifizierung

Alle Requests müssen einen gültigen Bearer-Token im Header enthalten:

Authorization: Bearer kuerze_YOUR_API_TOKEN
Sicherheitshinweis: Speichern Sie API-Schlüssel niemals im Frontend-Code oder in öffentlichen Repositories. Verwenden Sie Umgebungsvariablen.

Basis-URL

https://kuerze.at/api/v1

Alle Endpunkte sind relativ zu dieser Basis-URL. HTTPS wird erzwungen.

Rate Limiting

Tarif Limit Header
Pro 10.000 Requests/Tag X-RateLimit-Remaining
Agentur Unbegrenzt –

Bei Überschreitung wird HTTP 429 Too Many Requests zurückgegeben. Der Header Retry-After gibt an, wann das Limit zurückgesetzt wird.

Fehlerformate

Alle Fehler werden als JSON zurückgegeben:

{
  "message": "The destination_url field is required.",
  "errors": {
    "destination_url": ["The destination_url field is required."]
  }
}

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Validation Error

429

Rate Limit

500

Server Error

204

No Content

QR-Codes

QR-Codes erstellen und verwalten.

GET /api/v1/qr-codes QR-Codes auflisten

Gibt eine paginierte Liste aller QR-Codes des Teams zurück.

Parameter

Name Typ Pflicht Beschreibung
search string nein Suche im Namen
type string nein Filter nach QR-Typ (url, wifi, vcard, …)
per_page integer nein Einträge pro Seite (Standard: 25)

Antwort 200 

{"data": [{
  "id": 7,
  "ulid": "01HN...",
  "name": "Mängelmelder QR",
  "type": "url",
  "content": {"url": "https://buergerservice.example.at/meldung"},
  "output_format": "svg",
  "scan_count": 892,
  "created_at": "2026-01-20T09:00:00Z"
}], "meta": {"total": 12}}
POST /api/v1/qr-codes QR-Code erstellen

Erstellt einen neuen QR-Code. Der Code wird asynchron generiert.

Parameter

Name Typ Pflicht Beschreibung
name string ja Interner Name
type string ja url | wifi | vcard | email | phone | sms | location | event | epc_girocode
content object ja Inhalt abhängig vom Typ (siehe unten)
output_format string nein svg (Standard) | png
error_correction string nein L | M (Standard) | Q | H
size integer nein Pixel (100–2000, Standard: 400)
design object nein {foreground_color, background_color}
project_id integer nein Projekt-ID

Request Body

{
  "name": "Mängelmelder QR",
  "type": "url",
  "content": {
    "url": "https://buergerservice.example.at/meldung"
  },
  "output_format": "svg",
  "error_correction": "H",
  "design": {
    "foreground_color": "#0A0908",
    "background_color": "#FFFFFF"
  }
}

Antwort 201 

{
  "id": 7,
  "ulid": "01HN...",
  "name": "Mängelmelder QR",
  "type": "url",
  "content": {"url": "https://buergerservice.example.at/meldung"},
  "output_format": "svg",
  "scan_count": 892,
  "created_at": "2026-01-20T09:00:00Z"
}

Content-Objekte nach QR-Typ

url {"url": "https://..."}
wifi {"ssid": "Netzwerkname", "password": "...", "security": "WPA"}
vcard {"first_name": "Maria", "last_name": "Huber", "email": "...", "phone": "..."}
email {"to": "...", "subject": "...", "body": "..."}
phone {"phone": "+43..."}
sms {"phone": "+43...", "message": "..."}
location {"lat": 48.2083, "lng": 16.3731, "label": "Wien"}
GET /api/v1/qr-codes/{id} QR-Code abrufen

Gibt einen einzelnen QR-Code zurück.

Antwort 200 

{
  "id": 7,
  "ulid": "01HN...",
  "name": "Mängelmelder QR",
  "type": "url",
  "content": {"url": "https://buergerservice.example.at/meldung"},
  "output_format": "svg",
  "scan_count": 892,
  "created_at": "2026-01-20T09:00:00Z"
}
DELETE /api/v1/qr-codes/{id} QR-Code löschen

Löscht einen QR-Code endgültig.

Antwort 204

Kein Body

Analytics

Anonymisierte Klick-Statistiken abrufen.

GET /api/v1/analytics/overview Übersicht

Gesamt-Statistiken des Teams für einen Zeitraum.

Parameter

Name Typ Pflicht Beschreibung
days integer nein Zeitraum in Tagen (Standard: 30, Max: 365)

Antwort 200 

{
  "total_clicks": 8471,
  "unique_clicks": 6203,
  "bot_clicks": 142,
  "total_scans": 2103,
  "period_days": 30
}
GET /api/v1/analytics/links/{id} Link-Statistiken

Detaillierte Statistiken für einen einzelnen Link.

Parameter

Name Typ Pflicht Beschreibung
days integer nein Zeitraum in Tagen (Standard: 30)

Antwort 200 

{
  "clicks": 1247,
  "unique_clicks": 891,
  "chart": [
    {"date": "2026-04-01", "clicks": 42, "unique": 31},
    ...
  ],
  "countries": {"AT": 847, "DE": 312, "CH": 88},
  "devices": {"mobile": 712, "desktop": 401, "tablet": 134}
}