Die LinkHarbor-API im Überblick

Mit der REST-API steuerst du LinkHarbor aus eigenen Programmen: Pages und Links anlegen, Entwürfe ändern und veröffentlichen, Short Links erzeugen oder Statistiken in dein eigenes Reporting holen. Dieser Artikel richtet sich an Entwicklerinnen und Entwickler und erklärt die Grundregeln, die für alle Endpunkte gelten.

#Welcher Weg passt?

#Basis-URL und Versionierung

Basis-URL

https://dock.at-harbor.com – alle Produkt-Endpunkte liegen unter /v1, zum Beispiel https://dock.at-harbor.com/v1/pages.

Version

Es gibt aktuell nur die Version v1. Die Versionsnummer steckt im Pfad.

Protokoll

Ausschließlich HTTPS.

OpenAPI

Die maschinenlesbare Beschreibung (OpenAPI 3.1) liegt unter https://dock.at-harbor.com/openapi.yaml. Du kannst sie in Postman, Insomnia oder einen Code-Generator laden.

#Testen in der Sandbox

Zum Entwickeln und Testen gibt es eine eigene Sandbox. Sie verhält sich wie die echte API, ist aber vollständig von ihr getrennt: eigene Konten, eigene Daten, nichts davon landet in deinem echten Workspace.

API

https://drydock.at-harbor.com, mit denselben Pfaden wie oben, etwa https://drydock.at-harbor.com/v1/pages.

Dashboard

https://sandbox-deck.linkharbor.com, zum Beispiel um API-Keys anzulegen.

Pages

Veröffentlichte Pages erscheinen unter https://<handle>.sandbox.linkharbor.com.

Konto

Dein echtes LinkHarbor-Konto gilt dort nicht. Lege ein eigenes Sandbox-Konto an.

Die Sandbox verschickt keine E-Mails. Registrierst du dich über die API (POST /v1/auth/register), steht der Bestätigungscode direkt in der Antwort im Feld _dev_verification. Dasselbe gilt für Passwort-Reset und E-Mail-Wechsel. Dieses Feld gibt es nur in der Sandbox, verlasse dich in deinem Code nicht darauf.

• Push-Nachrichten sind abgeschaltet
• Zahlungen laufen über den Testmodus von Stripe, es wird kein echtes Geld bewegt
• Die Rate-Limits liegen bei etwa einem Drittel der echten Werte, neue Konten sind auf 5 pro Stunde und IP-Adresse begrenzt
• Am 1. jedes Monats um 3:00 Uhr UTC wird die Sandbox vollständig geleert, alle Konten und Daten sind danach weg
• Jede Antwort trägt den Header X-Environment: sandbox

#Anmeldung in Kürze

1. Als Eigentümer oder Admin im Dashboard unter „Callback & API“ einen API-Key mit den nötigen Scopes anlegen (ab Creator Pro)
2. Key-ID und Key-Secret per POST /v1/token gegen ein Access-Token tauschen
3. Das Token bei jeder Anfrage im Header Authorization: Bearer … mitschicken
4. Nach 15 Minuten ein neues Token holen

Alle Details stehen unter API-Schlüssel und Token, die Berechtigungen unter Scopes.

#Anfragen und Antworten

Format

Anfragen und Antworten sind JSON in UTF-8. Uploads von Dateien gehen zusätzlich als multipart/form-data.

Content-Type

Schick bei jeder Anfrage mit Body den Header Content-Type: application/json. Ein anderer Typ wird mit 400 bad_request abgelehnt – auch der, den curl ohne diesen Header bei -d automatisch setzt.

Unbekannte Felder

Felder, die ein Endpunkt nicht kennt, führen zu 422 validation_failed. Die Antwort nennt die unbekannten Felder.

Kaputtes JSON

Führt zu 400 invalid_json.

Größe

Ein Body darf je nach Endpunkt höchstens 64 KB, 1 MB oder 2 MB groß sein, ein Datei-Upload 10 MB. Ist er größer, antwortet die API mit 413 request_too_large. Alle Grenzen stehen unter Rate Limits.

Listen

Kommen als Objekt mit dem Feld items, zum Beispiel {"items":[…]}.

Anlegen

Antwortet mit HTTP 201 und der neuen ID, zum Beispiel {"id":123}.

Aktionen ohne Rückgabewert

Antworten mit {"ok":true}.

Fehler

Haben immer ein festes Format mit einem maschinenlesbaren Code. Siehe Fehlerformat und Fehlercodes.

#Paginierung

Es gibt kein einheitliches Paginierungsschema. Die meisten Listen sind klein und kommen vollständig zurück; nur einige Endpunkte haben Parameter:

Für sort bei Short Links gibt es created_desc, created_asc, redirects_desc und redirects_asc; q sucht in Slug, Titel und Ziel-URL (bis 100 Zeichen, Groß- und Kleinschreibung egal). Bei Statistiken sind für period die Werte 24h, 7d, 30d, 90d, this_month, last_month, last_30d und custom erlaubt; alternativ gibst du from und to an. granularity ist hour oder day.

#Request-ID und Sprache

• Jede Antwort trägt den Header X-Request-Id – gib ihn bei Support-Anfragen mit an
• Schickst du selbst einen X-Request-Id-Header, übernimmt die API ihn
• Der Fehlertext in message kommt in der Kontosprache des Workspace-Eigentümers, sonst nach Accept-Language; der Code in error bleibt immer gleich

#Aus dem Browser aufrufen?

Technisch erlaubt die API Aufrufe aus dem Browser (CORS). Ein Key-Secret gehört aber nie in Code, der beim Besucher läuft – weder in eine Website noch in eine App. Ruf die API immer von deinem eigenen Server aus auf.

#Pläne

Es gibt kein Kontingent an API-Aufrufen pro Plan. Es gelten nur die Rate Limits pro Minute. Die Inhalts-Limits deines Plans – etwa Pages, Links oder Blöcke pro Page – gelten über die API genauso wie im Dashboard. Siehe Pläne im Vergleich.

#Erster Aufruf

# Key gegen Token tauschen
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Pages auflisten (Scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Ein vollständiges Beispiel mit Link anlegen, Design ändern und Veröffentlichen findest du unter Page per API aktualisieren.