Link-API

Die API legt anonyme Kurzlinks an, liefert ihre Klickstatistik, ändert ihre Einstellungen und löscht sie. Anfragen und Antworten verwenden JSON. CORS ist aktiviert, Aufrufe funktionieren daher auch aus Browser-Code.

Basisadresse:

http://anonym.es/api/v1

Schnellstart

Um einen Kurzlink anzulegen, senden Sie die Zieladresse:

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Mit einem Kontotoken legt derselbe Aufruf den Link in Ihrem Dashboard ab und zählt ihn auf Ihren Tarif:

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Die Antwort enthält die Kurzadresse, die Link-ID und das Token, das diesen Link verwaltet. Bewahren Sie das Token auf: Es wird gebraucht, um den Link später zu lesen oder zu löschen.

{
  "ok": true,
  "link": {
    "id": 4821,
    "short": "http://anonym.es/k7m2q",
    "url": "https://example.com/article",
    "status": "active",
    "password": false,
    "created_at": "2026-09-05T14:02:11Z",
    "expires_at": null,
    "max_hits": null,
    "self_destruct": false,
    "delay": null,
    "no_countdown": false,
    "adult": false,
    "note": null,
    "tags": [],
    "clicks": 0,
    "uniques": 0
  },
  "token": "3f9c1b7e2d4a4c0e9b8f7a6d5c4b3a21",
  "left": 4
}

Felder des Link-Objekts

Alle Endpunkte, die einen Link zurückgeben, verwenden diese Struktur. Zeitstempel sind ISO 8601 in UTC. Die Zähler clicks und uniques umfassen die gesamte Lebensdauer des Links.

Autorisierung

Autorisierte Anfragen tragen das Token im Authorization-Header. Alternativ wird der Header X-API-Key akzeptiert. Tokens werden nie im Query-String übergeben.

Authorization: Bearer YOUR_TOKEN

Ein Kontotoken beginnt mit anon_. Ein Link-Token besteht aus 32 Zeichen. Ein neu erzeugtes Kontotoken macht das vorherige ungültig.

Beispiel:

curl http://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Kontotoken im Konto erzeugen

Endpunkte

Der Request-Body kann als application/json oder als application/x-www-form-urlencoded gesendet werden. Parameternamen und Fehlercodes sind bei allen Endpunkten identisch.

Die Kosten sind in Einheiten des Ratenlimits angegeben, siehe Ratenlimits.

Einen Link anlegen

POST /api/v1/links

Die minimale Anfrage enthält nur das Feld url:

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Mit einem Kontotoken gehört der Link zum Konto und zählt auf dessen Tarif. Ohne Token ist er ein Gastlink auf die IP-Quote:

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

Eine erfolgreiche Anfrage liefert Status 201 mit dem Link, seinem Token und der Anzahl der im aktuellen Quotenzeitraum verbleibenden Links.

Felder der Antwort:

Link mit eigenem Namen

Die Kurzadresse erhält den Namen my-article, wenn er frei ist und den Regeln unten entspricht.

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","name":"my-article"}'

Namensregeln:

• Lateinische Buchstaben, Ziffern, Bindestrich und Unterstrich. Ab 5 Zeichen im Free-Tarif und ab 3 in bezahlten Tarifen, höchstens 32. Groß- und Kleinschreibung spielt keine Rolle: Promo und promo sind derselbe Link.
• Seitennamen, Sprachcodes und Dienstwörter sind reserviert.
• Markennamen und anstößige Wörter werden abgelehnt. Namen durchlaufen eine Wortliste und eine automatische Prüfung. Die Zahl eigener Namen pro Stunde ist je Tarif begrenzt.
• Ein vergebener Name liefert Status 409 mit freien Alternativen in suggest.
• Ein Subdomain-Name (sub: true, Tarif Max) ist ein DNS-Label: Buchstaben, Ziffern und Bindestriche, kein Bindestrich am Rand, kein Unterstrich. Namen wie www, mail oder ns1 sind reserviert.

Ein Name lässt sich vor dem Anlegen prüfen:

curl "http://anonym.es/api/v1/names/check?name=my-article"

Felder der Prüfantwort:

Mehrere Links auf einmal

Das Feld urls nimmt bis zu 50 Adressen an, als JSON-Array oder als Text mit einer Adresse pro Zeile. Jede Adresse wird ein eigener Link mit eigenem Token, die übrigen Felder gelten für alle. Ein eigener Name ist im Stapel nicht verfügbar.

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/a","https://example.com/b","https://example.com/c"]}'

Die Antwort enthält batch: true und ein Array results mit einem Eintrag pro Adresse in der gesendeten Reihenfolge. Eine fehlerhafte Adresse ergibt einen Eintrag mit ok: false und dem Fehlercode, ohne die übrigen zu stoppen.

Weitere Einstellungen

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "name": "my-article",
    "expires_days": 30,
    "max_hits": 1000,
    "self_destruct": true,
    "password": "secret",
    "note": "Available until the end of the month",
    "delay": 5,
    "tags": "blog,promo",
    "qr": true,
    "qr_size": 300,
    "qr_format": "png"
  }'

Als kostenpflichtig markierte Optionen werden für Gäste und im Free-Tarif ignoriert. Die Antwort gibt die Einstellungen wieder, die der Link tatsächlich erhalten hat.

Links auflisten

GET /api/v1/links

Erfordert ein Kontotoken. Links werden neueste zuerst zurückgegeben.

curl "http://anonym.es/api/v1/links?page=1&per=50" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Suche und Tag-Filter lassen sich kombinieren:

curl "http://anonym.es/api/v1/links?q=example&tag=promo" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Felder der Antwort:

Einen Link über die Kurzadresse finden

Ein Link wird über seine numerische ID angesprochen (Feld id, zum Beispiel 4821), nicht über den Namen in der Kurzadresse. Ist nur die Kurzadresse bekannt, lässt sich die ID mit jedem Token ermitteln, das diesen Link verwaltet:

curl --get http://anonym.es/api/v1/links/lookup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "short=http://anonym.es/k7m2q"

Linkdetails und Statistik

GET /api/v1/links/{id}

Liefert die Einstellungen des Links, seinen Status, die Zahl der Besuche und der eindeutigen Besucher über seine gesamte Lebensdauer:

curl http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

Mit einem Kontotoken fügt der Parameter stats einen Besuchsbericht hinzu:

curl "http://anonym.es/api/v1/links/4821?stats=day" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Felder der Antwort: stats

Einen Link ändern

PATCH /api/v1/links/{id}

Nur die gesendeten Felder ändern sich:

curl -X PATCH http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"max_hits": 2000, "delay": 3, "tags": "blog,updated"}'

Einen Wert löschen

• password, note und tags: ein leerer String entfernt den Wert.
• expires_days und max_hits: null, ein leerer String oder 0 hebt das Limit auf. self_destruct erlischt, wenn weder Limit noch Lebensdauer bleibt.
• delay: null oder ein leerer String stellt den Tarifstandard wieder her. 0 bedeutet sofortige Weiterleitung.
• url kann nicht geleert werden, und ein reiner Notizlink braucht weiterhin eine Notiz.

curl -X PATCH http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "", "note": "", "expires_days": null, "max_hits": null, "delay": 0}'

Einen Link löschen

DELETE /api/v1/links/{id}

curl -X DELETE http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

Nach dem Löschen ist der eigene Name wieder frei. Die Statistik wird mit dem Link gelöscht.

Felder der Antwort:

QR-Code

Für ein HTML-img-Tag fordern Sie den Code über die Kurzadresse an. Dieser Endpunkt braucht kein Token: Die Kurzadresse selbst ist der Schlüssel, und jeder, der sie kennt, kann denselben Code erzeugen.

<img
  src="http://anonym.es/api/v1/qr?short=http%3A%2F%2Fanonym.es%2Fk7m2q&qr_size=400"
  alt="QR code"
>

Serverseitiger Code kann das Bild auch per ID mit Token anfordern oder es base64-codiert in JSON erhalten, indem qr=true an den Aufruf zum Anlegen oder zu den Details angehängt wird:

curl "http://anonym.es/api/v1/links/4821/qr?qr_size=400&qr_format=svg" \
  -H "Authorization: Bearer YOUR_TOKEN" -o qr.svg

Parameter beider Bild-Endpunkte:

Das Feld qr in JSON-Antworten:

Kontodetails

GET /api/v1/me

Erfordert ein Kontotoken. Liefert den Tarif, seine Limits und die verbleibende Quote:

curl http://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Fehler

Fehler werden in einem einheitlichen JSON-Format zurückgegeben:

{
  "ok": false,
  "error": "taken",
  "message": "This name is already taken.",
  "field": "name",
  "suggest": ["my-article-26", "my-my-article", "my-article-link"]
}

field enthält den Namen des fehlerhaften Parameters oder null, wenn der Fehler kein bestimmtes Feld betrifft. Ein vergebener Name ergänzt suggest, eine kostenpflichtige Option upgrade, Quoten und Ratenlimits den Header Retry-After.

Ratenlimits

Jeder Aufruf kostet Einheiten, und jeder Tarif hat ein Budget an Einheiten pro Minute (siehe Tarife und Limits). Ein Lesezugriff kostet 1 Einheit, eine Listenseite 2, ein QR-Code 3, eine Änderung 3, ein Löschen 2, ein Anlegen 5 plus 1 pro Adresse. Jede Antwort trägt diese Header:

Tarife und Limits

Die genauen Limits jedes Tarifs. Links zählen im Free-Tarif pro Tag und IP-Adresse, in bezahlten Tarifen pro Monat und Konto. Die letzte Spalte nennt die Einstellungen, die ein Tarif nutzen kann.

OpenAPI-Spezifikation

Die vollständige technische Beschreibung als OpenAPI-3.1-Dokument: http://anonym.es/api/v1/openapi.json

Es enthält Schemata und Beispiele aller Anfragen und Antworten, die Tariflimits, die Namensregeln und die Fehlercodes. Es eignet sich für Swagger UI, Postman, Insomnia und Client-Generatoren.