REST API

Mithilfe des Apptiva Klar REST API kann die Wissensdatenbank verwaltet werden, ohne direkt auf das CMS zugreifen zu müssen. Über diese Schnittstelle wird das Anlegen, Aktualisieren und Löschen von Wissenseinträgen ermöglicht, sodass das Verwalten von Inhalten automatisiert oder in eigene Workflows integriert werden kann. Neu können auch externe Objekte aus Drittsystemen direkt in die Wissensdatenbank importiert und synchronisiert werden. Darüber hinaus stellt das API Analytics-Daten bereit, mit denen sich Nutzung und Qualität des Chatbots auswerten lassen.

Im Folgenden wird beschrieben, wie das REST API genutzt werden kann, welche Endpunkte zur Verfügung stehen und auf welche Weise Authentifizierung sowie Fehlermanagement erfolgen. Sämtliche Methoden werden in der Swagger-Dokumentation detailliert erläutert.

Voraussetzungen

Access Token: Ein gültiges Access Token wird von Apptiva bereitgestellt und ist für die Authentifizierung erforderlich.
API-Endpunkt: Die Basis-URL der API muss bekannt sein (z. B. https://<CHATBOT-DOMAIN>/cms/api/v1/).

API Spezifikation

Alle API Funktionen sind in einer interaktiven Swagger-Dokumentation beschreiben. Diese steht unter dem Pfad https://<CHATBOT-DOMAIN>/cms/api/docs/ zur Verfügung.

In der Swagger-Dokumentation können:

Alle Endpunkte aufgelistet und eingesehen werden.
Beispielanfragen inklusive Request- und Response-Beispielen betrachtet werden.
Parameter und Datentypen detailliert überprüft werden.
Testaufrufe direkt in der Oberfläche ausgeführt werden.

Zusätzlich kann die Schnittstellendefinition im OpenAPI-Format (YAML oder JSON) direkt heruntergeladen werden:

OpenAPI YAML: https://<CHATBOT-DOMAIN>/cms/api/docs/swagger.yaml
OpenAPI JSON: https://<CHATBOT-DOMAIN>/cms/api/docs/swagger.json

Es wird empfohlen, stets mit der Swagger-Dokumentation zu beginnen, um einen Überblick über die verfügbaren Funktionen und die benötigten Felder zu erhalten.

Übersicht der Funktionen

Das REST API stellt im Wesentlichen folgende Funktionen zur Verfügung:

Wissensdatenbanken suchen, erfassen, ändern und löschen
Einträge einer Wissensdatenbank suchen, hinzufügen, ändern und löschen
Dokumente zu einem Wissensdatenbankeintrag hinzufügen, ändern und löschen
Externe Objekte aus anderen Systemen importieren und synchronisieren
Analytics-Daten abfragen (Konversationen, Chat-Nutzer, Nachrichten, Wissenslücken, Sternebewertungen, meistgenutzte Wissensquellen, LLM-Aufrufe)

Mit diesen Kernfunktionen wird der komplette Lebenszyklus von Wissenseinträgen und zugehörigen Dateien abgedeckt, was eine flexible Integration in bestehende Systeme ermöglicht.

Authentifizierung und Sicherheit

Die Authentifizierung erfolgt mittels eines Access Tokens, das von Apptiva bereitgestellt wird. Das Token wird als Bearer Token im Authorization-Header mitgegeben, um jede Anfrage zu legitimieren. Ein Beispiel für die Übergabe dieses Tokens lautet:

Authorization: Bearer <ACCESS-TOKEN>

Beispielaufrufe

Im Folgenden werden einige typische Beispiele mit curl vorgestellt. Dabei sollten <CHATBOT-DOMAIN> und <ACCESS-TOKEN> durch die entsprechenden Werte ersetzt werden.

Erstellen einer Wissensdatenbank

curl -X 'POST' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Confluence",
  "conditions": {
    "language": "DE",
    "contexts": ["LOGGED_IN_USER"]
  }
}'

Aktualisieren eines Wissenseintrags

curl -X 'PUT' \
  'http://localhost:3000/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/entries/<ID-DES_WISSENSEINTRAGS>' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Release notes version 3.42",
  "uri": "https://my.confluence.com/kb/2343",
  "sections": [
    "Version 3.42 ermöglicht nun die Benutzer-Authentifizierung via SAML und erleichtert dadurch die nahtlose Einbindung in bestehende Identity-Provider-Lösungen."
  ]
}'

Dokument zu einem Wissenseintrag hinzufügen

curl -X 'POST' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/entries/<ID-DES_WISSENSEINTRAGS>/attachments' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'origin=https://my.confluence.com/kb/2343/attachments/release-news.pdf' \
  -F 'file=@release-news.pdf;type=application/pdf'

Oder mit JavaScript

const fileInput = document.getElementById("fileInput");
const file = fileInput.files[0];

const formData = new FormData();
formData.append(
  "origin",
  "https://my.confluence.com/kb/2343/attachments/release-news.pdf",
);
formData.append("file", file, "release-news.pdf");

fetch(
  "https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/entries/<ID-DES_WISSENSEINTRAGS>/attachments",
  {
    method: "POST",
    headers: {
      accept: "application/json",
      Authorization: "Bearer <ACCESS-TOKEN>",
    },
    body: formData,
  },
);

Externe Objekte importieren

Mit dem Endpunkt /knowledge-bases/{kbId}/external-objects/{externalObjectId} kannst du Inhalte aus anderen Systemen direkt in die Wissensdatenbank übernehmen. Das eignet sich besonders für HTML-Seiten sowie für Dokumente wie PDF- oder DOCX-Dateien, die in der Wissensbasis als Quellen für Antworten verwendet werden sollen.

Dabei musst du die interne dreistufige Struktur der Wissensdatenbank nicht kennen. Du kannst einfach voneinander unabhängige Objekte direkt in eine Wissensdatenbank importieren und Apptiva Klar übernimmt die Zuordnung und Verarbeitung im Hintergrund.

Der externalObjectId muss pro Objekt stabil sein, damit das gleiche Objekt bei späteren Synchronisationen aktualisiert statt doppelt angelegt wird.

Für HTML-Inhalte wird der Inhalt direkt übergeben und intern in Text umgewandelt.

curl -X 'POST' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/external-objects/<EXTERNAL-OBJECT-ID>' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'name=Richtlinie 42' \
  -F 'uri=https://intranet.example.com/richtlinie-42.html' \
  -F 'contentType=text/html' \
  -F 'html=<article><h1>Richtlinie 42</h1><p>...</p></article>'

Für Dokumente wird die Datei hochgeladen und als Wissensquelle verarbeitet. Für DOCX-Dateien verwendest du den MIME-Type application/vnd.openxmlformats-officedocument.wordprocessingml.document.

curl -X 'POST' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/external-objects/<EXTERNAL-OBJECT-ID>' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'name=Kundenhandbuch' \
  -F 'uri=https://intranet.example.com/kundenhandbuch.pdf' \
  -F 'contentType=application/pdf' \
  -F 'file=@kundenhandbuch.pdf;type=application/pdf'

Wenn du ein einzelnes externes Objekt löschen möchtest, kannst du den folgenden Endpunkt verwenden:

curl -X 'DELETE' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/knowledge-bases/<ID-DER-WISSENSDATENBANK>/external-objects/<EXTERNAL-OBJECT-ID>' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'

Wenn du alle externen Objekte einer Wissensdatenbank auf einmal löschen willst, steht dafür zusätzlich DELETE /knowledge-bases/{kbId}/external-objects zur Verfügung.

Analytics-Daten abfragen

Der Analytics-Endpunkt liefert eine Zusammenfassung der Chatbot-Nutzung für einen frei wählbaren Zeitraum. Optional kann die Auswertung auf bestimmte Kontexte eingeschränkt werden. Der Zeitraum darf maximal 365 Tage umfassen.

curl -X 'GET' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/analytics/summary?fromDate=2024-01-01&toDate=2024-01-31&contexts=Support' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'

Die Antwort enthält pro Tag folgende Kennzahlen:

Feld	Beschreibung
`conversations`	Anzahl Konversationen mit stündlicher Aufschlüsselung; massgeblich ist jeweils das Startdatum der Konversation
`chatUserMessages`	Anzahl Nachrichten von Nutzern
`fallbackTasks`	Neu erstellte und erledigte TrainingTasks, die aus Fallbacks entstanden sind
`fallbackEvents`	Tatsächliche Fallback-Ereignisse, bei denen der Chatbot die Eingabe nicht beantworten konnte
`fallbacks`	Deprecated: identischer Alias für `fallbackTasks`
`problemTasks`	Anzahl neu erstellter und erledigter Problem-Report-Aufgaben (Daumen runter)
`tasks`	Deprecated: identischer Alias für `problemTasks`
`starRatings`	Verteilung der Sternebewertungen (1–5)
`topics`	Angefragte Themen mit Anzahl Anfragen, beantworteten Fragen, Fallbacks und Rang
`topKnowledgeBaseSources`	Meistgenutzte Wissensquellen
`llmCalls`	Anzahl Tokens und Kosten (CHF) der LLM-Aufrufe

fallbackTasks und fallbackEvents haben bewusst unterschiedliche Bedeutungen:

fallbackTasks beschreibt die Arbeit, die im CMS noch erledigt werden muss. Die Werte new und resolved stammen aus den TrainingTasks und können durch die Zusammenfassung gleicher Fallbacks kleiner sein als die Anzahl der tatsächlichen Ereignisse.
fallbackEvents beschreibt, was der Benutzer erlebt. Der tägliche Wert count stammt aus derselben Analytics-Quelle wie der Fallback-Chart im Client und entspricht deshalb dessen absolutem Fallback-Zähler. Die Prozentrate im Client wird aus fallbackEvents.count geteilt durch chatUserMessages.count berechnet.
fallbacks bleibt aus Gründen der Rückwärtskompatibilität erhalten und liefert weiterhin exakt dieselben Werte wie fallbackTasks. Neue Integrationen sollten fallbackTasks verwenden.

Monitoring-Daten abfragen

Der Monitoring-Endpunkt liefert eine Momentaufnahme des aktuellen Systemzustands. Im Gegensatz zu den Analytics-Daten gibt es keinen Zeitraum und keine Filter: Die Antwort zeigt immer den Stand zum Zeitpunkt der Abfrage. Das eignet sich zum Beispiel für die Anbindung an ein externes Monitoring oder für regelmässige Health-Checks.

curl -X 'GET' \
  'https://<CHATBOT-DOMAIN>/cms/api/v1/monitoring/summary' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'

Die Antwort enthält folgende Kennzahlen:

Feld	Beschreibung
`version`	Applikationsversion (`version`)
`podStartedAt`	Startzeitpunkt des aktuellen Pods bzw. Prozesses (`podStartedAt`, ISO 8601)
`knowledgeBases`	Anzahl Wissensdatenbanken (`total`), davon mit Indexierungsfehler (`errors`) und Aufschlüsselung nach Typ (`types`)
`knowledgeBaseEntries`	Anzahl Wissensdatenbank-Dokumente (`total`) und davon mit Fehler (`errors`); ignorierte Dokumente werden nicht mitgezählt
`knowledgeBaseEntryAttachments`	Anzahl Dokumente, die zu Wissenseinträgen hinzugefügt wurden (`total`), davon mit Fehler (`errors`), nach Typ (`types`)
`agents`	Anzahl Agenten (`total`), davon aktiv (`active`) und inaktiv (`inactive`)
`tools`	Anzahl Tools (`total`)
`mcpServers`	Anzahl MCP-Server (`total`), davon mit Fehler oder ausstehender Entfernung (`errors`)
`users`	Anzahl Benutzer (`total`) und Aufschlüsselung nach Rolle (`roles`)

Zur Bedeutung der Fehlerzähler:

knowledgeBases.errors zählt Wissensdatenbanken, deren eigener Indexierungsstatus EXTRACTION_FAILED oder INDEXING_FAILED ist. Fehler bei den zugehörigen Dokumenten oder Attachments sind darin nicht enthalten, sie werden separat in knowledgeBaseEntries und knowledgeBaseEntryAttachments ausgewiesen.
knowledgeBaseEntryAttachments zählt ausschliesslich Dokumente, die einem Wissenseintrag angehängt wurden. Sie fliessen nicht in knowledgeBases.total ein.
mcpServers.errors zählt MCP-Server, bei denen mindestens eine Funktion den Synchronisationsstatus REMOVED hat.

Fehlerbehandlung

Bei fehlerhaften Anfragen wird üblicherweise ein HTTP-Statuscode zurückgegeben, der auf die Art des Fehlers hinweist. Übliche Statuscodes sind:

400 Bad Request: Die Anfrage konnte nicht verarbeitet werden (z. B. falsche JSON-Struktur).
401 Unauthorized: Es wurde kein Access Token mitgegeben.
403 Forbidden: Das übermittelte Access Token hat keine Berechtigung.
404 Not Found: Die gewünschte Ressource existiert nicht.
413 Content Too Large: Das übermittelte Dokument (Attachment) ist zu gross.
415 Unsupported Media Type: Der Typ des übermittelten Dokuments (Attachment) wird nicht unterstützt.
500 Internal Server Error: Ein unerwarteter Serverfehler trat auf.

Voraussetzungen​

API Spezifikation​

Übersicht der Funktionen​

Authentifizierung und Sicherheit​

Beispielaufrufe​

Erstellen einer Wissensdatenbank​

Aktualisieren eines Wissenseintrags​

Dokument zu einem Wissenseintrag hinzufügen​

Externe Objekte importieren​

Analytics-Daten abfragen​

Monitoring-Daten abfragen​

Fehlerbehandlung​