Du hast die API aktiviert und deinen Schlüssel erstellt? Dann geht es hier weiter: So verwendest du die Kraaft API ⚡
Dieser Artikel sammelt die Feinheiten, die man nur beim intensiven Testen der API entdeckt — halte ihn griffbereit, falls dein Make-Szenario hängen bleibt, dir ein Feld komisch vorkommt, oder du eine über die API erstellte Unterhaltung nicht wiederfindest 🕵️
📦 Die Ressourcen der API im Detail
🗂️ Workspaces — listet die mit deinem Schlüssel zugänglichen Arbeitsbereiche auf
📋 Schemas — gibt dir die Struktur eines Berichts (die Felder, und bei Auswahlfeldern die Zuordnung zwischen jeder
idund ihrem Label)📝 Records — listet, liest, erstellt und bearbeitet die Berichte eines bestimmten Schemas
💬 Conversations (Rooms) — liest, erstellt und bearbeitet eine Unterhaltung, verwaltet ihre Mitglieder und sendet Nachrichten (Text und Dateien)
⚡ Events — listet vergangene Ereignisse auf oder bleibt verbunden, um sie in Echtzeit zu empfangen, sobald sich ein Bericht ändert
🤖 Mit Make, n8n oder Zapier verbinden
✅ Make — installiere die Kraaft-App direkt über make.kraaft.co: die Authentifizierung erfolgt per OAuth, mit einem Klick — kein manuelles Kopieren eines API-Schlüssels mehr nötig
🔧 n8n, Zapier und andere — aktuell kein nativer Kraaft-Connector: nutze das HTTP- oder API-Request-Modul deines Tools, mit deinem Kraaft-API-Schlüssel als Bearer-Token
🔒 Die 4 Schlüsselrollen — was sie wirklich tun
Jeder API-Schlüssel hat eine Rolle, genau wie ein normaler Kraaft-Nutzer: Extern, Standard, Administrator, Inhaber 👤 Ihr tatsächliches Verhalten hält aber ein paar Überraschungen bereit ⬇️
🚫 Extern — kann keine Unterhaltung erstellen (Fehler: fehlendes "Room.create"). Er kann nur in Unterhaltungen handeln (Nachricht senden, Bericht erstellen), in denen er bereits Mitglied ist
⚠️ Standard — kann eine Unterhaltung erstellen, wird ihr aber nicht automatisch als Mitglied hinzugefügt! Denke daran, direkt danach den Endpunkt aufzurufen, der ein Mitglied zur Unterhaltung hinzufügt — mit einem Admin-/Inhaber-Schlüssel oder einem anderen Schlüssel, der bereits Mitglied ist. Sonst bleibt der Standard-Schlüssel von der gerade erstellten Unterhaltung ausgesperrt, weder lesend noch schreibend
✅ Administrator & Inhaber — voller Zugriff auf den Arbeitsbereich, ohne Mitglied einer Unterhaltung sein zu müssen: sie sehen und bearbeiten jede nicht-private Unterhaltung, auch die, die sie gerade erst erstellt haben
💡 Der richtige Reflex, wenn du feststeckst: Wenn dein Make-Szenario mit einem Standard-Schlüssel "nichts sieht" oder "direkt nach dem Erstellen einer Unterhaltung abbricht", ist das sehr wahrscheinlich diese Mitgliedschaftsfalle — kein Bug. Zwei Lösungen: nutze für dieses Szenario einen Admin-/Inhaber-Schlüssel, oder lass deinen Schlüssel von jemandem als Mitglied hinzufügen, der bereits Zugriff auf die Unterhaltung hat.
🆔 Eine ID in ein Label auflösen
Auswahlfelder (Status, Kategorien…) und Nutzerfelder liefern nicht das in der App angezeigte Label — sondern nur eine technische ID 🔢
✅ Für ein Auswahlfeld: hole dir das Schema des Berichts (
GET Schema) — jede Option listet dort ihreidund ihrlabelauf, du musst sie nur einander zuordnen❌ Für einen Nutzer: keine automatische Lösung über die API — es gibt keinen Endpunkt, der Name oder E-Mail eines Nutzers anhand seiner ID liefert. Frag unseren Support nach einem Export der IDs deines Arbeitsbereichs, um sie zuzuordnen
🧩 Listen- und Tabellenfelder über die API verstehen
Bei einem Bericht mit einfachen Feldern (Text, Zahl, Checkbox, Datum, Auswahl, Foto) liefert dir das Schema alle Daten direkt. Bei Listen- und Tabellenfeldern — häufig in Berichten (Stundenzettel, Material, Kontrollen) — ist die Struktur komplexer 🧩
Beispiel: ein wöchentlicher Stundenzettel. In der App zeigt das Feld "Stundenzettel der Woche" einen Abschnitt pro Tag (Montag, Dienstag…) mit jeweils mehreren Feldern. Über die API liefert dasselbe Feld:
"stundenzettel_der_woche": { "type": "multiple", "ofType": "recordId", "value": ["id_montag", "id_dienstag", "id_mittwoch", ...] }Kurz gesagt: Die API funktioniert gut für einfache Felder, aber noch nicht im Detail für Listen- und Tabellenfelder — der genaue Inhalt jeder Zeile ist nicht direkt zugänglich.
⚡ Filtern und Echtzeit: was es schon gibt
Zwei fortgeschrittene Fähigkeiten gibt es bereits und sind gut zu kennen, ohne hier ins Detail zu gehen (die Doku auf developers.kraaft.co deckt das ab):
🔍 Serverseitig filtern — Berichts- und Ereignislisten akzeptieren einen Filterparameter (zum Beispiel: nur Berichte, deren Status sich geändert hat), statt alles abzurufen und selbst zu sortieren
📡 Ereignisse in Echtzeit empfangen — statt die API regelmäßig abzufragen, kannst du verbunden bleiben und jede Änderung sofort empfangen, sobald sie eintritt (praktisch für eine reaktive Integration, z. B. um ein ERP in unter einer Sekunde zu benachrichtigen)
🚫 Was heute noch nicht möglich ist
⚠️ Über die API noch nicht möglich
🗑️ Einen Bericht oder eine Unterhaltung löschen — nur das Archivieren einer Unterhaltung ist möglich, nicht das Löschen
👤 Den Namen oder die E-Mail eines Nutzers automatisch anhand seiner ID abrufen — frag bei Bedarf unseren Support nach einem Export (siehe oben)