Schnittstelle: Wissen und Assistenten

Wege der App-Schnittstelle für Wissensquellen, Suche, Prüfsatz, Einrichtung, Assistenten, Abnahmeprüfungen und Werkzeuge, mit Feldern, Rollen und Fehlern.

In einfacher Sprache

Über diese Wege verwaltet die Anwendung das Wissen und die Assistenten. Sie legen Quellen für das Wissen an. Sie pflegen Paare aus Frage und Antwort. Sie prüfen, wie gut die Suche trifft. Sie richten einen Assistenten aus Ihrer Website ein. Sie verwalten Assistenten, ihre Fassungen und den Code zum Einbau. Für jeden Weg müssen Sie in der Anwendung angemeldet sein.

Stand 19. Oktober 2026

Alle Themen der Dokumentation

Diese Seite beschreibt die Wege der App-Schnittstelle, über die Sie Wissensquellen, Frage-Antwort-Paare, den Prüfsatz der Suche, die Einrichtung aus der eigenen Website, Assistenten samt Fassungen und Einbaucode, Abnahmeprüfungen und Werkzeuge verwalten. Jeder Weg liegt unter /api/v1/ und verlangt eine Anmeldung an der App. Für Anbindungen mit einem API-Schlüssel gilt Integration.

Zugang, Rollen und Drosseln

Alle Wege dieser Seite verlangen eine gültige Anmeldung, wie sie Anmeldung beschreibt, ein aktives Konto und eine bestätigte E-Mail-Adresse. Lesen darf jede Rolle; auch Suche und Probefrage sind für jede Rolle offen, weil sie nichts schreiben. Jede Änderung am Bestand verlangt mindestens die Rolle Bearbeiten. Einen Assistenten löschen und seinen öffentlichen Schlüssel tauschen darf erst die Rolle Verwaltung.

Rolle in der App	Kennung	Rang
Lesen	`viewer`	10
Bearbeiten	`editor`	20
Verwaltung	`admin`	30
Inhaber	`owner`	40

Wer welche Rolle bekommt, steht unter Team und Rollen.

Drosseln

Einige Wege tragen eine benannte Drossel. Sie zählt je angemeldeter Person und Minute; wer darüber liegt, bekommt 429. Die allgemeinen Regeln stehen unter Grenzen.

Drossel	Anfragen je Minute	Wege
`knowledge-sources`	20	Quelle anlegen, neu einlesen, Fassung zurückholen, Vektoren nachbauen, Einrichtung starten
`knowledge-search`	60	`POST /knowledge/search`
`knowledge-ask`	30	`POST /knowledge/ask`
`knowledge-probes`	6	`POST /knowledge/probes/run`
`knowledge-tune`	2	`POST /knowledge/probes/tune`
`assistants`	30	Assistent anlegen und ändern, Fassungen, Schlüssel tauschen, Abnahme starten und Prüffragen anlegen oder ändern, Werkzeuge anlegen und ändern

Gemeinsame Fehler

Status	Kennung	Bedeutung
403	`email_unverified`	Die E-Mail-Adresse ist noch nicht bestätigt.
403	`no_tenant`, `tenant_…`	Kein Konto oder das Konto ist nicht aktiv; der Zusatz nennt seinen Stand.
403	`role_too_low`	Die eigene Rolle reicht nicht; `required` nennt die verlangte.
402	`plan_limit_reached`	Die Paketgrenze ist erreicht; `allowed`, `used` und `plan_name` nennen Grenze, Verbrauch und Paket.
503	`plan_limit_unmeasured`	Der Verbrauch ließ sich gerade nicht messen; die Anfrage wurde nicht ausgeführt.
404	`not_found`	Der Eintrag gehört nicht zu Ihrem Konto oder existiert nicht.
422	Feldfehler	Eine Angabe passt nicht zu den Regeln der Tabellen unten.
429	–	Die Drossel ist erschöpft.
500	`not_logged`	Die Protokollzeile ließ sich nicht schreiben; die Änderung wurde darum nicht ausgeführt.

Wie viele Quellen, Dokumente, Abschnitte und Assistenten Ihr Paket erlaubt, steht unter Pakete und Kontingente und auf der Seite Preise.

Wissensquellen

In der App liegen die Quellen unter Wissen (app.xicbot.de/wissen). Was eine Quelle fachlich ist und wie aus ihr Antworten entstehen, erklären Wissen und Wissensaufbau und Antworten.

GET /api/v1/knowledge/sources

Listet die Quellen des Kontos, die neuesten zuerst, höchstens 200. Dazu kommen der Stand der Vektoren (vectors), der Stand der Anreicherung mit Schlüsselwörtern und Fragen (enrichment) und die Grenzen der Eingabefelder (limits).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld in `limits`	Wert	Bedeutung
`chunk_default_chars`	800	Vorgabe der Abschnittsgröße in Zeichen
`chunk_overlap_default_chars`	120	Vorgabe der Überlappung in Zeichen
`chunk_defaults_by_type`	je Art `target`, `overlap`	Vorgabe je Quellenart; Dateien starten mit 1400 und 200
`chunk_min_chars`, `chunk_max_chars`	200, 4000	kleinste und größte einstellbare Abschnittsgröße
`exclude_max_patterns`	50	höchstens so viele Ausgeschlossene Pfade je Quelle
`exclude_max_length`	300	höchste Länge eines Musters in Zeichen
`crawl_max_pages`	25	so viele Seiten liest ein Durchgang einer Website höchstens
`refresh_min_days`, `refresh_max_days`	1, 365	zulässiger Bereich für `refresh_days`
`refresh_default_days`	Zahl	Vorgabe, wenn `refresh_days` leer bleibt

Feld in `vectors` und `enrichment`	Bedeutung
`chunks`	Zahl aller Abschnitte
`embedded`	Abschnitte mit fertigem Vektor (nur `vectors`)
`enriched`	angereicherte Abschnitte (nur `enrichment`)
`pending`	Abschnitte, die noch fehlen
`model`	Kennung des Verfahrens, das die Vektoren bildet (`vectors`) oder die Abschnitte anreichert (`enrichment`)

Jede Quelle erscheint in der Liste mit diesen Feldern:

Feld	Bedeutung
`id`, `type`, `title`, `created`	Kennung, Art, Bezeichnung, Anlagezeit
`origin`	bei Websites die Startadresse, bei Dateien der ursprüngliche Dateiname
`status`, `error`	Stand der Aufnahme und gegebenenfalls der Fehler, siehe Stände
`documents`, `chunks`	Zahl der Dokumente und Abschnitte
`version`, `versions_kept`	Nummer der Fassung, die gerade antwortet, und wie viele Fassungen vorgehalten werden (5)
`refresh_days`	die an der Quelle eingetragene Frist; `null` heißt: nichts eingetragen
`last_checked`, `last_failed`	Zeitpunkt der letzten Bestätigung (Zuletzt bestätigt) und des letzten Fehlschlags (Fehlgeschlagen am)
`fresh`, `fresh_measured`, `fresh_reason`	nur bei Websites gemessen: Aktuell oder Veraltet; sonst `fresh_measured` `false` mit Grund `not_applicable`, bei nie bestätigten Websites `never_checked`
`crawl_truncated`, `crawl_pending`, `crawl_measured`, `crawl_reason`	ob der letzte Durchgang am Seitendeckel abbrach und wie viele Verweise offen blieben; Grund `not_applicable` bei anderen Arten, `never_crawled` vor dem ersten Durchgang
`chunk_target`, `chunk_overlap`, `exclude_patterns`	eigene Einstellungen der Quelle
`pairs`	Zahl der Frage-Antwort-Paare einer Quelle der Art `faq`
`pairs_matchable`	davon die aktiven Paare mit Antwort, also die, die eine Frage beantworten können; wie `pairs` nur in dieser Liste gezählt

Stände einer Quelle

`status`	In der App	Bedeutung
`new`	neu	angelegt, Aufnahme noch nicht begonnen
`running`	wird aufgenommen	die Website wird gelesen
`ready`	aufgenommen	Inhalt steht bereit
`failed`	nicht aufgenommen	Aufnahme gescheitert, `error` nennt den Grund
`stale`	nicht mehr aktuell	eine Website wurde als veraltet markiert

GET /api/v1/knowledge/sources/{id}

Liefert eine Quelle (source) mit ihren Dokumenten (documents), sortiert nach Titel, höchstens 200. Jedes Dokument trägt id, title, url, characters, is_draft, published_at und published. Entwürfe und noch nicht veröffentlichte Dokumente sind hier mit aufgeführt. documents_total nennt, wie viele Dokumente die Quelle hat, documents_limit den Deckel der Liste (200); ist documents_total größer, ist die Liste gekürzt.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

POST /api/v1/knowledge/sources

Legt eine Quelle an. Text- und Dateiquellen werden sofort aufgenommen und kommen mit 201 zurück, auch wenn die Aufnahme scheitert: dann steht die Quelle mit status failed und error. Eine Website wird im Hintergrund gelesen; die Antwort ist 202 mit der Quelle und dem Auftrag (job mit id, status, task). Eine Quelle der Art faq steht sofort bereit und bleibt leer, bis Sie Paare anlegen. Sie gibt es je Konto einmal: Besteht schon eine, ist die Antwort 422 mit faq_exists und source_id, der Kennung der Sammlung, in die neue Paare gehen. Nach Text, Datei und Website folgt ein Auftrag, der die Vektoren bildet. In der App: Neue Quelle, dann Quelle aufnehmen.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher; Paketgrenzen für Quellen, Dokumente und Abschnitte
Begrenzung: Drossel knowledge-sources: 20 Anfragen je Minute und Person, siehe Grenzen

Feld	Pflicht	Regel
`type`	ja	`text`, `file`, `website` oder `faq` (Art der Quelle)
`title`	ja	höchstens 200 Zeichen (Bezeichnung)
`text`	bei `text`	höchstens 1 000 000 Zeichen (Inhalt)
`url`	bei `website`	gültige Adresse, höchstens 500 Zeichen (Startadresse)
`file`	bei `file`	hochgeladene Datei (Datei auswählen), als `multipart/form-data`
`refresh_days`	nein	nur bei `website`; ganze Zahl von 1 bis 365
`exclude_patterns`	nein	nur bei `website`; Liste mit höchstens 50 Mustern zu je höchstens 300 Zeichen (Ausgeschlossene Pfade)
`chunk_target`	nein	ganze Zahl von 200 bis 4000 (Abschnittsgröße)
`chunk_overlap`	nein	ganze Zahl ab 0 (Überlappung); wirksam höchstens die halbe Abschnittsgröße
`draft`	nein	nur bei `text` und `file`; wahr oder falsch
`published_at`	nein	nur bei `text` und `file`; Datum der Veröffentlichung

Eine Website-Adresse wird vor dem Anlegen geprüft. Lässt sie sich nicht lesen, nutzt sie ein anderes Schema als erlaubt, lässt sich der Name nicht auflösen oder zeigt sie auf ein nicht erlaubtes Ziel, kommt 422 mit url_unreadable, scheme_not_allowed, name_unresolvable oder target_not_allowed.

PUT /api/v1/knowledge/sources/{id}

Ändert die Einstellungen einer Quelle; PATCH wirkt genauso. Alle Felder sind freiwillig: title (höchstens 200 Zeichen), refresh_days, exclude_patterns, chunk_target, chunk_overlap mit den Regeln wie beim Anlegen; null setzt refresh_days und exclude_patterns auf die Vorgabe zurück, bei Websites auch chunk_target und chunk_overlap; title nimmt kein null an. Aufgenommen wird dabei nichts: neue Abschnittsgrößen wirken erst beim nächsten Durchgang. Bei einer Quelle, die keine Website ist, ergeben diese Angaben 422 website_only, und field nennt das betroffene Feld, bei mehreren das erste in der Reihenfolge refresh_days, exclude_patterns, chunk_target, chunk_overlap: ein Wert für refresh_days, eine nicht leere Liste in exclude_patterns, die von der gespeicherten abweicht, und ein Wert für chunk_target oder chunk_overlap, der vom gespeicherten abweicht, auch null. Dort erlaubt bleiben null für refresh_days, null oder eine leere Liste für exclude_patterns sowie die gespeicherte Liste und die gespeicherten Abschnittsgrößen. Ohne Protokolleintrag bleibt die Quelle unverändert; die Antwort ist dann 500 mit not_logged. Antwort: source.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

DELETE /api/v1/knowledge/sources/{id}

Löscht eine Quelle; die Protokollzeile hält fest, wie viele Dokumente und Abschnitte sie hatte. Zuerst wird die Protokollzeile geschrieben, im selben Schritt wie das Löschen; gelingt sie nicht, bleibt die Quelle stehen und die Antwort ist 500 mit not_logged. Antwort: {"deleted": true}.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

POST /api/v1/knowledge/sources/{id}/refresh

Liest eine Website neu ein (Neu einlesen). Mit "rebuild": true werden auch unveränderte Seiten neu in Abschnitte zerlegt (Vollständig neu aufbauen); das braucht es nach einer Änderung der Abschnittsgröße. Ist für diese Quelle schon ein Auftrag zur Aufnahme oder zum Neueinlesen offen, wartend oder laufend, wird er weiterverwendet und already_open ist true; task nennt dann seine Art, source.ingest oder source.refresh. Einen verlangten Neuaufbau nimmt ein wartender Auftrag noch mit; läuft er schon ohne Neuaufbau, kommt 409 refresh_running. Zusätzlich reiht die Schnittstelle den Vektorbau für die Quelle ein. Andere Arten als Websites ergeben 422 website_only. Antwort: 202 mit job (id, status, task) und already_open.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher; Paketgrenzen für Dokumente und Abschnitte
Begrenzung: Drossel knowledge-sources: 20 Anfragen je Minute und Person, siehe Grenzen

GET /api/v1/knowledge/jobs/{id}

Zeigt den Stand eines Auftrags aus diesem Konto: id, task, status, attempts, error, result und finished_at. Damit verfolgen Sie Aufnahme, Neueinlesen und Vektorbau. Wie Aufträge ablaufen, beschreibt Hintergrundaufträge.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Fassungen einer Quelle

GET /api/v1/knowledge/sources/{id}/versions

Listet die vorgehaltenen Fassungen einer Quelle (Fassungen). current ist die Fassung, die gerade antwortet (antwortet), kept die Zahl der vorgehaltenen Fassungen (5), versions die Liste.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

POST /api/v1/knowledge/sources/{id}/versions/{number}/restore

Holt eine frühere Fassung zurück (Zurückholen). Fassungen über der genannten werden verworfen. Eine Nummer, die nicht vor der aktuellen liegt, ergibt 422 not_a_previous_version; eine nicht mehr vorgehaltene 422 version_not_kept; ein offener Auftrag zur Aufnahme oder zum Neueinlesen dieser Quelle, wartend oder laufend, 409 refresh_running. Antwort: restored, source, current, kept (wie viele Fassungen höchstens vorgehalten werden), discarded (Zahl der verworfenen Fassungen) und versions (Liste der Fassungen).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel knowledge-sources: 20 Anfragen je Minute und Person, siehe Grenzen

POST /api/v1/knowledge/embed

Stößt den Bau der fehlenden Vektoren an, für das ganze Konto oder mit source_id für eine Quelle. Wartet schon ein solcher Auftrag, wird er weiterverwendet. Antwort: 202 mit job, already_open, vectors und enrichment.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel knowledge-sources: 20 Anfragen je Minute und Person, siehe Grenzen

Suchen und Probefrage

POST /api/v1/knowledge/search

Sucht Abschnitte zu einer Frage, ohne eine Antwort zu formulieren. Damit sehen Sie, was ein Assistent zu einer Frage findet.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: Drossel knowledge-search: 60 Anfragen je Minute und Person, siehe Grenzen

Feld	Pflicht	Regel
`question`	ja	höchstens 2000 Zeichen
`source_id`	nein	Kennung einer Quelle, um die Suche auf sie zu begrenzen
`count`	nein	1 bis 20 Treffer, Vorgabe 6
`context`	nein	wahr oder falsch, Vorgabe wahr: liefert das Umfeld des Abschnitts im Dokument mit
`language`	nein	Sprachkürzel, höchstens 5 Zeichen

Feld eines Treffers	Bedeutung
`chunk_id`, `source_id`	Kennung des Abschnitts und seiner Quelle
`document`, `heading`	Titel des Dokuments und Überschrift des Abschnitts
`excerpt`	die ersten 400 Zeichen des Abschnitts
`keywords`, `questions`	Schlüsselwörter und Fragen aus der Anreicherung; `null` heißt: noch nicht angereichert, eine leere Liste: nichts gefunden
`context`	Umfeld im Dokument, wenn `context` wahr ist
`value`	Trefferwert, auf fünf Stellen gerundet
`paths`	über welche Suchwege der Abschnitt gefunden wurde

Felder ohne Wert fehlen im Treffer.

POST /api/v1/knowledge/ask

Stellt eine Probefrage an die Wissensbasis und liefert eine Antwort mit Belegstellen, wie sie die App unter Antwort prüfen zeigt. Trifft die Frage ein aktives Frage-Antwort-Paar, kommt dessen Antwort im Wortlaut, ohne Modellaufruf. Sonst sind die Grundlage bis zu fünf gefundene Abschnitte und, sobald deren Deckung reicht, bis zu zwölf weitere Abschnitte aus Textbausteinen. Geantwortet wird in der Sprache der Frage, wenn sie sich als Deutsch oder Englisch erkennen lässt. Wie eine Antwort entsteht, erklärt Wissensaufbau und Antworten.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: Drossel knowledge-ask: 30 Anfragen je Minute und Person, siehe Grenzen

Feld	Pflicht	Regel
`question`	ja	höchstens 2000 Zeichen (Ihre Frage)
`language`	nein	`de` oder `en`; gilt nur, wenn sich die Frage nicht sicher als Deutsch oder Englisch erkennen lässt, dann mit der Vorgabe `de`
`source_id`	nein	Kennung einer Quelle

Antwortfeld	Bedeutung
`answered`	ob eine Antwort zustande kam
`text`	Antworttext oder die Absage
`citations`	Belegstellen mit `number`, `chunk_id`, `document`, `heading`, `excerpt`
`path`	`model` für eine formulierte Antwort, `qa_pair` für die Antwort aus einem Frage-Antwort-Paar, `none` für eine Absage
`reason`	Grund der Absage, sonst `null`
`blocks`	Zahl der Abschnitte aus Textbausteinen, die über die Treffer hinaus mitgegeben wurden, siehe Textbausteine; `null` bei einer Absage und bei einer Antwort aus einem Frage-Antwort-Paar
`model`	Kennung des verwendeten Verfahrens

Eine Absage kommt mit diesen Gründen und Texten:

`reason`	Text
`empty_question`	„Bitte stellen Sie eine Frage.“
`nothing_found`, `not_covered`, `model_declined`, `without_citation`	„Dazu steht nichts in der hinterlegten Wissensbasis.“
`no_model`	„Die Antwort ist gerade nicht möglich. Bitte versuchen Sie es später erneut.“

Frage-Antwort-Paare

Ohne source_id landet ein neues Paar in der ältesten Quelle der Art faq; gibt es keine, wird eine angelegt. Ihr Titel folgt locale der angemeldeten Person (Konto und Profil): „Questions and answers“ bei en, sonst „Fragen und Antworten“. Diese neue Quelle zählt gegen die Paketgrenze für Quellen; ist sie erreicht, wird kein Paar angelegt, und die Antwort ist dieselbe wie beim Anlegen einer Quelle. Mit source_id nennen Sie die Quelle selbst.

GET /api/v1/knowledge/qa-pairs

Listet die Paare, sortiert nach position, Anlagezeit und Kennung, höchstens 500; mit source_id nur die einer Quelle. Jedes Paar trägt id, source_id, question, answer, variants, position, is_active und created. Dazu kommt matching: limit nennt, wie viele aktive Paare mit Antwort die Antwortsuche höchstens vergleicht (300, in der Reihenfolge dieser Liste), active, wie viele solche Paare es gibt. Ist active größer als limit, greifen die übrigen nicht. variants nennt die Grenzen der Varianten je Paar: max (20) und length (500 Zeichen je Variante).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

POST /api/v1/knowledge/qa-pairs

Legt ein Paar an. Ein Paar ohne Antwort wird inaktiv gespeichert. Doppelte Varianten fallen weg. Ohne Protokolleintrag wird kein Paar angelegt; die Antwort ist dann 500 mit not_logged. Antwort: 201 mit pair.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

Feld	Pflicht	Regel
`question`	ja	höchstens 500 Zeichen
`answer`	nein	höchstens 5000 Zeichen
`variants`	nein	höchstens 20 weitere Formulierungen zu je höchstens 500 Zeichen
`position`	nein	0 bis 9999
`is_active`	nein	Vorgabe wahr; ohne Antwort falsch
`source_id`	nein	Kennung einer Quelle Ihres Kontos; eine unbekannte ergibt `404` `not_found`

PUT /api/v1/knowledge/qa-pairs/{id}

Ändert ein Paar; alle Felder freiwillig, Regeln wie beim Anlegen. Bleibt die Antwort leer, wird das Paar inaktiv. variants ersetzt die Liste der Varianten, doppelte fallen weg; ohne variants bleibt sie stehen. Ohne Protokolleintrag bleibt das Paar unverändert; die Antwort ist dann 500 mit not_logged. Antwort: pair.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

DELETE /api/v1/knowledge/qa-pairs/{id}

Löscht ein Paar. Ohne Protokolleintrag bleibt es bestehen; die Antwort ist dann 500 mit not_logged. Antwort: {"deleted": true}.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

Prüfsatz und Gewichtung

Der Prüfsatz misst, ob die Suche zu einer Frage das erwartete Dokument findet. Eine Prüfzeile besteht aus einer Frage und dem erwarteten Dokument (Erwartetes Dokument). Ein Lauf fragt nur die eigene Suche, kein Modell und kein fremdes Netz, und läuft darum direkt in der Anfrage. Je Konto sind 100 Prüfzeilen möglich; gesucht wird bis Platz 10.

GET /api/v1/knowledge/documents

Listet die Dokumente, aus denen Sie ein erwartetes Dokument wählen: id, title, source_title; höchstens 500, limit nennt die Zahl.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

GET /api/v1/knowledge/probes

Liefert die Prüfzeilen (probes), die Grenze (limit, 100), die Suchtiefe (depth, 10), die Gewichtung (weights) und den letzten Lauf (run mit probes, hits, mrr, ran_at, oder null).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld einer Prüfzeile	Bedeutung
`id`, `question`, `language`	Kennung, Frage, Sprache
`expected_document_id`, `expected_title`	erwartetes Dokument und sein Titel
`last_rank`	Platz beim letzten Lauf (Platz {n}); `0` heißt gemessen, aber nicht gefunden; `null` heißt nie gemessen
`last_run_at`	Zeitpunkt des letzten Laufs

POST /api/v1/knowledge/probes

Legt eine Prüfzeile an (Prüfzeile anlegen): question (Pflicht, höchstens 500 Zeichen), expected_document_id (Pflicht, Kennung eines Dokuments), language (de oder en, freiwillig). Sind schon 100 Zeilen angelegt, kommt 422 probe_limit; ein unbekanntes Dokument ergibt 404. Ohne Protokolleintrag wird keine Prüfzeile angelegt; die Antwort ist dann 500 mit not_logged. Antwort: 201 mit probe.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

DELETE /api/v1/knowledge/probes/{id}

Löscht eine Prüfzeile. Ohne Protokolleintrag bleibt sie bestehen; die Antwort ist dann 500 mit not_logged. Antwort: {"deleted": true}.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

POST /api/v1/knowledge/probes/run

Misst alle Prüfzeilen (Messen) und liefert run mit probes, hits (Gefunden), mrr und ran_at sowie die aktualisierten Zeilen. mrr ist die Trefferqualität: der Mittelwert aus eins geteilt durch den Platz des erwarteten Dokuments, auf drei Stellen gerundet; ein nicht gefundenes Dokument zählt 0. Ohne Prüfzeilen kommt 422 no_probe.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel knowledge-probes: 6 Anfragen je Minute und Person, siehe Grenzen

Gewichtung

Zwei Stellschrauben bestimmen, wie die Suche Treffer ordnet: der Titelfaktor (title_factor, 1,0 bis 5,0, Vorgabe 1,8) hebt Treffer im Dokumenttitel an, das Schlüsselwortgewicht (keyword_tf, 0 bis 10, Vorgabe 3) Treffer in den angereicherten Schlüsselwörtern. weights enthält title_factor und keyword_tf (geltend), set (selbst eingetragen), default (Vorgabe) und bounds (Grenzen).

PUT /api/v1/knowledge/weights

Speichert die Gewichtung (Gewichtung speichern). Beide Felder sind freiwillig; null setzt auf die Vorgabe zurück. title_factor wird auf zwei Stellen gerundet. Ohne Protokolleintrag bleibt die Gewichtung unverändert; die Antwort ist dann 500 mit not_logged. Antwort: weights.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

POST /api/v1/knowledge/probes/tune

Probiert an den ältesten höchstens 20 Prüfzeilen des Prüfsatzes zuerst jeden Titelfaktor (1,0; 1,4; 1,8; 2,2; 2,6; 3,0) beim geltenden Schlüsselwortgewicht durch, dann jedes Schlüsselwortgewicht (0; 1; 2; 3; 5; 8) beim besten Titelfaktor (Abstimmen). Ohne apply wird nur gemessen. Mit "apply": true (Bestwert übernehmen) wird der beste Kandidat übernommen, aber nur, wenn er den geltenden Stand echt schlägt; bei Gleichstand bleibt alles, wie es ist (Kein Kandidat ist besser als die geltende Einstellung.). Kommt der Protokolleintrag zum Übernehmen nicht zustande, bleibt die geltende Gewichtung; die Antwort ist dann 500 mit not_logged. Antwort: tuning mit rows_used, rows_total, current, best, candidates, dazu applied und weights.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel knowledge-tune: 2 Anfragen je Minute und Person, siehe Grenzen

Einrichtung aus der Website

Die Einrichtung liest Ihre Website, schlägt daraus einen Assistenten vor und legt ihn nach Ihrer Auswahl an. In der App heißt das Einrichtung (app.xicbot.de/einrichtung); den Ablauf beschreibt Einrichtung. Das Anlegen eines Durchgangs zählt gegen dieselben Grenzen wie eine Wissensquelle, denn es legt eine an.

`status`	Bedeutung
`liest`	die Website wird gelesen
`schlaegt_vor`	der Vorschlag entsteht (Der Vorschlag entsteht.)
`entscheidung`	der Vorschlag liegt bereit und wartet auf Ihre Auswahl
`uebernommen`	der Assistent ist angelegt (Der Assistent ist angelegt.)
`fehler`	der Durchgang ist gescheitert; `hinweis` nennt den Grund (Der Durchgang ist gescheitert)
`leer`	aus der Website entstand kein Inhalt; `hinweis` nennt den Grund (Kein Vorschlag)

GET /api/v1/setup/runs

Listet die letzten 20 Durchgänge, die neuesten zuerst (Frühere Durchgänge). Antwort: runs.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld eines Durchgangs	Bedeutung
`id`, `website`, `status`	Kennung, gelesene Adresse, Stand
`language`	`de` oder `en`: in dieser Sprache entstehen Vorschlag und erste Fassung; ohne gespeicherte Angabe `de`
`vorschlag`	der Vorschlag mit `zweck` und `rolle` (je `text` und `fundstelle`), `name`, `tonfall`, `erster_satz`, `fragen` (je `frage`, `antwort`, `fundstelle`), `schweigethemen`, `luecken` und `removed`: was aus dem Vorschlag entfernt wurde (Aus dem Vorschlag entfernt), je Eintrag mit `kind` `promise` und dem Wort in `word`, `no_source` und dem Feld in `field` oder `question_no_source` und der Frage in `question`
`angenommen`	Ihre übernommene Auswahl
`hinweis`	bei `fehler` und `leer` der Grund als Kennung: `website_unreadable` (bei `leer` gegebenenfalls mit dem Grund der Aufnahme nach einem Doppelpunkt), `no_text`, `too_little_text:` mit der Zahl der gelesenen Zeichen, `model_unavailable`, `budget_exhausted`, `model_failed`, `reply_unreadable` oder `run_aborted`; sonst `null`. Die App zeigt dazu einen Satz in der Sprache der Oberfläche.
`assistent_id`	der angelegte Assistent
`erstellt`, `beendet`	Beginn und Ende
`dismissed_at`	Zeitpunkt, zu dem der Durchgang verworfen wurde, sonst `null`; ein verworfener Durchgang wird in der App beim Öffnen nicht mehr von selbst gezeigt
`taboo_limit`	wie viele `schweigethemen` die Übernahme annimmt (der Deckel der Tabuliste)

POST /api/v1/setup/runs

Startet einen Durchgang mit website (Pflicht, Adresse mit http oder https, höchstens 255 Zeichen; Adresse Ihrer Website, Knopf Website lesen) und optional language (de oder en, Sprache des Assistenten; ohne Angabe die locale Ihres Kontos, ein anderer Wert ergibt 422). Die Website wird als Wissensquelle angelegt; diese Quelle bleibt Ihnen erhalten, auch wenn Sie den Vorschlag nicht übernehmen. Läuft schon ein Durchgang (Stand liest oder schlaegt_vor), kommt 409 run_in_progress mit diesem Durchgang in run. Ein offener Durchgang, dessen Verarbeitung nicht mehr läuft und der seit über einer Minute unverändert ist, wird vor dem Start und vor der Liste der Durchgänge als fehler mit dem Hinweis run_aborted beendet; er hält dann keinen neuen Start auf. Antwort: 201 mit run.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher; Paketgrenzen für Quellen, Dokumente und Abschnitte
Begrenzung: Drossel knowledge-sources: 20 Anfragen je Minute und Person, siehe Grenzen

GET /api/v1/setup/runs/{id}

Liefert einen Durchgang (run). Damit fragen Sie den Stand ab, bis er entscheidung, fehler oder leer erreicht.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

POST /api/v1/setup/runs/{id}/accept

Übernimmt Ihre Auswahl aus dem Vorschlag und legt einen Assistenten als Entwurf an (Assistenten anlegen). Nur im Stand entscheidung möglich, sonst 409 not_ready mit dem aktuellen status; ein verworfener Durchgang lässt sich übernehmen, dismissed_at wird dabei geleert. Muss für die Fragen erst eine Quelle der Art faq entstehen und ist die Paketgrenze für Quellen erreicht, endet die Übernahme ohne Assistenten mit derselben Antwort wie das Anlegen einer Quelle (402 plan_limit_reached, bei nicht messbarem Verbrauch 503 plan_limit_unmeasured). Ohne Protokolleintrag für den Assistenten oder die neue Quelle bleibt die ganze Übernahme aus; die Antwort ist dann 500 mit not_logged. Antwort: 201 mit dem Durchgang (run) und assistant (id, name, slug, status).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher; Paketgrenze für Assistenten
Begrenzung: keine

Feld	Regel	In der App	Wird zu
`name`	Pflicht, höchstens 80 Zeichen	Name des Assistenten	Name
`zweck`	höchstens 600 Zeichen	Was Ihr Betrieb macht	Themengrenze der ersten Fassung
`rolle`	höchstens 200 Zeichen	Wen der Assistent vertritt	Rolle der ersten Fassung
`tone`	`neutral`, `friendly`, `concise` oder `detailed`	Wie er spricht mit sachlich, freundlich, knapp und ausführlich, vorgewählt sachlich; der Tonfall aus dem Vorschlag steht nur als Hinweis darunter	Ton der ersten Fassung, ohne Angabe sachlich; der Satz `tonfall` aus dem Vorschlag wird nicht übernommen
`erster_satz`	höchstens 300 Zeichen	Sein erster Satz	Begrüßung
`fragen`	höchstens 50, je `frage` (500) und `antwort` (4000) als Pflicht	Fragen und Antworten	Paare in der ältesten Quelle der Art `faq`, sonst in einer neuen Quelle der Art `faq`, deren Titel `locale` der übernehmenden Person folgt („Questions and answers“ bei `en`, sonst „Fragen und Antworten“); Fragen, die es im Konto schon gibt (gleich bis auf Groß- und Kleinschreibung), werden übersprungen, und doppelte Fragen der Auswahl zählen einmal
`schweigethemen`	höchstens so viele wie `taboo_limit` (8) zu je 120 Zeichen; mehr oder länger ergibt `422`	Themen, zu denen er schweigt	Tabus der ersten Fassung, doppelte entfallen

POST /api/v1/setup/runs/{id}/discard

Verwirft einen Durchgang (Verwerfen): dismissed_at wird gesetzt, ein zweites Verwerfen behält den ersten Zeitpunkt. Gelöscht wird nichts; der Durchgang bleibt in der Liste und ein verworfener Vorschlag lässt sich weiter übernehmen. Nur in den Ständen entscheidung, leer und fehler, sonst 409 not_discardable mit dem aktuellen status; unbekannte Kennung 404 not_found. Antwort: 200 mit run.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

Die erste Fassung eines so angelegten Assistenten antwortet nur aus der Wissensbasis und hat die Sprache des Durchgangs (language); Übergaberegel und Notfallantwort kommen aus der Grundvorlage dieser Sprache, ebenso Rolle, Themengrenze und Begrüßung, wo Ihre Auswahl sie leer lässt.

Assistenten

In der App liegen Assistenten unter Assistenten (app.xicbot.de/assistenten). Was die einzelnen Bausteine fachlich bewirken, erklärt Assistenten. Ein Assistent hat Kopfdaten (Name, Status, Notfallantwort, Widget-Einstellungen) und Fassungen mit den Bausteinen, die die App unter Bausteine der Antwort zeigt. Kopfdaten ändern Sie direkt; eine Änderung an den Bausteinen legt eine neue Fassung an und überschreibt die alte nicht.

GET /api/v1/assistants/templates

Listet die Vorlagen (Vorlage), gruppiert nach Branchen und Aufgaben. Mit ?language=en kommen die englischen Texte, Vorgabe ist de. Antwort: templates.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

GET /api/v1/assistants

Listet die Assistenten nach Namen, höchstens 200, jeweils mit ihrer aktiven Fassung. Antwort: assistants.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

GET /api/v1/assistants/{id}

Liefert einen Assistenten (assistant) und seine Fassungen (versions), die neuesten zuerst, höchstens 50.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld von `assistant`	Bedeutung
`id`, `name`, `slug`, `template`	Kennung, Name, Kurzname, Vorlage
`status`	`draft` (Entwurf), `active` (aktiv) oder `paused` (pausiert)
`fallback_reply`	Notfallantwort
`version`	die aktive Fassung
`widget`	Widget-Einstellungen: `is_active`, `title`, `color`, `position`, `vertical`, `offset_x`, `offset_y`, `width`, `height`, `scale`, `radius`, `avatar`, `outreach_rules`, `domains`, `consent`, `consent_text`, `attachments`, `base_url` und `key`, der öffentliche Schlüssel (Öffentlicher Schlüssel)

POST /api/v1/assistants

Legt einen Assistenten als Entwurf an (Neuer Assistent, Assistent anlegen), zusammen mit Fassung 1. Felder: name (Pflicht, höchstens 120 Zeichen), template (Kennung einer Vorlage, höchstens 40 Zeichen; ohne Angabe ohne Vorlage), language (de oder en). Der Kurzname entsteht aus dem Namen, höchstens 50 Zeichen; ist er im Konto schon vergeben, wird -2, -3 und so weiter angehängt. Die erste Fassung antwortet nur aus der Wissensbasis. Eine unbekannte Vorlage ergibt 422 unknown_template. Ohne Protokolleintrag entsteht weder Assistent noch Fassung; die Antwort ist dann 500 mit not_logged. Antwort: 201 mit assistant.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher; Paketgrenze für Assistenten
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

PUT /api/v1/assistants/{id}

Ändert die Kopfdaten; alle Felder sind freiwillig. Die Widget-Felder beschreibt Widget-Einstellungen im Einzelnen. Antwort: assistant.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

Feld	Regel
`name`	höchstens 120 Zeichen
`status`	`draft`, `active` oder `paused` (Status)
`fallback_reply`	5 bis 500 Zeichen (Notfallantwort)
`widget_enabled`	wahr oder falsch
`widget_title`	höchstens 80 Zeichen
`widget_color`	Farbe als `#rrggbb`
`widget_position`, `widget_vertical`	`right` oder `left`; `bottom` oder `top`
`widget_offset_x`, `widget_offset_y`	0 bis 400
`widget_width`, `widget_height`	280 bis 720; 320 bis 1200
`widget_scale`, `widget_radius`	80 bis 150; 0 bis 40
`widget_avatar`	Bild als PNG, JPEG oder WebP in einer `data:`-Adresse; Fehler `widget_avatar_format`, `widget_avatar_too_large`, `widget_avatar_not_an_image`
`widget_domains`	höchstens 500 Zeichen
`widget_consent`, `widget_consent_text`	wahr oder falsch; höchstens 500 Zeichen
`widget_outreach_rules`, `widget_attachments`	siehe Ansprache und Widget-Einstellungen
`widget_base_url`	höchstens 200 Zeichen, absolute Adresse mit `http` oder `https`, ohne Abfrageteil und Sprungmarke; ein Schrägstrich am Ende wird entfernt; Fehler `widget_base_url_not_absolute`, `widget_base_url_scheme`, `widget_base_url_has_query`

Fassungen

POST /api/v1/assistants/{id}/version

Veröffentlicht eine neue Fassung (Neue Fassung veröffentlichen). Sie bekommt die nächsthöhere Nummer und wird sofort aktiv. Die Pflichtfelder der Tabelle senden Sie jedes Mal mit. taboos, facts, master_data, escalation_topics, escalation_threshold, escalation_words und handoff_email übernimmt sie aus der aktiven Fassung, wenn Sie sie nicht senden; knowledge_only steht ohne Angabe auf wahr. Ohne Protokolleintrag entsteht keine neue Fassung, und die bisher aktive bleibt aktiv; die Antwort ist dann 500 mit not_logged. Antwort: 201 mit version.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

Feld	Pflicht	Regel	In der App
`persona`	ja	höchstens 200 Zeichen	Rolle
`tone`	ja	`neutral`, `friendly`, `concise` oder `detailed`	Ton: sachlich, freundlich, knapp, ausführlich
`topic_scope`	ja	höchstens 600 Zeichen	Themengrenze
`handoff_rule`	ja	höchstens 400 Zeichen	Übergaberegel
`greeting`	ja	höchstens 500 Zeichen	Begrüßung
`language`	ja	`de` oder `en`	–
`knowledge_only`	nein	wahr oder falsch, Vorgabe wahr	Nur aus der Wissensbasis antworten
`taboos`	nein	höchstens 8 Einträge zu je 120 Zeichen	Tabuthemen
`facts`	nein	höchstens 12 Einträge zu je 200 Zeichen	feste Angaben
`master_data`	nein	siehe Stammdaten	Stammdaten
`escalation_topics`	nein	Kennungen bekannter Themen; unbekannte ergeben `422` `unknown_topic` mit `topics`	Übergabethemen
`escalation_threshold`	nein	1 bis 20, Vorgabe 3	Schwelle der Übergabe
`escalation_words`	nein	je Thema höchstens 20 Wörter mit 3 bis 40 Zeichen	Signalwörter
`handoff_email`	nein	E-Mail-Adresse, höchstens 190 Zeichen; ändern darf nur der Inhaber	Übergabeadresse

Wer die Übergabeadresse ändert, ohne Inhaber zu sein, bekommt 403 role_too_low mit required owner und field handoff_email. Wer die bisherige Adresse unverändert mitschickt, ändert nichts und wird nicht abgewiesen.

Stammdaten

Teil von `master_data`	Regel
`opening_hours`	höchstens 14 Einträge mit `day` (`mon` bis `sun`), `from`, `to` (Uhrzeit `HH:MM`)
`locations`	höchstens 5 mit `name` (Pflicht), `street`, `postal_code`, `city`
`service_area`	höchstens 20 Einträge zu je 80 Zeichen
`contacts`	höchstens 5 mit `role` (Pflicht), `name`, `email`, `phone`
`price_ranges`	höchstens 10 mit `item`, `from_cents` (Pflicht, ab 0), `to_cents`, `unit`, `currency` (drei Buchstaben)

Weitere Felder in master_data ergeben 422 unknown_master_field mit fields.

Die Antwort einer Fassung (version) enthält neben diesen Feldern id, number, restored_from, published_at und die Grenzen, die die App zum Ausfüllen braucht, etwa taboo_limit, fact_limit, master_data_limits, escalation_threshold_min und escalation_threshold_max.

POST /api/v1/assistants/{id}/versions/{number}/restore

Holt eine frühere Fassung zurück, indem eine neue Fassung mit ihrem Inhalt angelegt wird; restored_from nennt die Vorlage. Die Zwischenfassungen bleiben erhalten. Eine unbekannte Nummer ergibt 404 version_not_found, die bereits aktive 422 already_active. Enthält die alte Fassung eine andere Übergabeadresse, gilt die Inhaberregel wie oben. Ohne Protokolleintrag entsteht keine neue Fassung, und die bisher aktive bleibt aktiv; die Antwort ist dann 500 mit not_logged. Antwort: 201 mit restored, from und version.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

Löschen, Einbaucode und Schlüssel

DELETE /api/v1/assistants/{id}

Löscht einen Assistenten mit seinen Fassungen und allen seinen Gesprächen. Zuerst wird die Protokollzeile geschrieben; gelingt sie nicht, bleibt alles stehen und die Antwort ist 500 mit not_logged. Antwort: {"deleted": true}.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Verwaltung oder höher
Begrenzung: keine

GET /api/v1/assistants/{id}/embed

Liefert den Einbaucode und seine Bestandteile. Wie Sie ihn auf Ihrer Seite einsetzen, beschreiben Widget einbauen und Script-Attribute.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Antwortfeld	Bedeutung
`snippet`	der Einbaucode
`url`, `api`, `key`	Adresse der Einbaudatei, Adresse der Schnittstelle, öffentlicher Schlüssel
`base`, `snippet_first_party`	eigene Basisadresse und der Einbaucode dafür, wenn `widget_base_url` gesetzt ist
`sri`, `reason`	Prüfsumme der ausgelieferten Einbaudatei oder, wenn sie fehlt, der Grund (`file_missing`, `file_unreadable`); beide gehen nicht in den Einbaucode ein
`seen_at`, `seen_host`	wann und auf welcher Seite der Einbau zuletzt gemeldet wurde

Quelltext html

<script src="{url}/einbetten.js" data-xicbot="{key}" data-api="{api}" defer></script>

Ist die Einwilligung am Assistenten eingeschaltet, trägt der Einbaucode zusätzlich data-einwilligung="erforderlich".

POST /api/v1/assistants/{id}/key

Tauscht den öffentlichen Schlüssel aus (Neuen Schlüssel erzeugen). Danach lädt kein bisheriger Einbau mehr; die App meldet: *Neuer Schlüssel ist aktiv. Bitte den Einbaucode überall austauschen.* Zuerst wird die Protokollzeile geschrieben; gelingt sie nicht, bleibt der bisherige Schlüssel gültig und die Antwort ist 500 mit not_logged. Ein unbekannter Assistent ergibt 404 not_found. Antwort: key, der neue Schlüssel aus 32 Hexadezimalzeichen.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Verwaltung oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

GET /api/v1/usage

Zeigt das Kontingent des laufenden Monats (Kontingent in diesem Monat). Ab 80 Prozent Verbrauch steht level auf warning, bei erschöpftem Kontingent auf exhausted, sonst auf ok. Ohne Konto kommt 403 no_tenant. Die Kontingente der Pakete stehen unter Pakete und Kontingente.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld in `usage`	Bedeutung
`month`	Monat
`used`, `budget`, `remaining`	verbraucht, verfügbar, übrig
`messages`	Zahl der Nachrichten
`share`	Anteil des Verbrauchs
`warn_at`	Warnschwelle
`warning`, `throttled`, `exhausted`	Warnung, gedrosselt, erschöpft
`reply_tokens`, `tool_rounds`	Obergrenzen je Antwort, ab der Warnschwelle niedriger
`level`	`ok`, `warning` oder `exhausted`

Abnahmeprüfungen

Eine Abnahme stellt der aktiven Fassung eines Assistenten feste Prüffragen und vergleicht die Antworten mit einer Musterantwort. Den Ablauf in der App beschreibt Probieren und abnehmen. Je Assistent sind 50 Prüffragen möglich.

GET /api/v1/assistants/{id}/checks

Listet die Prüffragen (checks), jede mit last_result und last_run_at, dazu limit (50), terms_limit (10 Begriffe je Liste) und den letzten Lauf (last_run).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

POST /api/v1/assistants/{id}/checks

Legt eine Prüffrage an (Prüffrage anlegen); sie wird hinten angestellt. Sind schon 50 angelegt, kommt 422 limit_reached. Antwort: 201 mit check.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

Feld	Pflicht beim Anlegen	Regel	In der App
`question`	ja	3 bis 500 Zeichen	Frage
`expected`	ja	3 bis 4000 Zeichen	Musterantwort
`must_contain`	nein	höchstens 10 Begriffe zu je 80 Zeichen	Muss enthalten
`must_not_contain`	nein	höchstens 10 Begriffe zu je 80 Zeichen	Darf nicht enthalten
`min_overlap`	nein	0 bis 1, Vorgabe 0,5	Mindestdeckung
`language`	nein	`de` oder `en`	–
`position`	nein	0 bis 9999	–
`is_active`	nein	wahr oder falsch	Läuft mit

PUT /api/v1/assistants/{id}/checks/{check}

Ändert eine Prüffrage; alle Felder sind freiwillig. Antwort: check.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

DELETE /api/v1/assistants/{id}/checks/{check}

Löscht eine Prüffrage. Antwort: {"deleted": true}.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

POST /api/v1/assistants/{id}/checks/run

Startet eine Abnahme (Abnahme starten) mit allen Prüffragen, die mitlaufen. Der Lauf arbeitet im Hintergrund; wartet oder läuft schon einer, wird er weiterverwendet. Ohne aktive Fassung kommt 422 no_version, ohne mitlaufende Prüffrage 422 no_check, bei erschöpftem Kontingent 422 quota_exhausted. Antwort: 202 mit run.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

GET /api/v1/assistants/{id}/check-runs

Listet die letzten 30 Läufe, die neuesten zuerst. Antwort: runs.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

GET /api/v1/assistants/{id}/check-runs/{run}

Liefert einen Lauf (run) mit den Ergebnissen je Prüffrage (results).

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld	Bedeutung
`status`	`pending` (eingereiht), `running` (läuft), `done` (fertig), `failed` (abgebrochen)
`checks`, `passed`, `failed`, `errored`	Zahl der Prüffragen, Bestanden, Durchgefallen, Nicht messbar
`rate`	Quote: bestanden geteilt durch bestanden plus durchgefallen, auf drei Stellen; `null`, solange nichts gewertet ist
`version_id`	die geprüfte Fassung
`started_at`, `finished_at`, `duration_ms`, `reason`, `created_at`	Zeiten, Dauer und Abbruchgrund

Ein Ergebnis (result) ist pass (bestanden), fail (durchgefallen) oder error (nicht messbar). Bestanden ist eine Antwort, wenn jeder Begriff aus Muss enthalten vorkommt, keiner aus Darf nicht enthalten und die Deckung mit der Musterantwort die Mindestdeckung erreicht; ist die Mindestdeckung 0 oder die Deckung nicht messbar, entfällt der letzte Teil. Groß- und Kleinschreibung zählen nicht. Jedes Ergebnis nennt answer, missing, forbidden, overlap, reason, conversation_id und duration_ms.

Werkzeuge

Werkzeuge geben einem Assistenten Handlungen, etwa eine Anfrage aufnehmen oder in einem Katalog suchen. Was jede Bauform fachlich tut, erklären Werkzeuge und Werkzeugbausatz. Anlegen, Ändern und Löschen verlangt die Rolle Bearbeiten; Adresse der Schnittstelle, Zugangsmarke und Mindestrolle verlangen darüber hinaus die Rolle Verwaltung.

Bauform (`type`)	Art	Vorgabe der Freigabe
`lead`	schreibend	`confirm`
`appointment`	schreibend	`confirm`
`handoff`	schreibend	`confirm`
`product_search`	lesend	`automatic`
`cart`	nicht umkehrbar	`confirm`
`http`	lesend	`confirm`
`form_fill`	schreibend	`confirm`

Dazu kommen die Bauformen aus dem Werkzeugbausatz; ihre Art und die Vorgabe der Freigabe bringt jede selbst mit. Nur lesende Werkzeuge dürfen auf automatic stehen; bei allen anderen setzt die Schnittstelle confirm, gleich was Sie senden.

GET /api/v1/assistants/{assistant}/tools

Listet die Werkzeuge eines Assistenten.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, jede Rolle
Begrenzung: keine

Feld eines Werkzeugs	Bedeutung
`id`, `key`, `title`, `description`	Kennung, Schlüssel, Bezeichnung, Wann soll der Assistent es benutzen?
`adapter`, `kind`	Bauform und Art
`approval`, `min_role`	Freigabe, Mindestrolle
`required_fields`, `required_effective`	eingetragene und tatsächlich geltende Pflichtangaben
`schema`	Felder der Eingabe
`settings`	Einstellungen; eine gesetzte Zugangsmarke erscheint als `__set__`
`is_active`	Aktiv
`timezone_valid`	bei der Bauform `appointment`, ob die Zeitzone in `settings` gilt (`true` oder `false`), nach demselben Urteil wie beim Speichern; bei allen anderen Bauformen `null`

POST /api/v1/assistants/{assistant}/tools

Legt ein Werkzeug an (Werkzeug hinzufügen). Antwort: 201 mit tool.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

Feld	Pflicht	Regel
`type`	ja	eine der Bauformen oben oder aus dem Werkzeugbausatz (Bauform)
`key`	ja	Kleinbuchstabe am Anfang, dann Kleinbuchstaben, Ziffern oder `_`, 3 bis 64 Zeichen; je Assistent eindeutig
`title`	ja	höchstens 120 Zeichen
`description`	ja	höchstens 600 Zeichen
`approval`	nein	`automatic` oder `confirm`
`min_role`	nein	`public`, `member`, `admin` oder `owner`; Vorgabe `public`
`required_fields`	nein	höchstens 20 Namen zu je 40 Zeichen
`settings`	nein	Einstellungen der Bauform, bei `http` mit Adresse und Zugangsmarke
`schema`	nein	eigene Eingabefelder, siehe unten
`is_active`	nein	wahr oder falsch

Status	Kennung	Bedeutung
422	`key_taken`	Diesen Schlüssel gibt es bei diesem Assistenten schon.
422	`shape_unknown`	unbekannte Bauform
422	`url_required`	Bauform `http` ohne Adresse
422	`url_unreadable`, `scheme_not_allowed`, `name_unresolvable`, `target_not_allowed`	die Adresse besteht die Adressprüfung nicht
422	Codes der Einstellungsprüfung, etwa `appointment_timezone_invalid`	die Einstellungen der Bauform `appointment`, `cart` oder `form_fill` bestehen die Prüfung nicht; `appointment_timezone_invalid` heißt: unbekannte Zeitzone in `settings`, eine leere Angabe gilt als Vorgabe
403	`role_too_low` mit `field` `min_role`	die gewählte Mindestrolle liegt über der eigenen (Zur Wahl stehen die Stufen bis zur eigenen Rolle.)
403	`role_too_low` mit `required` `admin` und `field`	Adresse, Zugangsmarke oder Mindestrolle geändert ohne Rolle Verwaltung
402	`plan_feature_missing`	die Bauform gehört nicht zum Paket; `feature`, `plan`, `plan_name` und `available_in` nennen Merkmal, Paket und die Pakete, die es enthalten

Eigene Eingabefelder

Bei der Bauform http legen Sie unter Felder der Eingabe fest, welche Angaben der Assistent übergibt. schema ist eine Liste von Feldern mit Feldname, Typ, Beschreibung und Pflicht. Es gelten diese Regeln: höchstens 20 Felder; ein Name beginnt mit einem Kleinbuchstaben und hat danach bis zu 39 Kleinbuchstaben, Ziffern oder _; die Namen tenant_id, mandant, mandant_id und konto_id sind gesperrt; Typen sind string, integer, number und boolean, jeder andere wird zu string; die Beschreibung wird auf 200 Zeichen gekürzt und ist ohne Angabe der Feldname. Ein Schema, das diese Regeln verletzt, lehnt der Dienst mit 422 ab: schema_field_name_invalid oder schema_field_name_reserved mit dem Feldnamen unter field, schema_fields_too_many mit max, schema_required_unknown für eine Pflichtangabe ohne Feld. Gespeichert wird dann nichts.

PUT /api/v1/tools/{id}

Ändert ein Werkzeug. Die Bauform bleibt, wie sie ist; title und description sind wieder Pflicht, die übrigen Felder freiwillig. Senden Sie als Zugangsmarke __set__, bleibt die gespeicherte erhalten. Antwort: tool.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: Drossel assistants: 30 Anfragen je Minute und Person, siehe Grenzen

DELETE /api/v1/tools/{id}

Löscht ein Werkzeug. Gelingt die Protokollzeile nicht, bleibt es stehen und die Antwort ist 500 mit not_logged. Antwort: {"deleted": true}.

Anmeldung: Angemeldet, bestätigte E-Mail-Adresse, Rolle Bearbeiten oder höher
Begrenzung: keine

Häufige Fragen

Warum kommt beim Anlegen einer Website-Quelle 202 statt 201?

Eine Website wird im Hintergrund gelesen. Die Antwort enthält den Auftrag; seinen Stand fragen Sie mit GET /api/v1/knowledge/jobs/{id} ab, den der Quelle mit GET /api/v1/knowledge/sources/{id}.

Wie prüfe ich, ob die Suche das richtige Dokument findet?

Legen Sie Prüfzeilen mit Frage und erwartetem Dokument an und messen Sie mit POST /api/v1/knowledge/probes/run. POST /api/v1/knowledge/probes/tune probiert danach andere Gewichtungen und übernimmt mit "apply": true nur einen echten Gewinn.

Verliere ich neuere Fassungen, wenn ich zurückhole?

Bei einer Wissensquelle ja: Fassungen über der zurückgeholten werden verworfen. Bei einem Assistenten nein: das Zurückholen legt eine neue Fassung mit dem alten Inhalt an.

Warum bekomme ich 403 beim Ändern der Übergabeadresse?

Die Übergabeadresse darf nur der Inhaber des Kontos ändern. Die Antwort nennt required owner und field handoff_email.

Was passiert mit eingebauten Seiten, wenn ich den Schlüssel tausche?

Sie laden das Widget nicht mehr, bis dort der neue Einbaucode steht. Den holen Sie mit GET /api/v1/assistants/{id}/embed.

Selbst fragen, Assistent dieser Website

Automatischer Assistent