Zum Inhalt wechseln
cutty.dev
Für Entwickler

API und MCP-Server

Erstellen und verwalten Sie Kurzlinks direkt aus dem Code heraus — über die REST-API oder über den MCP-Server in Ihrem KI-Assistenten.

cutty hat eine öffentliche API und einen MCP-Server. Mit der ersten erstellst und änderst du Links direkt aus dem Code; der zweite arbeitet direkt mit einem KI-Assistenten, der das MCP-Protokoll spricht. Beide nutzen denselben API-Schlüssel.

API-Schlüssel

Authentifiziere jeden Aufruf mit einem Header:

Authorization: Bearer ck_your_key

Wo du einen Schlüssel bekommst: melde dich an, öffne dein Dashboard → API keys → Create key. Der vollständige Schlüssel (er beginnt mit ck_) wird nur einmal angezeigt, bei der Erstellung — speichere ihn sofort an einem sicheren Ort. Das Limit liegt bei 120 Anfragen pro Minute pro Schlüssel.

Basis-URL

Alle REST-Endpunkte liegen unter https://cutty.dev/api/v1. Anfragen und Antworten sind JSON.

Einen Link erstellen

POST /api/v1/links — der JSON-Body braucht mindestens eine url. Der Rest ist optional:

  • url — Zieladresse (erforderlich)
  • slug — eigene Endung, 3–40 Zeichen; weglassen für eine zufällige
  • expiresAt — Ablaufdatum im ISO 8601-Format
  • maxHits — Klick-Limit (1–1.000.000)
  • password — Passwort zum Schutz des Links
  • tags — kommagetrennte Labels zum Organisieren im Dashboard
  • folder — Name des Ordners, in den der Link kommt
  • utmSource, utmMedium, utmCampaign — UTM-Parameter, die bei der Weiterleitung angehängt werden

Die Antwort liefert dir slug, shortUrl und target.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

Auflisten und ein einzelner Link

GET /api/v1/links gibt alle deine Links zurück. GET /api/v1/links/{slug} — Details zu einem.

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

Aktualisieren und löschen

PATCH /api/v1/links/{slug} aktualisiert die Felder, die du übergibst, DELETE /api/v1/links/{slug} entfernt den Link.

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

Über PATCH kannst du unter anderem setzen: targetUrl, expiresAt, maxHits, status, password, tags, folder sowie die erweiterten Felder unten. Ein Feld, das auf null (oder einen leeren String) gesetzt wird, löscht diese Eigenschaft.

Targeting, A/B und erweiterte Felder

Dieselben Dinge, die du im Link-Editor hast, sind über die API verfügbar:

  • rules — ein Array von Weiterleitungsregeln nach Land oder Gerät, z. B. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B-Rotation: ein Array [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; wird verwendet, wenn keine Regel passt
  • startsAt — Datum (ISO 8601), an dem der Link aktiv wird; davor gibt der Link 425 zurück
  • webhookUrl — Adresse, die bei jedem Klick eine POST-Benachrichtigung erhält (fire-and-forget)
  • serveOg mit ogTitle, ogDescription, ogImageUrl — eine eigene Vorschaukarte für Social-Media-Crawler (Menschen werden weiterhin weitergeleitet)
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

Massenoperationen

POST /api/v1/bulk erstellt viele Links in einer Anfrage. Übergib ein links-Array (jeder Eintrag wie beim normalen Erstellen), bis zu 500 auf einmal. Die Antwort gibt ein Ergebnis pro Zeile zurück.

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

Link-Statistiken

GET /api/v1/links/{slug}/stats gibt eine Klick-Zusammenfassung zurück: die Gesamtzahl, eine Aufschlüsselung nach Gerät und Browser sowie die Verteilung über die letzten 24 Stunden.

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

MCP-Server

Wenn du mit einem KI-Assistenten arbeitest, kannst du cutty über MCP (Model Context Protocol) anbinden und ihn bitten, Links direkt im Gespräch zu kürzen und zu organisieren. Der Server läuft unter https://mcp.cutty.dev/mcp über Streamable HTTP, und du authentifizierst dich mit demselben API-Schlüssel — dem Header Authorization: Bearer ck_....

Die vollständige Tool-Liste, fertige Verbindungs-Snippets und Beispiele findest du auf einer eigenen Seite: cutty MCP-Server.

Etwas funktioniert nicht?

Schreib an [email protected] — ich antworte noch am selben Tag.