API Zugriff

Authentifizierung

Alle API-Requests erfordern ein Bearer Token, das im Authorization-Header mitgesendet werden muss:

Authorization: Bearer <access_token>

Token erhalten

Um ein gültiges Access Token zu bekommen, sende folgenden Request:

POST https://melibo.eu.auth0.com/oauth/token

Mit folgenden Parametern im x-www-form-urlencoded Format im Body:

Parameter	Wert
grant_type	password
client_id	mz7l3KkP8ELzR1mn5Tuv6O1YnRcxDUFh
username	Deine E-Mail-Adresse (melibo-Account)
password	Dein Passwort

Beispiel Response:

{ "access_token": "eyJ...", "expires_in": 86400, "token_type": "Bearer" }

Das access_token verwendest du dann für alle nachfolgenden API-Aufrufe im Authorization-Header.

---

Knowledge Piece erstellen

POST https://api.melibo.de/whale/v1/knowledge-bases/text

Request Body Schema:

{ "name": "string", // Titel zur Organisation "tags": ["string"], // Tags zur Strukturierung "text": "string" // Der eigentliche Wissenstext }

Beispiel:

{ "name": "Ich bin der Titel", "tags": ["topic:1"], "text": "Ich bin unstrukturierter Text" }

• name: Dient nur zur Organisation in der Plattform.

• tags: Ermöglichen eine dynamische Strukturierung. Zum Beispiel kann später im Chat Flow gezielt nach bestimmten Themen (z. B. "topic:1") gefiltert werden.

• text: Das ist der eigentliche Inhalt, der indexiert und für die Antwortgenerierung verwendet wird.

Response (relevante Felder):

{ "id": "abc123", "status": "loading" | "success" | "error", "updatedAt": "2024-01-01T12:00:00Z" }

• id: Kann später für Updates oder Löschungen genutzt werden.

• status: Zeigt den Verarbeitungsstatus des Knowledge Pieces.

• updatedAt: Zeitstempel der letzten Änderung.

---

Knowledge Piece aktualisieren

PUT https://api.melibo.de/whale/v1/knowledge-bases/text/:id

Beispiel Request Body für Text-Update:

{ "text": "Ich bin ein neuer unstrukturierter Text" }

---

Knowledge Piece löschen

DELETE https://api.melibo.de/whale/v1/knowledge-bases/:id

Der :id-Parameter ist die ID des zu löschenden Knowledge Pieces.

---

Einzelnes Knowledge Piece abrufen

GET https://api.melibo.de/whale/v1/knowledge-bases/:id

Mit der ID bekommst du das gespeicherte Knowledge Piece inklusive aller Details zurück.

---

Mehrere Knowledge Pieces abrufen

GET https://api.melibo.de/whale/v2/knowledge-bases

Du kannst verschiedene Query-Parameter verwenden, um die Ergebnisse zu filtern, zu sortieren oder zu paginieren. Die wichtigsten Parameter sind:

• limit (number, required): Anzahl der Knowledge Pieces, die zurückgegeben werden sollen.

• skip (number, required): Anzahl der zu überspringenden Knowledge Pieces (für Pagination).

• sort (string, required): Feld, nach dem sortiert werden soll (z. B. "name", "updatedAt").

• sortOrder (string, required): Sortierreihenfolge ("asc" für aufsteigend, "desc" für absteigend).

• Weitere optionale Filter:

  • name (string): Filtert nach Name.

  • kind (string): Filtert nach Typ, z. B. "text".

  • status (string): Filtert nach Status, z. B. "loading", "success" oder "error".

  • folder (string): Filtert nach Ordner.

  • tags (string, kommasepariert): Filtert nach Tags, z. B. tag1,tag2.

  • include (string): Gibt zusätzliche Felder in der Antwort zurück. z.B. "tags"

Beispiel-Request:

GET .../whale/v2/knowledge-bases?limit=10&skip=0&sort=updatedAt&sortOrder=desc&tags=topic:1,topic:2

---

Hinweis zu Ordnern

Es gibt weitere Endpunkte zur Verwaltung von Ordnern im Knowledge Hub. Diese dienen aktuell ausschließlich der Plattform-Organisation und sind für die API-Nutzung nicht relevant – daher sind sie hier nicht dokumentiert.

---

Zukunftsausblick

Aktuell ist die Authentifizierung nur über das Access Token möglich. Eine einfachere Variante über API-Keys ist bereits geplant und wird langfristig zur Verfügung stehen.