> ## Documentation Index > Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt > Use this file to discover all available pages before exploring further. # API Upload einrichten und nutzen > Bearer Token erzeugen und Dokumente über die HTTP-API in eine Wissensdatenbank hochladen, abfragen und löschen > [!TIP] > > Öffnen Sie **Admin-Menü** > **Wissensdatenbanken**. Mit der Datenquelle **API Upload** befüllen externe Systeme (z. B. ein DMS, CMS oder eine eigene Integration) eine Wissensdatenbank über HTTP-Aufrufe. Die Quelle stellt drei Endpunkte bereit: Dokument hochladen, Verarbeitungsstatus abfragen und Dokument löschen. Die Authentifizierung erfolgt über einen **Bearer Token**, der pro Quelle in der Oberfläche erzeugt wird. Eine Übersicht aller Quellentypen finden Sie unter [Wissensdatenbanken](https://docs.varios-ai.com/de/monthly/admin/knowledgebases/index.md#api-upload). ## Voraussetzungen * Eine gespeicherte Wissensdatenbank mit einer Quelle vom Typ **API Upload** (pro Wissensdatenbank ist nur eine solche Quelle möglich). * Das externe System muss die VARIOS AI Domain per HTTPS erreichen können. ## Endpunkt und Bearer Token VARIOS AI erzeugt den Bearer Token, sobald Sie die Quelle mit **Quelle anlegen** speichern. Endpunkt und Token finden Sie in der Bearbeitungsansicht der Quelle im Abschnitt **Verbindung**: | Feld | Inhalt | | - | - | | **API-Endpunkt** | Upload-URL der Quelle, über das Kopier-Symbol übernehmen | | **Bearer Token** | Maskiert angezeigt, über das Augen-Symbol einblenden | Mit **Neues Token erzeugen** und einer Bestätigung ersetzen Sie den Token, zum Beispiel wenn er in falsche Hände geraten ist. > [!WARNING] > > Behandeln Sie den Bearer Token wie ein Passwort und geben Sie ihn nur an das > externe System weiter. Nach **Neues Token erzeugen** ist der bisherige Token > sofort ungültig. Systeme, die damit hochladen, erhalten Fehler, bis Sie dort > den neuen Token eintragen. ## Endpunkte Der in der Oberfläche angezeigte **API-Endpunkt** ist die Upload-URL der Quelle. Die UUID der Quelle (`{source}`) ist Teil des Pfads; die Endpunkte für Status und Löschen verwenden denselben Pfad mit anderem Suffix. | Methode | Pfad | Zweck | | - | - | - | | `POST` | `/api/knowledgebase-source/{source}/upload` | Dokument als Datei oder Text hochladen | | `GET` | `/api/knowledgebase-source/{source}/status` | Verarbeitungsstatus eines Dokuments abrufen | | `DELETE` | `/api/knowledgebase-source/{source}/delete` | Dokument aus der Quelle entfernen | Alle Endpunkte antworten mit JSON und erwarten den Header `Authorization: Bearer `. ### Authentifizierung Jeder Aufruf muss den Bearer Token der Quelle mitsenden: ```http theme={null} Authorization: Bearer vrai_... ``` Authentifizierungsfehler werden mit HTTP-Status `401` und dem Header `WWW-Authenticate: Bearer` beantwortet. Der JSON-Body nennt in `errorMessage` die Ursache. Das folgende Beispiel zeigt einen nicht übereinstimmenden Token: ```json theme={null} { "success": false, "errorMessage": "Invalid API secret" } ``` ### Externe Kennung Jedes Dokument wird innerhalb der Quelle über den Parameter `externalIdentifier` identifiziert. Vergeben Sie dafür eine stabile, eindeutige Kennung aus Ihrem System (z. B. die Dokument-ID im Quellsystem). Dieselbe Kennung verwenden Sie später für die Statusabfrage und das Löschen. ## Dokument hochladen `POST /api/knowledgebase-source/{source}/upload` **externalIdentifier** `string` *required* Eindeutige Kennung des Dokuments im externen System. Pro Quelle darf jede Kennung nur einmal verwendet werden. Eine leere Kennung wird abgelehnt. Kann als Query-Parameter oder als Formularfeld übergeben werden. **resource** `file` Die hochzuladende Datei (`multipart/form-data`). Erforderlich, wenn kein `text` übergeben wird. **text** `object` Text-Upload als JSON (`application/json`). Erforderlich, wenn keine Datei übergeben wird. **Eigenschaften** **text.content** `string` *required* Inhalt des Dokuments. Leerer oder nur aus Leerzeichen bestehender Inhalt wird abgelehnt. **text.name** `string` Dateiname ohne Erweiterung. Der Text wird als Datei `.txt` gespeichert. Ohne Namen verwendet VARIOS AI die externe Kennung. Der Request muss **entweder** eine Datei in `resource` **oder** ein Objekt `text` mit nicht leerem `text.content` enthalten. Werden Datei und Text übergeben, wird der Text verwendet. ```bash Datei-Upload theme={null} curl -X POST 'https://ihre-domain.de/api/knowledgebase-source//upload?externalIdentifier=doc-4711' \ -H 'Authorization: Bearer ' \ -F 'resource=@/pfad/zu/handbuch.pdf' ``` ```bash Text-Upload theme={null} curl -X POST 'https://ihre-domain.de/api/knowledgebase-source//upload?externalIdentifier=faq-42' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"text": {"content": "Antworten auf häufige Fragen ...", "name": "faq-support"}}' ``` ```json Erfolg theme={null} { "success": true } ``` ```json Fehler theme={null} { "success": false, "errorMessage": "A document with the external identifier \"doc-4711\" and this source already exists." } ``` Fehler beantwortet der Endpunkt mit `"success": false` und einem passenden HTTP-Status: | Status | Bedeutung | | - | - | | `400` | Ungültige Anfrage, zum Beispiel leere externe Kennung oder kein Dokument | | `401` | Authentifizierung fehlgeschlagen | | `404` | Die Quelle ist unbekannt oder keine Quelle vom Typ **API Upload** | | `405` | Falsche HTTP-Methode. Der Header `Allow` nennt die richtige. | | `409` | Die Kennung oder der Inhalt ist in der Quelle schon vorhanden, oder ein paralleler Aufruf mit derselben Kennung läuft noch | | `422` | Das Dokument verletzt die Einstellungen der Quelle, zum Beispiel Dateiendung oder Dateigröße | Vor dem Speichern prüft die API das Dokument gegen die Quellenkonfiguration: * **Externe Kennung:** Existiert in dieser Quelle bereits ein Dokument mit derselben Kennung, wird der Upload abgelehnt. Löschen Sie das Dokument zuerst, wenn Sie es ersetzen möchten. * **Inhalt:** Existiert in dieser Quelle bereits ein Dokument mit identischem Inhalt, wird der Upload abgelehnt. * **Dateiendungen:** Die Erweiterung muss in der Einstellung **Dateiendungen** der Quelle enthalten sein. Beim Text-Upload ist das immer `txt`. * **Maximale Dateigröße:** Das Dokument darf die Einstellung **Maximale Dateigröße (MB)** nicht überschreiten. * **Leere Dokumente:** Dokumente ohne Inhalt werden abgelehnt. > [!NOTE] > > Nach erfolgreichem Upload erscheint das Dokument in der Quelle unter > **Dokumente** und wird anschließend verarbeitet und eingebettet – wie bei > allen anderen Quellentypen. ## Status abfragen `GET /api/knowledgebase-source/{source}/status` **externalIdentifier** `string` *required* Kennung, die beim Hochladen verwendet wurde. ```bash cURL theme={null} curl 'https://ihre-domain.de/api/knowledgebase-source//status?externalIdentifier=doc-4711' \ -H 'Authorization: Bearer ' ``` ```json Erfolg theme={null} { "success": true, "status": "done" } ``` **status** `string` *required* Verarbeitungsstatus des Dokuments für das Embedding-Modell der Wissensdatenbank. | Wert | Bedeutung | | - | - | | `in_progress` | Dokument wurde angenommen, Verarbeitung oder Embedding läuft noch. | | `done` | Dokument wurde erfolgreich eingebettet und ist in der Suche nutzbar. | | `error` | Verarbeitung fehlgeschlagen (z. B. Dateiformat, Lesefehler). | | `not_existing` | Zu dieser Kennung existiert in der Quelle kein Dokument. | > [!TIP] > > Fragen Sie den Status nach dem Upload in Abständen ab, bis `done` oder > `error` zurückgegeben wird. Bei `error` können Sie das Dokument löschen und > in korrigierter Form erneut hochladen. ## Dokument löschen `DELETE /api/knowledgebase-source/{source}/delete` **externalIdentifier** `string` *required* Kennung, die beim Hochladen verwendet wurde. ```bash cURL theme={null} curl -X DELETE 'https://ihre-domain.de/api/knowledgebase-source//delete?externalIdentifier=doc-4711' \ -H 'Authorization: Bearer ' ``` ```json Erfolg theme={null} { "success": true } ``` ```json Fehler theme={null} { "success": false, "errorMessage": "No document found for source and external identifier doc-4711" } ``` Das Dokument wird aus der Quelle entfernt und steht in der Wissensdatenbank nicht mehr zur Verfügung. Anschließend kann dieselbe externe Kennung erneut für einen Upload verwendet werden. Existiert kein Dokument zur Kennung, antwortet der Endpunkt mit HTTP-Status `404`. Läuft gerade ein anderer Aufruf mit derselben Kennung, antwortet er mit `409`. ## Anwendungsbeispiel: Dokument aktualisieren Die API kennt keinen eigenen Aktualisierungs-Endpunkt. Um ein geändertes Dokument einzuspielen, kombinieren Sie Löschen und Hochladen mit derselben Kennung: **1. Altes Dokument löschen** `DELETE .../delete?externalIdentifier=doc-4711` **2. Neue Version hochladen** `POST .../upload?externalIdentifier=doc-4711` mit der neuen Datei oder dem neuen Text. **3. Status prüfen** `GET .../status?externalIdentifier=doc-4711`, bis `done` zurückgegeben wird. ## Typische Fehler und Lösungen | Fehlermeldung | Ursache | Lösung | | - | - | - | | `Authorization header missing` (HTTP 401) | Der Header `Authorization` fehlt. | Header `Authorization: Bearer ` mitsenden. | | `Authorization header is not a Bearer token` (HTTP 401) | Der Header hat nicht das Format `Bearer `. | Präfix `Bearer` und Leerzeichen vor dem Token prüfen. | | `Knowledgebase source could not be resolved` (HTTP 404) | Die Quellenkennung im Pfad ist unbekannt. | Den **API-Endpunkt** aus dem Abschnitt **Verbindung** der Quelle kopieren. | | `API secret not configured` (HTTP 401) | Für die Quelle ist kein Token hinterlegt. | In der Quelle **Neues Token erzeugen** wählen. | | `Invalid API secret` (HTTP 401) | Der Token stimmt nicht mit dem Token der Quelle überein. | Aktuellen Token verwenden; nach **Neues Token erzeugen** ist nur der neue Token gültig. | | `The external identifier must not be empty.` (HTTP 400) | `externalIdentifier` fehlt oder ist leer. | Eine Kennung mitsenden. | | `No valid document provided` (HTTP 400) | Weder eine Datei in `resource` noch ein Objekt `text` mit nicht leerem `content` übergeben. | Datei als `multipart/form-data` oder Text als JSON senden. | | `A document with the external identifier "…" and this source already exists.` (HTTP 409) | Die Kennung wird in dieser Quelle bereits verwendet. | Dokument zuerst löschen oder eine andere Kennung verwenden. | | `A document with the same content already exists in this source.` (HTTP 409) | Ein inhaltlich identisches Dokument ist bereits vorhanden. | Kein erneuter Upload nötig; ggf. Inhalt prüfen. | | `The file extension "…" is not allowed. …` (HTTP 422) | Die Erweiterung ist nicht in **Dateiendungen** enthalten. | Einstellung **Dateiendungen** der Quelle erweitern oder Datei konvertieren. | | `The file size … exceeds the configured maximum of … bytes.` (HTTP 422) | Das Dokument ist größer als **Maximale Dateigröße (MB)**. | Einstellung erhöhen oder Dokument verkleinern bzw. aufteilen. | | `The document is empty.` (HTTP 422) | Das Dokument hat keinen Inhalt. | Dokument mit Inhalt hochladen. | | `No document found for source … and external identifier …` (HTTP 404) | Beim Löschen existiert zur Kennung in der Quelle kein Dokument. | Kennung prüfen; der Status `not_existing` zeigt, dass kein Dokument vorhanden ist. | | `Another operation for external identifier "…" on this source is already in progress.` (HTTP 409) | Ein paralleler Aufruf mit derselben Kennung wird noch verarbeitet. | Den Aufruf später erneut senden. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.