---
title: Die REST-API
description: "Die REST-API von frwrd.to: Basis-URL, Autorisierung, ein curl-Beispiel für jeden Hauptaufruf, die Bit.ly-kompatible /v4-Auswahl, Rate Limits und Fehler."
theme: { accent: "#1f6feb", background: light }
translations: { en: help-api }
---

# 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.

## Links

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.

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.

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:

- `POST /v4/shorten`
- `POST /v4/expand`
- `PATCH /v4/bitlinks/frwrd.to/{hash}`
- `GET /v4/bitlinks/frwrd.to/{hash}/clicks/summary`

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

## Grenzen und Fehler

- Noch bevor sie deinen Schlüssel prüft, erlaubt die API 20 Anfragen pro Sekunde von einer Adresse (Spitzen bis 60). Danach gelten 10 pro Sekunde für jeden Workspace (Spitzen bis 30). Workspaces anzulegen oder zurückzuholen ist auf 5 pro Minute und Adresse begrenzt.
- Über einer Grenze lautet die Antwort `429` mit dem Code `rate_limited`, und ein `Retry-After`-Header sagt, wann du es wieder versuchen kannst.
- Fehler unter `/v1` sind JSON: `{"error":{"code":"...","message":"..."}}`. Richte dich nach `code`: `invalid_body`, `missing_credentials`, `invalid_credentials`, `not_found`, `conflict`, `precondition_failed`, `quota_exceeded`, `not_verified`, `rate_limited` oder `internal_error`.

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.

- [Zurück zur Hilfe](/@frwrd.to/de/hilfe)