Plattform-API (/v1)
Die Plattform-API ist die versionierte HTTP-Schnittstelle von Waafir. Nutzen Sie sie, um Ihre Organisation aus Ihren eigenen Systemen heraus zu lesen und zu verwalten. Sie umfasst Ihr Team (Mitglieder einladen, Rollen ändern, Mitglieder entfernen), Zugriffsfreigaben für Datenräume, Ordner, Dateien, Q&A, Datenraum-Chat und Agenten, Aktivität und Engagement pro Gegenpartei sowie die Portfolio-Überwachung.
Sie ist eine eigene Schnittstelle neben den MCP-Servern von Waafir, die dieselbe Plattform KI-Clients als Tools bereitstellen. Beide authentifizieren sich mit denselben persönlichen Zugriffstokens.
Basis-URL
Jeder Endpunkt liegt unter:
https://app.waafir.io/api/v1Die Endpunkt-Referenz führt jeden Endpunkt mit
seinem vollständigen Pfad auf, zum Beispiel GET /api/v1/team.
Ihr erster Aufruf
- Token ausstellen. Öffnen Sie in Waafir Add-ons → Konfiguration und
stellen Sie ein persönliches Zugriffstoken aus. Ein
read-Token genügt für den Anfang. Kopieren Sie den Wert, der mitwaafir_pat_beginnt. Er wird nur einmal angezeigt. - Fragen, wer Sie sind.
GET /api/v1/sessiongibt die Identität und die Organisation zurück, als die das Token handelt. Prüfen Sie damit, ob ein Token funktioniert, bevor Sie darauf aufbauen:
curl -s https://app.waafir.io/api/v1/session \
-H "Authorization: Bearer $WAAFIR_TOKEN"{
"orgId": "…",
"userId": "…",
"email": "you@example.com",
"orgRole": "admin",
"authMethod": "pat",
"principalType": "user"
}Ein 401 bedeutet, dass das Token fehlt, falsch eingegeben, abgelaufen oder
widerrufen ist. Andere Ablehnungen enthalten in der Regel einen maschinenlesbaren
code, der auf der Seite Fehlercodes erklärt
wird. Manche enthalten keinen, greifen Sie daher immer auf den HTTP-Status
zurück.
Wie die Referenz entsteht
Die Seiten Endpunkte und Fehlercodes werden bei jeder Veröffentlichung dieser Website aus dem Routenbaum der Plattform generiert. Sie werden nicht von Hand geschrieben. Ein Produktions-Release erstellt sie aus demselben Commit wie die App, sodass sie die Routen auflisten, die dieses Release bereitstellt, mit der Rollenbeschränkung und dem Token-Scope, die jeder Endpunkt verlangt, und den Query-Parametern, die er akzeptiert. Ihre Fehlerlisten sind ein bekanntes Minimum, nicht erschöpfend: Ein Endpunkt kann Codes zurückgeben, die der Generator nicht sieht, behandeln Sie nicht aufgeführte Fehler daher anhand des HTTP-Status.
Versionierung
/v1 wird innerhalb seiner Version nur additiv erweitert. Waafir kann
Antwortfelder und optionale Anfrageparameter hinzufügen. Innerhalb von /v1
entfernt Waafir kein bestehendes Feld, ändert nicht dessen Typ und entfernt
keinen Endpunkt. Eine nicht abwärtskompatible Änderung erscheint unter einem
neuen Versionspräfix. Schreiben Sie Clients so, dass sie Felder ignorieren, die
sie nicht kennen.
Wie es weitergeht
- Authentifizierung: Tokens, Scopes, die Rollenobergrenze und auf Datenräume beschränkte Tokens.
- Endpunkte: jeder Endpunkt, nach Bereich gruppiert.
- Fehlercodes: die bekannten Ablehnungen und was dagegen zu tun ist.
- Loan-API-Referenz und das Cookbook: der Anfrage- und Antwortvertrag für die Erfassung von Daten zur Portfolio-Überwachung.