Die REST-API

Die Basis-URL ist https://api.frwrd.to. Jeder Aufruf außer dem Anlegen und Zurückholen eines Workspace nimmt deinen Workspace-Schlüssel als Bearer-Token:

Authorization: Bearer fw_...

Die Beispiele unten lesen den Schlüssel aus $FRWRD_KEY. Bodies sind JSON, sofern das Beispiel nichts anderes sagt.

Einen Kurzlink anlegen:

curl -X POST https://api.frwrd.to/v1/links -H "Authorization: Bearer $FRWRD_KEY" -H "Content-Type: application/json" -d '{"long_url":"https://example.com/a/long/address","title":"Beispiel"}'

Die Antwort enthält den Kurzlink link, seinen hash und die Adressen seines QR-Codes. Nur Ziele mit http und https werden angenommen. Du kannst auch tags, utm und, in einem bestätigten Workspace, einen eigenen hash mitschicken.

Hat dein Workspace Standard-UTM-Parameter, werden sie vor dem Speichern an das Ziel angehängt, und long_url in der Antwort ist dieses gespeicherte Ziel. Ein utm, das du mit dem Link schickst, hat für die Schlüssel, die du angibst, Vorrang vor den Standardwerten, und ein utm_-Parameter, der schon in der Adresse steht, hat Vorrang vor beiden. Bestehende Links ändern sich nicht.

Die Standardwerte setzt du so (die Schlüssel sind source, medium, campaign, term und content; die neue Menge ersetzt die alte, und {} leert sie):

curl -X PUT https://api.frwrd.to/v1/workspace/utm -H "Authorization: Bearer $FRWRD_KEY" -H "Content-Type: application/json" -d '{"utm":{"source":"newsletter","medium":"email"}}'

Links auflisten, die neuesten zuerst (limit bis 200, dazu offset):

curl "https://api.frwrd.to/v1/links?limit=50" -H "Authorization: Bearer $FRWRD_KEY"

Zahlen für einen Link, standardmäßig die letzten 30 Tage (since und until nehmen ein Datum wie 2026-10-01, höchstens 366 Tage auseinander):

curl "https://api.frwrd.to/v1/links/aB3xZ9/stats?since=2026-10-01" -H "Authorization: Bearer $FRWRD_KEY"

Die Antwort nennt die Summe, die Aufteilung nach Kanal (link für einen direkten Klick, qr für einen Scan, page für einen Klick auf einer Bio-Seite) und die Zahlen pro Tag.

Für ein Diagramm fragst du stattdessen einen Zeitraum an: ?range=1d sind die letzten 24 Stunden in 24 Stunden-Blöcken, 7d und 30d die letzten 7 oder 30 UTC-Tage in Tagesblöcken. Die Antwort enthält dann zusätzlich buckets (jeder mit start und einer Zahl pro Kanal, auch Nullen, kein Block fehlt) und all_time, die Summen seit dem ersten Klick. Ein anderer Wert ist ein 400, und ein Zeitraum lässt sich nicht mit since oder until kombinieren. Dasselbe gilt für die Seitenzahlen weiter unten.

Die Zahlen aller deiner Links auf einmal, damit du nicht jeden einzeln öffnen musst:

curl "https://api.frwrd.to/v1/workspace/stats?range=30d" -H "Authorization: Bearer $FRWRD_KEY"

Sie zählt die Klicks auf jeden Link des Workspace zusammen (archivierte Links zählen mit, sie wurden geklickt; Aufrufe von Bio-Seiten nicht), in dieselben buckets, mit total, by_channel und all_time, und ergänzt top: die zehn Links mit den meisten Klicks im Zeitraum, je mit hash, title, short_url, archived, total und by_channel. range ist 1d, 7d (der Standard) oder 30d. Die Antwort wird zwischengespeichert und kann bis zu 5 Minuten alt sein; all_time ist null, wenn die Summe gerade nicht gezählt werden konnte (alles andere ist trotzdem da). Ist der Server ausgelastet, antwortet er mit 429 und einem Retry-After: versuche es in ein paar Sekunden noch einmal.

Der QR-Code als PNG oder SVG (size von 128 bis 2048):

curl "https://api.frwrd.to/v1/links/aB3xZ9/qr.png?size=512" -H "Authorization: Bearer $FRWRD_KEY" -o code.png

Um einen Link zu ändern, sende PATCH /v1/links/{hash} mit long_url, title, tags und archived, je nachdem, was sich ändert. DELETE /v1/links/{hash} archiviert ihn: Er leitet nicht mehr weiter, seine Zahlen bleiben.

Seiten

Eine Seite ist ein Markdown-Dokument mit einem kurzen Kopf. Du speicherst das ganze Dokument in einem Aufruf. Der Pfad - ist die Startseite; eine Seite in einer anderen Sprache liegt unter ihrem Sprachkürzel, und der Schrägstrich wird als %2F geschrieben, etwa de%2Fhilfe.

curl -X PUT https://api.frwrd.to/v1/pages/hallo -H "Authorization: Bearer $FRWRD_KEY" -H "Content-Type: text/markdown" --data-binary @hallo.md

Jeder Link im Dokument wird ein Kurzlink deines Workspace. Um eine Seite als Markdown zurückzulesen, sende Accept: text/markdown; die Antwort trägt einen ETag. Schick ihn beim Speichern als If-Match zurück, dann schlägt der Aufruf mit 412 fehl, wenn die Seite inzwischen jemand geändert hat.

Aufrufe einer Seite und Klicks auf jeden ihrer Links:

curl "https://api.frwrd.to/v1/pages/hallo/stats" -H "Authorization: Bearer $FRWRD_KEY"

GET /v1/pages listet deine Seiten, GET /v1/pages/{path}/versions zeigt den Verlauf und DELETE /v1/pages/{path} archiviert eine Seite.

Bit.ly-kompatibles /v4

Werkzeuge, die Bit.lys v4-API sprechen, können auf https://api.frwrd.to/v4 zeigen und deinen Workspace-Schlüssel als Token nutzen. Diese Aufrufe gibt es, mit Bit.lys Antworten, Zeitstempeln und Fehlermeldungen:

Alles andere von Bit.ly wird nicht angeboten. Ein aufgebrauchtes Link-Kontingent antwortet mit 429 und MONTHLY_LIMIT_EXCEEDED.

Den Workspace löschen

DELETE /v1/workspace löscht den Workspace. Einen Workspace zu löschen stoppt seinen Schlüssel und nimmt seine Seiten sofort offline; nach 7 Tagen werden die Seiten und Einstellungen gelöscht. Kurzlinks funktionieren weiter. Wer die Domain innerhalb von 7 Tagen erneut nachweist (Rückholung des Schlüssels), bekommt alles zurück; bis zu 60 Tage danach die Links. Nach 60 Tagen ist die Domain frei und die Links funktionieren ohne Besitzer weiter. Browser können Kopien einer Seite, ihres QR-Codes und der Bilder bis zu einer Stunde nach dem Löschen behalten. Schick die Domain des Workspace als confirm mit; ein fehlender oder anderer Wert ergibt 400, und nichts wird gelöscht. Die Antwort ist 204, und der Schlüssel funktioniert danach nicht mehr.

curl -X DELETE https://api.frwrd.to/v1/workspace -H "Authorization: Bearer $FRWRD_KEY" -H "Content-Type: application/json" -d '{"confirm":"acme.com"}'

Grenzen und Fehler

Der vollständige Vertrag ist ein OpenAPI-Dokument, das beim Quellcode liegt, und der ist noch nicht öffentlich. Bis dahin beschreiben die Aufrufe oben, die Beschreibungen der MCP-Tools und frwrd.to/llms.txt die API.