API Upload einrichten und nutzen

Ö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.

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.

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 <Token>.

Authentifizierung

Jeder Aufruf muss den Bearer Token der Quelle mitsenden:

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:

{
  "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

string

erforderlich

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.

file

Die hochzuladende Datei (multipart/form-data). Erforderlich, wenn kein text übergeben wird.

object

Text-Upload als JSON (application/json). Erforderlich, wenn keine Datei übergeben wird.

Anzeigen Eigenschaften

string

erforderlich

Inhalt des Dokuments. Leerer oder nur aus Leerzeichen bestehender Inhalt wird abgelehnt.

string

Dateiname ohne Erweiterung. Der Text wird als Datei <name>.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.

curl -X POST 'https://ihre-domain.de/api/knowledgebase-source/<source>/upload?externalIdentifier=doc-4711' \
  -H 'Authorization: Bearer <Token>' \
  -F 'resource=@/pfad/zu/handbuch.pdf'

curl -X POST 'https://ihre-domain.de/api/knowledgebase-source/<source>/upload?externalIdentifier=faq-42' \
  -H 'Authorization: Bearer <Token>' \
  -H 'Content-Type: application/json' \
  -d '{"text": {"content": "Antworten auf häufige Fragen ...", "name": "faq-support"}}'

{
  "success": true
}

{
  "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.

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

string

erforderlich

Kennung, die beim Hochladen verwendet wurde.

cURL

curl 'https://ihre-domain.de/api/knowledgebase-source/<source>/status?externalIdentifier=doc-4711' \
  -H 'Authorization: Bearer <Token>'

Erfolg

{
  "success": true,
  "status": "done"
}

string

erforderlich

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.

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

string

erforderlich

Kennung, die beim Hochladen verwendet wurde.

cURL

curl -X DELETE 'https://ihre-domain.de/api/knowledgebase-source/<source>/delete?externalIdentifier=doc-4711' \
  -H 'Authorization: Bearer <Token>'

{
  "success": true
}

{
  "success": false,
  "errorMessage": "No document found for source <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:

Altes Dokument löschen

DELETE .../delete?externalIdentifier=doc-4711

Neue Version hochladen

POST .../upload?externalIdentifier=doc-4711 mit der neuen Datei oder dem neuen Text.

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 <Token>` mitsenden.
`Authorization header is not a Bearer token` (HTTP 401)	Der Header hat nicht das Format `Bearer <Token>`.	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.

Einführung

Nutzung

Administration

Installation

Betrieb

Sicherheit

Changelog

API Upload einrichten und nutzen

Voraussetzungen

Endpunkt und Bearer Token

Endpunkte

Authentifizierung

Externe Kennung

Dokument hochladen

Status abfragen

Dokument löschen

Anwendungsbeispiel: Dokument aktualisieren

Typische Fehler und Lösungen

​Voraussetzungen

​Endpunkt und Bearer Token

​Endpunkte

​Authentifizierung

​Externe Kennung

​Dokument hochladen

​Status abfragen

​Dokument löschen

​Anwendungsbeispiel: Dokument aktualisieren

​Typische Fehler und Lösungen

Voraussetzungen

Endpunkt und Bearer Token

Endpunkte

Authentifizierung

Externe Kennung

Dokument hochladen

Status abfragen

Dokument löschen

Anwendungsbeispiel: Dokument aktualisieren

Typische Fehler und Lösungen