API

Erstelle und verwalte Kurzlinks aus Skripten und Apps. Die API ist kostenlos. Leg in deinem Dashboard unter API-Schlüssel einen Schlüssel an und sende ihn als Bearer-Token.

Authentifizierung

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel werden nur einmal angezeigt. Behandle sie wie Passwörter: Wer deinen Schlüssel hat, kann in deinem Konto Links anlegen und ändern. Einen abhandengekommenen Schlüssel kannst du im Dashboard widerrufen.

Grenzen

60 Anfragen pro Minute und Schlüssel.
500 neue Links pro Tag und Konto.
Ziele werden gegen Google Safe Browsing und unsere Sperrliste geprüft. Andere Link-Kürzer sind als Ziel nicht erlaubt.

Link anlegen

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code ist optional (4–32 Buchstaben, Ziffern, - oder _). Ohne Angabe gibt es einen zufälligen Code mit 7 Zeichen. Antwort 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

Links auflisten

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

Neueste zuerst. Übergib nextCursor von der vorherigen Seite, um die nächste zu bekommen. clicks=1 ergänzt die Zahl der menschlichen Klicks insgesamt.

Abrufen, ändern, löschen

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

Statistik

GET /api/my/links/{code}/stats

Liefert menschliche Klicks der letzten 90 Tage und insgesamt, Klicks pro Tag sowie die häufigsten Länder, Verweisquellen, Geräte, Browser und Betriebssysteme. Bots und Link-Vorschauen (Slack, WhatsApp und so weiter) werden getrennt in botClicks gezählt. Ergebnisse werden etwa 5 Minuten zwischengespeichert.

Fehler

Fehler nutzen HTTP-Statuscodes und einen JSON-Body:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

400 ungültige Eingabe (invalid_url, invalid_slug, …)
401 fehlender, ungültiger oder widerrufener Schlüssel
409 eigener Link bereits vergeben
422 Ziel nicht erlaubt (destination_blocked)
429 Rate- oder Tageslimit erreicht

Eine maschinenlesbare Beschreibung aller Endpunkte liegt unter /openapi.json.