API-Überblick

Die Rekomi-API spricht JSON über HTTPS. Jede Anfrage braucht einen API-Schlüssel. Jede Antwort ist JSON. Jeder Fehler hat dieselbe Form.

Basis-URLs

• Produktion: https://api.rekomi.com/api/v1

Es gibt nur eine Umgebung. Rekomi hat keinen separaten Staging- oder Sandbox-Host und keine Schlüssel für einen Testmodus: Jeder Schlüssel, den das Dashboard ausgibt, ist ein rk_live_-Schlüssel für die Produktion. Um eine Integration ohne echtes Geld durchzuspielen, schreib dem vorab angelegten Test-Affiliate Conversions gut (siehe Teste deine Integration); seine Events werden nie ausgezahlt und aus den Berichten herausgefiltert.

Content-Type

Alle Anfragen und Antworten nutzen application/json, UTF-8-kodiert. Kein XML, keine formularkodierten Anfrageinhalte.

Content-Type: application/json
Accept: application/json

Authentifizierung

Jeder Endpunkt (außer einer kleinen Gruppe öffentlicher wie /api/p/by-handle/{handle}/{campaign}, /api/p/by-domain und /api/v1/track/click) verlangt ein Bearer-Token im Header Authorization:

Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx

API-Schlüssel erzeugst du unter /dashboard/settings/api-keys. Den vollständigen Lebenszyklus (erstellen, rotieren, widerrufen, auf Lesen oder Schreiben beschränken) findest du unter Authentifizierung.

S2S-Tracking und Webhook-Payloads haben zusätzlich zur Bearer-Authentifizierung einen eigenen HMAC-Signaturschritt. Siehe S2S-Tracking und Webhooks.

Fehler

Fehler aus Geschäftsregeln unter /api/v1 sind JSON in dieser Form; Endpunkte außerhalb von /api/v1 liefern kompatible JSON-Fehler, tragen aber nicht garantiert alle drei Keys:

{
  "error": "plan_tier_required",
  "message": "White-label embed requires Growth tier or higher."
}

• error: ein stabiler String-Code. Nutze ihn für Verzweigungen in deinem Code. Codes ändern sich nach ihrer Veröffentlichung nie.
• message: eine für Menschen lesbare Beschreibung. Kann sich ändern. Nicht parsen.
• field (optional): das Feld, das den Fehler ausgelöst hat, sofern relevant.

Nicht jeder Fehler nutzt dieses Envelope. Fehler bei der Validierung der Anfrage (ein fehlerhafter Anfrageinhalt oder Query-Parameter) liefern ein Problem-Details-Objekt nach Standard mit einer Map errors ({ type, title, status, errors }), 401-Antworten haben keinen Antwortinhalt, und viele 404 ebenfalls nicht.

Häufige Fehlercodes:

Parse nie das Feld message. Verzweige immer anhand von error.

Rate-Limits

Die Limits gelten bei authentifizierten Aufrufen pro Nutzer (Aufrufe mit API-Schlüssel teilen sich das Kontingent des Nutzers, der den Schlüssel erstellt hat) und bei anonymem und Webhook-Traffic pro IP:

Überschreitest du das Limit, ist die Antwort HTTP 429 mit leerem Antwortinhalt. Warte und versuch es dann erneut, bei anhaltenden Spitzen mit exponentiellem Backoff.

Paginierung

Die zentralen Ressourcenlisten (Programme, Affiliates, Conversions, Auszahlungen) liefern Envelopes mit Cursor-Paginierung; einige Hilfslisten (ausstehende Bewerbungen, Betrugs-Events, Ranglisten) liefern stattdessen flache Arrays:

GET /api/v1/conversions?take=100&cursor=eyJpZCI6MTIzNH0

• take: Seitengröße. Höchstens 200, Standard 50. (Eine Ausnahme: GET /api/v1/conversions liefert 100 Zeilen, wenn take fehlt.)
• cursor: opaker Cursor aus dem Feld nextCursor einer vorherigen Antwort. Für die erste Seite weglassen.

Form der Antwort:

{
  "items": [ /* up to `take` items */ ],
  "nextCursor": "eyJpZCI6MTIzNH0",
  "hasMore": true
}

Ist hasMore false, bist du am Ende angekommen.

Idempotenz

Bei schreibenden Endpunkten, die neue Ressourcen anlegen, kannst du einen Header Idempotency-Key mitgeben (UUID v4 empfohlen). Innerhalb von 60 Minuten liefert derselbe Key mit demselben Payload die vorherige Antwort. Derselbe Key mit einem anderen Payload liefert HTTP 409.

Idempotency-Key: 8f14e45f-ceea-467a-bb2c-d8b8c0afc8d8

Nutze ihn für jeden Schreibvorgang, den du bei Netzwerkfehlern eventuell wiederholst.

CORS

Die API hat eine restriktive CORS-Konfiguration. Die Standard-Positivliste deckt Rekomis eigene Oberflächen ab (rekomi.com, app.rekomi.com), jede gebrandete Subdomain {handle}.rekomi.com und die verifizierte eigene Portal-Domain jeder Marke. Für Aufrufe von Server zu Server (Node.js, Go, Python, alles außerhalb eines Browsers) spielt CORS keine Rolle, du kannst also beliebige Anfragen stellen.

Anfragen aus dem Browser von deiner eigenen Domain leitest du über deinen Anwendungsserver. Über die Rekomi-Oberflächen, gebrandeten Subdomains und verifizierten eigenen Portal-Domains oben hinaus fügen wir keine beliebigen Origins von Partnern hinzu.

Das iframe für das White-Label-Embed ist ein eigener Ablauf mit eigener Origin-Positivliste pro Token; siehe Embed.

Planvoraussetzungen

Der programmatische Zugriff (API-Schlüssel) hängt von der Planstufe ab. Das Dashboard in der App unter app.rekomi.com ist in jeder bezahlten Stufe uneingeschränkt; nur rk_live_*-API-Aufrufe sind an den Plan gebunden. Der gehostete MCP-Server ist die Ausnahme: Er funktioniert in jedem Plan einschließlich der Testphase, weil jeder Tool-Aufruf über mcp.rekomi.com weitergeleitet und pro Tool durch die Zustimmungsschleife deines KI-Clients freigegeben wird statt durch eine Planprüfung der direkten API.

In der Testphase bekommst du die Funktionen der Stufe, die du bei der Anmeldung gewählt hast; eine Testphase mit Starter schaltet keine Funktionen von Growth oder Pro frei. Plangrenzen lösen ein 402 plan_tier_required aus, mit der erforderlichen und der aktuellen Stufe im Antwortinhalt:

{
  "error": "plan_tier_required",
  "required": "Growth",
  "current": "Starter",
  "trialing": false,
  "message": "White-label embed requires Growth tier or higher. Upgrade in Settings → Billing."
}

Das Dashboard (app.rekomi.com) authentifiziert über Clerk-JWTs und umgeht Plangrenzen, damit Marken ihre eigenen Daten unabhängig von der Stufe immer sehen und verwalten können.

Versionierung

Alle Routen liegen unter /api/v1. Wir führen /api/v2 ein, falls und sobald wir Breaking Changes machen. v1 bleibt nach dem Start von v2 mindestens 24 Monate verfügbar. Abkündigungen geben wir über den Blog und einen Header Deprecation in den Antworten bekannt.

Maschinenlesbare Dokumentation

LLMs und Coding-Agents, die Rekomi integrieren, sollten /docs/developers/reference.md abrufen: ein Manifest in einer einzigen Datei, das jeden /api/v1/*-Endpunkt, Form von Anfrage und Antwort, Fehlercodes, Plangrenzen, Webhook-Events, Schritte zur Signaturprüfung und Regeln für Rate-Limits in einfacher Prosa mit strukturierten Überschriften aufführt. Das Manifest wird mit jedem API-Release aktualisiert und ist die maßgebliche maschinenlesbare Spezifikation; diese Seite und der Rest von /docs/developers/* sind die für Menschen gedachten Ansichten derselben Schnittstelle.

Wie es weitergeht

• Authentifizierung: Schlüssel erzeugen, Scopes verwalten.
• S2S-Tracking: serverseitige Erfassung von Conversions.
• Leads und Anmeldungen tracken: kostenlose Anmeldungen erfassen (bei Stripe und Paddle automatisch) und einen späteren Verkauf über die E-Mail-Adresse zuordnen.
• Webhooks: Events von Rekomi empfangen.
• Embed: das Dashboard eines Affiliates auf deiner Domain einbinden.
• MCP: Claude, Cursor oder ChatGPT über den gehosteten MCP-Server mit deinem Konto verbinden.
• Referenz: jeder v1-Endpunkt mit Methode, Scope und Beispiel.