REST-API · v1

klick.tools aus deinem System ansprechen.

Eine Schnittstelle für die ganze Plattform — zur automatischen Erstellung und Verwaltung von QR-Codes und Kurzlinks.

Grundlagen

Basis-URL, Anmeldung, Antwortformat

Basis-URL
https://klick.tools/api/v1

Alle Endpunkte liegen unter dieser Adresse. Es gibt keinen separaten API-Host.

Anmeldung

Entweder per API-Schlüssel im Header Authorization: Bearer kt_live_… (alternativ x-api-key) oder — im Browser — über die bestehende Anmeldung. Ohne beides antwortet die API mit 401.

Antworten

Immer JSON: Listen als { data, count }, Schreibvorgänge als { message, data }, Fehler als { error } mit passendem Statuscode. Die Links-Endpunkte liefern zusätzlich ein stabiles code-Feld, das sich maschinell auswerten lässt.

Referenz

Endpunkte · QR-Codes

MethodePfadZweckZugang
GET/api/v1/qrAlle gespeicherten QR-Codes des Kontos, inklusive Anzahl der Scans.API-Schlüssel oder Session
POST/api/v1/qrNeuen QR-Code speichern. Antwortet mit 201 und dem angelegten Datensatz.API-Schlüssel oder Session
GET/api/v1/qr/{id}Einzelnen Code samt der 20 jüngsten Scans.API-Schlüssel oder Session
PATCH/api/v1/qr/{id}Titel, Inhalt oder Design eines Codes ändern.API-Schlüssel oder Session
DELETE/api/v1/qr/{id}Code löschen.API-Schlüssel oder Session
GET/api/v1/keysEigene API-Schlüssel auflisten.Nur angemeldet im Browser
POST/api/v1/keysNeuen API-Schlüssel erzeugen. Der Schlüssel beginnt mit kt_live_.Nur angemeldet im Browser
Referenz

Endpunkte · Kurzlinks

MethodePfadZweckZugang
POST/api/v1/linksKurzlink anlegen. Ohne Anmeldung möglich und dann rate-limitiert; customAlias erfordert PRO. Antwortet mit 201.Optional — anonym, API-Schlüssel oder Session
GET/api/v1/linksDie eigenen Kurzlinks, neueste zuerst, höchstens 200 — inklusive Klickzahl.API-Schlüssel oder Session
PATCH/api/v1/links/{id}title und isActive für alle; targetUrl und code nur mit PRO. Beim Ändern des Codes bleibt der alte dauerhaft gesperrt.API-Schlüssel oder Session
DELETE/api/v1/links/{id}Soft Delete: Der Kurzlink antwortet ab sofort mit 410, der Kurzcode wird nie neu vergeben.API-Schlüssel oder Session
GET/api/v1/links/{id}/statsFree: Gesamtklicks. Pro: 30-Tage-Verlauf, verschiedene Besucher, Herkunft, Geräte, Browser, Länder.API-Schlüssel oder Session
Referenz

Felder beim Anlegen eines QR-Codes

NameTypBeschreibung
titlePflichtstringName des Codes in deiner Verwaltung.
typePflichtstringInhaltstyp: url, text, wifi, vcard, email, phone oder geo.
payloadPflichtstringDer Inhalt, der im Code steckt — etwa die Ziel-URL oder ein fertiges WIFI:/vCard-Payload.
designConfigobjectFarben, Modulform und Rahmen als JSON-Objekt. Wird mitgespeichert und beim Rendern im Generator wieder verwendet.
isDynamicbooleantrue legt zusätzlich einen Kurzcode an, über den die Weiterleitung läuft — das Ziel bleibt damit später änderbar.
Referenz

Felder beim Anlegen eines Kurzlinks

NameTypBeschreibung
targetUrlPflichtstringDie Ziel-Adresse. Nur http:// und https://, höchstens 2.048 Zeichen. Interne und private Adressen, eingebettete Zugangsdaten und Kurzlinks dieser Seite werden abgelehnt.
titlestringFreier Name, höchstens 160 Zeichen. Nur in der eigenen Verwaltung sichtbar.
customAliasstringWunsch-Kurzcode: 3 bis 32 Zeichen aus Buchstaben, Ziffern, Bindestrich und Unterstrich. Erfordert PRO; reservierte Wörter wie admin oder api werden abgelehnt.
Beispiele

Ein Aufruf, ein Datensatz

cURL
curl -X POST https://klick.tools/api/v1/qr \
  -H "Authorization: Bearer $KLICK_TOOLS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Aktion Frühling",
    "type": "url",
    "payload": "https://example.de/aktion",
    "isDynamic": true
  }'
JavaScript
const res = await fetch("https://klick.tools/api/v1/qr", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KLICK_TOOLS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Aktion Frühling",
    type: "url",
    payload: "https://example.de/aktion",
  }),
});

const { data } = await res.json();
Beispiele

Kurzlink anlegen

cURL
curl -X POST https://klick.tools/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{ "targetUrl": "https://example.de/eine/sehr/lange/adresse" }'
Antwort
{
  "message": "Kurzlink erstellt.",
  "data": {
    "id": "clx7f2k9a0000xyz",
    "code": "Ab3xY7z",
    "shortUrl": "https://klick.tools/s/Ab3xY7z",
    "targetUrl": "https://example.de/eine/sehr/lange/adresse",
    "title": null,
    "isActive": true,
    "isCustomAlias": false,
    "clickCount": 0,
    "lastClickAt": null,
    "createdAt": "2026-08-15T09:12:44.031Z",
    "updatedAt": "2026-08-15T09:12:44.031Z",
    "claimToken": "…"
  }
}

claimToken wird ausschließlich beim anonymen Anlegen zurückgegeben und nur dieses eine Mal. Ein Endpunkt zum Einlösen ist in Vorbereitung — bis dahin ist der Wert ohne Funktion.

Referenz

Fehlercodes

codeStatusBedeutung
INVALID_JSON400Der Anfrage-Körper ist kein gültiges JSON-Objekt.
INVALID_URL400Die Ziel-Adresse hat die Prüfung nicht bestanden.
BLOCKED_TARGET400Die Ziel-Domain steht auf der Sperrliste.
INVALID_TITLE400Titel ist kein Text oder länger als 160 Zeichen.
INVALID_ALIAS400Alias verletzt die Zeichen- oder Längenregel oder ist reserviert.
SPAM_DETECTED400Das versteckte Formularfeld war ausgefüllt.
UNAUTHORIZED401Keine gültige Session und kein gültiger API-Schlüssel.
FORBIDDEN_ORIGIN403Der Origin-Header passt nicht zum Host (CSRF-Schutz).
PRO_REQUIRED403Die Funktion gehört zu klick.tools PRO.
LINK_LIMIT_REACHED403Das Kontingent des kostenlosen Tarifs ist ausgeschöpft.
NOT_FOUND404Kein solcher Kurzlink — oder er gehört einem anderen Konto.
ALIAS_TAKEN409Der Wunsch-Alias ist bereits vergeben.
CODE_TAKEN409Der neue Kurzcode ist bereits vergeben.
RATE_LIMITED429Zu viele Anfragen. Die Antwort trägt einen Retry-After-Header in Sekunden.
QUOTA_EXCEEDED429Das monatliche API-Kontingent des Schlüssels ist ausgeschöpft. Retry-After nennt die Sekunden bis zum Monatswechsel.
SERVER_ERROR500Unerwarteter Fehler auf unserer Seite.
SHORT_CODE_EXHAUSTED503Es konnte kein freier Kurzcode erzeugt werden. Wiederholen.
Fahrplan

In Vorbereitung

Geplant
Anonyme Kurzlinks übernehmen

Beim anonymen Anlegen entsteht ein claimToken. Ein Endpunkt, der ihn gegen die Übernahme in ein Konto eintauscht, folgt — dokumentiert wird er erst, wenn er antwortet.

Geplant
Render-Endpunkt

Ein Aufruf, der die fertige Datei als PNG, SVG oder PDF zurückgibt, statt nur den Datensatz zu speichern. Bis dahin entsteht die Datei im Generator — mit denselben Design-Optionen.

Grenzen

Kontingente pro Tarif

Free
10 API-Anfragen / Monat
Pro
100 API-Anfragen / Monat
Max
10.000 API-Anfragen / Monat

Kurzlinks

Ohne Konto

30 Kurzlinks pro Tag, höchstens 5 in zehn Minuten und 20 pro Stunde.

Free-Konto

25 gleichzeitig bestehende Kurzlinks. Gelöschte zählen nicht mit.

Pro

Keine Obergrenze, zusätzlich Wunsch-Alias und änderbares Ziel.

Schlüssel holen und loslegen

API-Schlüssel gehören zu einem kostenlosen Konto. Die Registrierung dauert unter einer Minute.

Kostenloses Konto anlegen