# Knowledge Base API

Ihre Wissensdatenbank ist die Grundlage, aus der die KI liest. Sie besteht aus zwei Teilen, die beide auf dieser Seite behandelt werden:

- **Wissensquellen** (`/kb-sources`) — die Webseiten und hochgeladenen Dokumente, die Sie der Plattform zur Verfügung stellen. Jede Quelle wird gelesen, in Abschnitte unterteilt und in FAQs umgewandelt, die Ihre KI beantworten kann.
- **Wissensgruppen** (`/kb-groups`) — benannte Bündel von FAQs, die Sie mit einem einzigen Aufruf auf einen Agenten oder eine Kampagne anwenden können, sodass bereits kuratiertes Wissen für den nächsten Agenten, den Sie erstellen, wiederverwendet werden kann.

Die FAQs, die eine Quelle erzeugt, landen in derselben Bibliothek wie die von Ihnen manuell erstellten. Sobald ein Import abgeschlossen ist, können Sie diese mit der [FAQs API](faqs.md) lesen, bearbeiten und verknüpfen.

Alle unten aufgeführten Endpunkte beziehen sich auf die Basis-URL `https://api.youraiconnector.com/v1`. Jede Anfrage muss authentifiziert sein – siehe [API-Zugriff](../integrations/api-access.md) und [Authentifizierung](authentication.md). Der API-Zugriff ist eine kostenpflichtige Funktion; ohne diesen werden Anfragen mit einem `403` abgelehnt.


> **Der Import kostet Credits.** Das Lesen einer Seite oder eines Dokuments und das Erstellen von FAQs daraus verbraucht Credits, ungefähr proportional zur Inhaltsmenge. Verwenden Sie [Import schätzen](#estimate-what-an-import-will-cost), bevor Sie einen großen Crawl starten.

---

## Funktionsweise eines Imports

Der Import ist ein Hintergrundprozess und kein Vorgang, der sofort abgeschlossen ist. Jeder Import-Endpunkt antwortet sofort mit einer `source_id`, und Sie fragen diese Quelle ab, bis sie fertig ist:

1. **Import starten** — `POST /kb-sources/url` (eine Seite), `POST /kb-sources/file` (ein hochgeladenes Dokument) oder `POST /kb-sources/bulk-import` (bis zu 100 Seiten). Sie erhalten eine Quellen-ID und eine `status: "queued"` zurück.
2. **Abfragen** — `GET /kb-sources/{sourceId}`, bis `status` nicht mehr `queued` oder `processing` ist.
3. **FAQs lesen** — wenn der Status `ready` lautet, befinden sich die erzeugten Einträge in Ihrer FAQ-Bibliothek: `GET /faqs`.

Jede Quelle meldet einen dieser Statuswerte:

| Status | Bedeutung |
|---|---|
| `queued` | Wartet darauf, gelesen zu werden. Es wurden noch keine Kosten berechnet. |
| `processing` | Wird gerade gelesen und in FAQs umgewandelt. |
| `ready` | Abgeschlossen. Die FAQs befinden sich in Ihrer Bibliothek. |
| `failed` | Konnte nicht importiert werden. `error_message` gibt den Grund an. |
| `cancelled` | Gestoppt, bevor der Lesevorgang abgeschlossen war (siehe [Import stoppen](#stop-an-import)). |
| `paused` | Gestoppt, weil Ihr eigener KI-Schlüssel während des Imports fehlgeschlagen ist (siehe [Pausierten Import fortsetzen](#resume-a-paused-import)). |
| `deleting` | Eine Massenlöschung wird gerade verarbeitet. |
| `unknown` | Der Datensatz hat keinen Status. Behandeln Sie ihn als nicht bereit. |

> **Beim Import zuweisen.** Übergeben Sie `autoLinkToAgentId` an einem beliebigen Import-Endpunkt, und die Quelle – sowie alle daraus erzeugten FAQs – werden mit demselben Aufruf dem Wissen des Agenten hinzugefügt, ohne dass ein weiterer Verknüpfungsschritt erforderlich ist. `autoLinkToCampaignId` bewirkt dasselbe für eine klassische Kampagne. Die Verknüpfung erfolgt nach dem Best-Effort-Prinzip: Eine ID, die nicht existiert oder zu einem anderen Konto gehört, wird stillschweigend übersprungen und der Import läuft weiter. Überprüfen Sie die Verknüpfung daher, indem Sie den Agenten erneut abrufen.

---

## Webseite importieren

`POST /kb-sources/url`

Fügt Ihrer Wissensdatenbank eine Webseite hinzu.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `url` | Ja | Vollständige `http`- oder `https`-Adresse der Seite. |
| `autoLinkToAgentId` | Nein | ID eines KI-Agenten, dem die importierte Quelle zugeordnet werden soll. |
| `autoLinkToCampaignId` | Nein | Veraltet. ID einer Kampagne, der die importierte Quelle zugeordnet werden soll. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")
```

**Antwort** — `202 Accepted`

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}
```

Fragen Sie `source_id` mit [Quelle prüfen](#check-a-source) ab, bis der Status `ready` oder `failed` lautet.

Wenn dieselbe Seite bereits in Ihrer Wissensdatenbank vorhanden ist, wird nichts Neues in die Warteschlange gestellt und Sie erhalten stattdessen eine `200` — und falls Sie eine automatische Verknüpfung angefordert haben, wird die bestehende Quelle ohnehin für Sie verknüpft:

```json
{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}
```

Ein fehlender `url` oder eine Angabe, die keine gültige `http`/`https`-Adresse ist, führt zu `400`.

---

## Hochgeladenes Dokument importieren

`POST /kb-sources/file`

Fügt ein Dokument, das sich **bereits im Dateispeicher Ihres Kontos** befindet, als Wissensquelle hinzu. Unterstützte Formate: PDF, DOCX, TXT, MD, CSV und XLSX.

> **Dieser Endpunkt überträgt die Datei nicht.** Es gibt keinen Multipart-Upload, keinen Base64-Body und keinen Download von einer URL: Sie senden den Speicherort einer Datei, die bereits existiert, und diese muss sich in Ihrem eigenen Upload-Ordner befinden (`storage_path` muss mit `users/{your user id}/uploads/` beginnen), andernfalls wird die Anfrage mit `403` abgelehnt. Das Dashboard legt Dateien dort ab, wenn Sie sie hineinziehen. Wenn Sie keine Möglichkeit haben, eine Datei dort abzulegen, importieren Sie stattdessen eine Webseite über [Webseite importieren](#import-a-web-page).

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `storage_path` | Ja | Speicherort der hochgeladenen Datei. Muss mit `users/{your user id}/uploads/` beginnen. |
| `filename` | Ja | Ursprünglicher Dateiname inklusive Erweiterung – daran wird der Dateityp erkannt. |
| `mime_type` | Ja | MIME-Typ der Datei, zum Beispiel `application/pdf`. |
| `autoLinkToAgentId` | Nein | ID eines KI-Agenten, dem das Dokument zugeordnet werden soll. |
| `autoLinkToCampaignId` | Nein | Veraltet. ID einer Kampagne, der das Dokument zugeordnet werden soll. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'
```

**Antwort** — `202 Accepted`

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}
```

| Status | Wann |
|---|---|
| `400` | Ein erforderliches Feld fehlt oder der Dateityp kann nicht gelesen werden. |
| `403` | `storage_path` befindet sich außerhalb Ihres eigenen Upload-Ordners. |

---

## Quelle prüfen

`GET /kb-sources/{sourceId}`

Die Abfrage, die auf jeden Import und jede Aktualisierung folgt. Wiederholen Sie diese, bis der Status `ready` oder `failed` lautet.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()
```

**Antwort**

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}
```

| Feld | Typ | Beschreibung |
|---|---|---|
| `status` | string | Wo sich die Quelle in der Pipeline befindet (siehe die [Statustabelle](#how-an-import-works)). |
| `faq_count` | integer | Wie viele FAQs bisher aus dieser Quelle generiert wurden. |
| `section_count` | integer | In wie viele Inhaltsabschnitte die Quelle unterteilt wurde. |
| `error_message` | string \| null | Warum der Import fehlgeschlagen ist, wenn der Status `failed` ist. Ansonsten `null`. |

---

## Eine Quelle löschen

`DELETE /kb-sources/{sourceId}`

Entfernt eine Wissensquelle. **Standardmäßig bleiben die daraus erstellten FAQs erhalten** – fügen Sie `delete_faqs=true` hinzu, um diese ebenfalls zu entfernen.

**Abfrageparameter**

| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| `delete_faqs` | Nein | Auf `true` setzen, um auch alle FAQs zu löschen, die diese Quelle erstellt hat. Standardwert ist `false`. |

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"
```

**Antwort**

```json
{
  "success": true,
  "faqs_deleted": 24
}
```

`faqs_deleted` ist `0`, es sei denn, Sie haben `delete_faqs=true` angefordert.

---

## Viele Seiten auf einmal importieren

`POST /kb-sources/bulk-import`

Fügt bis zu 100 Webseiten in einem Aufruf hinzu – der übliche nächste Schritt nach [Seiten auf einer Website entdecken](#discover-pages-on-a-website) oder [Neue Seiten auf einer Website finden](#find-new-pages-on-a-website). Seiten, die bereits in Ihrer Wissensdatenbank vorhanden sind, werden übersprungen, anstatt dupliziert zu werden (und sind weiterhin mit dem Agenten verknüpft, wenn Sie dies angefordert haben).

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `urls` | Ja | Zu importierende Adressen. Mindestens 1, maximal 100 pro Aufruf. |
| `autoLinkToAgentId` | Nein | ID eines KI-Agenten, dem jede importierte Seite zugeordnet werden soll. |
| `autoLinkToCampaignId` | Nein | Veraltet. ID einer Kampagne, der jede importierte Seite zugeordnet werden soll. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]
```

**Antwort** — `202 Accepted`

```json
{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}
```

Fragen Sie jede ID in `queued_source_ids` mit [Eine Quelle prüfen](#check-a-source) ab. Das Senden eines leeren `urls`-Arrays, eines Eintrags, der kein String ist, oder von mehr als 100 Einträgen gibt `400` zurück.

---

## Viele Quellen auf einmal löschen

`POST /kb-sources/bulk-delete`

Entfernt bis zu 2.000 Wissensquellen in einem Aufruf. Der Löschvorgang läuft im Hintergrund und Sie erhalten eine E-Mail, sobald er abgeschlossen ist.

> **Beim Massenlöschen werden auch die FAQs entfernt.** Im Gegensatz zu [Quelle löschen](#delete-a-source), bei dem die FAQs erhalten bleiben, sofern Sie nichts anderes angeben, löscht dieser Endpunkt jede Quelle zusammen mit den daraus erstellten FAQs. Es gibt keine Option, diese beizubehalten.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `sourceIds` | Ja | IDs der zu entfernenden Quellen. Mindestens 1, maximal 2.000 pro Aufruf. |
| `domainLabel` | Nein | Ein benutzerfreundlicher Name für diese Bereinigung. Wird nur in der Abschluss-E-Mail verwendet. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'
```

**Antwort** — `202 Accepted`

```json
{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}
```

---

## Seiten auf einer Website entdecken

`POST /kb-sources/discover-pages`

Durchsucht eine Website von einer Startadresse aus und listet die auf derselben Domain gefundenen Seiten auf, jeweils mit einer Einschätzung, ob sich ein Import lohnt. **Es wird nichts importiert und nichts für Sie ausgewählt** — dies ist der Schritt „Was befindet sich auf dieser Website“, den Sie ausführen, bevor Sie entscheiden, was an [Viele Seiten auf einmal importieren](#import-many-pages-at-once) gesendet werden soll.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `url` | Ja | Adresse, von der aus die Erkundung gestartet werden soll, normalerweise die Startseite der Website. |
| `maxPages` | Nein | Obergrenze für die Anzahl der zurückzugebenden Seiten. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'
```

**Antwort**

```json
{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}
```

| Feld | Typ | Beschreibung |
|---|---|---|
| `source_type` | string | Wie die Seiten gefunden wurden — `sitemap` (die eigene Sitemap der Website) oder `link_discovery` (durch Folgen von Links). |
| `url` | string | Vollständige Adresse der Seite. |
| `title` | string \| null | Seitentitel, sofern einer gelesen werden konnte. |
| `depth` | integer | Wie viele Links von der Startseite entfernt diese Seite gefunden wurde. |
| `score` | integer | Wie nützlich die Seite als Wissen erscheint, von `0` bis `100`. |
| `recommendation` | string | `add` (eindeutig einen Import wert, Punktzahl 90 oder höher), `maybe` (grenzwertig) oder `skip` (Inhalte, die selten für einen Assistenten hilfreich sind — Änderungsprotokolle, rechtliche Seiten, doppelte Übersetzungen). |
| `reason_key` | string | Ein stabiler, maschinenlesbarer Grund für die Empfehlung, zum Beispiel `core_page`, `changelog_history`, `legal_page` oder `locale_duplicate`. |

> **Die Erkundung erfolgt nach bestem Bemühen.** Wenn die Website nicht gelesen werden kann, ist die Antwort dennoch `200`, mit `success: false`, einer leeren `pages`-Liste und einer `error`-Nachricht. Überprüfen Sie `success`, bevor Sie `pages` lesen.

Ein fehlendes `url` gibt `400` zurück.

---

## Kosten eines Imports schätzen

`POST /kb-sources/estimate-cost`

Berechnet, wie viele Credits ein geplanter Import verbrauchen würde, bevor Sie sich dazu verpflichten. Seiten werden abgerufen und Dokumente gelesen, um ihre Größe zu messen, aber es wird nichts importiert und die Schätzung selbst verbraucht keine Credits.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `urls` | Nein | Seitenadressen, deren Import Sie in Betracht ziehen. |
| `files` | Nein | Bereits hochgeladene Dateien, die Sie in Betracht ziehen. Jeder Eintrag benötigt `storage_path`, `filename` und `mime_type`. |
| `tier` | Nein | Die KI-Qualitätsstufe, auf der der Import ausgeführt wird, damit die Schätzung mit dem übereinstimmt, was Ihnen tatsächlich berechnet wird. Lassen Sie es für den Standardtarif weg. |

Senden Sie `urls`, `files` oder beides.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'
```

**Antwort**

```json
{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7
}
```

Jede Zeile spiegelt die URL oder den Speicherpfad in `ref` wider, sodass Sie sie Ihrer Eingabe zuordnen können. Eine Seite oder Datei, die nicht gelesen werden konnte, erhält dennoch eine Zeile, die als ein Chunk gezählt wird, mit einem `error` darauf.

---

## Einen Import stoppen

`POST /kb-sources/cancel-import`

Stoppt Seiten, die noch in der Importwarteschlange warten – die Schaltfläche „Import stoppen“ für einen Crawl, der sich als größer herausgestellt hat als erwartet. Das Abbrechen einer wartenden Seite kostet nichts, da sie noch nicht gelesen wurde.

Seiten, die bereits verarbeitet werden, werden **nicht** gestoppt: Ihre Bearbeitung läuft bereits und wird in jedem Fall berechnet, daher werden sie fertiggestellt. Die Antwort gibt an, wie viele das waren.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `host` | Nein | Stoppt nur wartende Seiten auf dieser Website (zum Beispiel `docs.example.com`). Lassen Sie es weg, um jeden wartenden Import im Konto zu stoppen. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'
```

**Antwort**

```json
{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}
```

---

## Einen pausierten Import fortsetzen

`POST /kb-sources/resume-import`

Startet einen Import neu, der pausiert wurde, weil Ihr eigener KI-Schlüssel nicht mehr funktionierte.

> Dieser Aufruf **ist** Ihre Zustimmung, den Import mit dem Schlüssel abzuschließen, der jetzt aktiv ist – was bedeuten kann, dass Plattform-Credits verbraucht werden, falls Ihr eigener Schlüssel immer noch nicht funktioniert.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `host` | Nein | Setzt nur pausierte Seiten auf dieser Website fort. Lassen Sie es weg, um alles Pausierte fortzusetzen. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Antwort**

```json
{
  "success": true,
  "resumed": 58
}
```

---

## Neue Seiten auf einer Website finden

`POST /kb-sources/refresh-domain`

Durchsucht eine Website, von der Sie bereits importiert haben, und meldet nur die Seiten, die noch **nicht** in Ihrer Wissensdatenbank enthalten sind, jeweils mit derselben Empfehlung wie bei der Seitenerkennung. Es wird nichts importiert und nichts geändert.

Die beiden Folgeaktionen sind bewusst separate Aufrufe, daher kostet es nichts, diesen hier abzubrechen:

- importieren Sie die neuen Seiten, die Sie möchten, mit [Importieren Sie viele Seiten auf einmal](#import-many-pages-at-once);
- lesen Sie die Seiten, die Sie bereits haben, erneut mit [Aktualisieren Sie jede Seite auf einer Website](#refresh-every-page-on-a-website).

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `baseUrl` | Ja | Jede Adresse auf der Website oder nur der Host. |
| `maxPages` | Nein | Obergrenze für die Anzahl der zu durchsuchenden Seiten. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'
```

**Antwort**

```json
{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}
```

| Feld | Typ | Beschreibung |
|---|---|---|
| `discovered` | Ganzzahl | Wie viele Seiten insgesamt auf der Website gefunden wurden. |
| `new_pages` | Array | Seiten, die noch nicht in Ihrer Wissensdatenbank enthalten sind. Es wird nichts für Sie in die Warteschlange gestellt – importieren Sie die gewünschten Seiten. |
| `new_urls_queued` | Ganzzahl | Immer `0`. Aus Gründen der Abwärtskompatibilität beibehalten; dieser Endpunkt stellt nie etwas in die Warteschlange. |
| `existing_refresh_queued` | Ganzzahl | Wie viele Seiten, die Sie bereits von dieser Website importiert haben, als bereit zum erneuten Lesen gefunden wurden. Durch diesen Aufruf wird nichts in die Warteschlange gestellt. |
| `batch_id` | Zeichenfolge | Nur vorhanden, wenn ein Batch erstellt wurde. |

Wie die Erkennung schlägt dies sanft fehl: Eine Website, die nicht gelesen werden kann, gibt immer noch `200` zurück, mit `success: false`, einem leeren `new_pages` und einem `error`. Ein fehlendes oder leeres `baseUrl` gibt `400` zurück.

---

## Aktualisieren Sie jede Seite auf einer Website

`POST /kb-sources/trigger-domain-refresh`

Liest jede Seite, die Sie bereits von einer Website importiert haben, erneut, sodass deren FAQs dem aktuellen Inhalt der Website entsprechen: Geänderte Abschnitte werden aktualisiert, neue Abschnitte hinzugefügt und entfernte Abschnitte gelöscht.

Dies stellt die Arbeit in die Warteschlange und kehrt sofort zurück. Folgen Sie dem mit [Verfolgen Sie eine Website-Aktualisierung](#track-a-website-refresh) und stoppen Sie es mit [Stoppen Sie eine Website-Aktualisierung](#stop-a-website-refresh).

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `baseUrl` | Ja | Jede Adresse auf der Website oder nur der Host. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'
```

**Antwort**

```json
{
  "success": true,
  "queued": 249
}
```

---

## Verfolgen Sie eine Website-Aktualisierung

`GET /kb-sources/domain-refresh-status`

Wie weit eine Website-Aktualisierung fortgeschritten ist, damit Sie den Fortschritt wie "221 von 249" anzeigen können.

**Abfrageparameter**

| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| `baseUrl` | Ja | Jede Adresse auf der Website oder nur der Host. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"
```

**Antwort**

```json
{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}
```

`job` ist `null`, wenn keine Aktualisierung für diese Website läuft. Die bisher fertiggestellten Seiten sind `total` minus `pending`. Der Job `status` ist einer von `refreshing` (arbeitet noch Seiten ab), `deduplicating` (der Bereinigungsdurchlauf am Ende) oder der endgültige `completed`, `failed` und `cancelled`. Behalten Sie `domainBatchId` – dies ist das, was Sie an den Abbruch-Endpunkt übergeben.

Ein fehlendes oder leeres `baseUrl` gibt `400` zurück.

---

## Website-Aktualisierung stoppen

`POST /kb-sources/refresh-domain/cancel`

Stoppt eine Website-Aktualisierung, die noch Seiten verarbeitet. Bereits fertiggestellte Seiten behalten ihre aktualisierten Inhalte; nicht begonnene Seiten werden verworfen, und Seiten, die gerade erneut eingelesen wurden, kehren in ihren vorherigen Zustand zurück.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `jobId` | Ja | Die `domainBatchId`, die von [Website-Aktualisierung verfolgen](#track-a-website-refresh) zurückgegeben wurde. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'
```

**Antwort**

```json
{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}
```

| Feld | Typ | Beschreibung |
|---|---|---|
| `status` | string | Status der Aktualisierung nach diesem Aufruf: `cancelled`, `deduplicating`, `completed` oder `failed`. |
| `cancelled_units` | integer | Wie viel Arbeit noch ausstand, als der Abbruch erfolgte. `0` bei einem wiederholten Abbruch. |
| `sources_reset` | integer | Seiten, die aus der Verarbeitung genommen und auf `ready` zurückgesetzt wurden. |
| `sources_cancelled` | integer | Brandneue Seiten dieser Aktualisierung, die noch in der Warteschlange standen und nun abgebrochen wurden. |

Ein zweimaliger Abbruch ist harmlos – der zweite Aufruf meldet denselben Endzustand. Sobald die Aktualisierung in den Bereinigungsschritt übergegangen ist, kann sie nicht mehr gestoppt werden, und die Antwort erfolgt mit `success: false` und `reason: "already_finalizing"`. Eine fehlende `jobId` gibt `400` zurück, und ein Job, der sich nicht in Ihrem Konto befindet, gibt `404` zurück.

---

## Eine einzelne Quelle aktualisieren

`POST /kb-sources/{sourceId}/refresh`

Liest eine bereits importierte Webseite erneut ein und gleicht deren FAQs mit dem aktuellen Inhalt der Seite ab: Geänderte Abschnitte werden aktualisiert, neue hinzugefügt und entfernte gelöscht.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"
```

**Antwort** — `202 Accepted`

```json
{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}
```

Fragen Sie die Quelle ab, bis ihr Status `queued` und `processing` verlässt. Eine Quellen-ID, die sich nicht in Ihrem Konto befindet, gibt `404` zurück.

---

## Die relevantesten Seiten auswählen

`POST /kb-sources/select-relevant-pages`

Bittet die KI, aus einer Liste von Kandidaten die fünf Seiten auszuwählen, die ein Unternehmen am besten beschreiben – wird verwendet, wenn ein Kampagnen-Playbook von einer Website generiert wird. Dies verbraucht Credits.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `urls` | Ja | Kandidaten-Seitenadressen zur Auswahl, normalerweise aus der Seitenerkennung. |
| `homeUrl` | Ja | Die Startseite der Website, die als Kontext für die Auswahl verwendet wird. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'
```

**Antwort**

```json
{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}
```

Dies ist ein Hilfsprogramm, keine Ressource: Im Fehlerfall antwortet es dennoch mit `200`, mit `success: false`, einer leeren `pages`-Liste und einer `error`-Nachricht.

---

## Wissensgruppen

Eine **Wissensgruppe** ist ein benanntes Bündel von FAQs – „Versand und Rücksendungen“, „Onboarding“ –, das Sie mit einem einzigen Aufruf auf einen Agenten oder eine Kampagne anwenden können. Die Gruppe enthält Referenzen, keine Kopien: Die FAQs selbst verbleiben in Ihrer zentralen Bibliothek. Wenn Sie also eine FAQ über die [FAQs-API](faqs.md) bearbeiten, wird sie überall dort aktualisiert, wo sie verwendet wird.

Das Anwenden einer Gruppe **fügt** immer nur das hinzu, was fehlt. Daher ist das zweimalige Anwenden derselben Gruppe harmlos und `added_count` wird beim zweiten Mal als `0` zurückgegeben.

---

## Wissensgruppe erstellen

`POST /kb-groups`

Erstellt eine Gruppe. Sie ist anfangs leer – fügen Sie ihr FAQs mit [FAQ zu einer Gruppe hinzufügen](#add-a-faq-to-a-group) hinzu.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `name` | Ja | Name der Gruppe. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]
```

**Antwort** — `201 Created`

```json
{
  "success": true,
  "group_id": "kbg_abc123"
}
```

---

## Wissensgruppe umbenennen

`PUT /kb-groups/{groupId}`

Ändert den Namen einer Gruppe. Die enthaltenen FAQs bleiben unverändert.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `name` | Ja | Neuer Name für die Gruppe. |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'
```

**Antwort**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}
```

---

## Wissensgruppe löschen

`DELETE /kb-groups/{groupId}`

Löscht die Gruppe. Nur das Bündel wird entfernt – die darin enthaltenen FAQs verbleiben in Ihrer Bibliothek, und alles, worauf die Gruppe bereits angewendet wurde, behält diese FAQs bei.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"
```

**Antwort**

```json
{
  "success": true
}
```

---

## FAQ zu einer Gruppe hinzufügen

`POST /kb-groups/{groupId}/faqs`

Fügt eine bestehende FAQ zu einer Gruppe hinzu. Dies ändert nur das Paket – es verknüpft die FAQ nicht von selbst mit einem Agenten; wenden Sie dafür die Gruppe an.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `faq_id` | Ja | ID der hinzuzufügenden FAQ. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'
```

**Antwort**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}
```

---

## FAQ aus einer Gruppe entfernen

`DELETE /kb-groups/{groupId}/faqs/{faqId}`

Entfernt eine FAQ aus einer Gruppe. Die FAQ selbst wird nicht gelöscht, und Agenten, auf die die Gruppe bereits angewendet wurde, behalten sie.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"
```

**Antwort**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}
```

---

## Eine Gruppe auf einen Agenten anwenden

`POST /kb-groups/{groupId}/apply-to-agent`

Fügt jede FAQ in der Gruppe mit einem einzigen Aufruf zum Wissen eines KI-Agenten hinzu – der schnelle Weg, einem neuen Agenten einen bereits kuratierten Wissensbestand zu geben.

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `agent_id` | Ja | ID des KI-Agenten, auf den die Gruppe angewendet werden soll. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]
```

**Antwort**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}
```

`added_count` gibt an, wie viele FAQs tatsächlich hinzugefügt wurden – `0`, wenn die Gruppe leer ist oder bereits angewendet wurde.

---

## Eine Gruppe auf eine Kampagne anwenden

`POST /kb-groups/{groupId}/apply-to-campaign`

Die Classic-Campaign-Version des obigen Aufrufs. Verwenden Sie bei einem Agenten-basierten Konto stattdessen [Eine Gruppe auf einen Agenten anwenden](#apply-a-group-to-an-agent).

**Anfragefelder**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `campaign_id` | Ja | ID der Kampagne, auf die die Gruppe angewendet werden soll. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'
```

**Antwort**

```json
{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}
```

---

## Fehler der Knowledge Base API

Diese Endpunkte geben den Standard-Fehler-Envelope zurück:

```json
{
  "success": false,
  "error": "Knowledge base source not found."
}
```

| Status | Wenn es bei einem Knowledge-Base-Endpunkt auftritt |
|---|---|
| `400` | Ein erforderliches Feld fehlt oder ist ungültig – ein leeres `url`, ein fehlendes `baseUrl` oder `jobId`, mehr als 100 URLs bei einem Massenimport, mehr als 2.000 IDs bei einer Massenlöschung oder ein Dateityp, den wir nicht lesen können. |
| `402` | Nicht genügend Credits, um den Import auszuführen. Laden Sie Ihr Guthaben auf und versuchen Sie es erneut. |
| `403` | Ein `storage_path` außerhalb Ihres eigenen Upload-Ordners – oder Ihr Plan beinhaltet keinen API-Zugriff. |
| `404` | Die Quelle, Gruppe, FAQ, der Agent, die Kampagne oder der Aktualisierungsauftrag wurde nicht gefunden – entweder existiert er nicht oder er gehört zu einem anderen Konto. |

> **Soft-Failures sind keine Fehler.** Discovery (`discover-pages`, `refresh-domain`) und der Seiten-Auswahl-Helfer antworten bei `200` mit `success: false` und einer `error`-Nachricht, wenn die Website nicht gelesen werden kann, anstatt die Anfrage fehlschlagen zu lassen. Überprüfen Sie immer `success`, bevor Sie die Daten lesen.

Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann — `401`, `403` (Ihr Plan beinhaltet keinen API-Zugriff), `429` (Ratenbegrenzung) und `500` — sind zusammen mit Hinweisen zur Wiederholung unter [Fehler & Paginierung](errors-and-pagination.md) aufgeführt.

---

## Verwandte Themen

- [FAQs API](faqs.md) – Lesen, Bearbeiten und Verknüpfen der FAQs, die Ihre Quellen erzeugen.
- [FAQs verwalten](../ai-automation/faq-management.md) – dieselbe Knowledge Base im Dashboard.
- [KI-Agenten](../ai-agents/ai-agents.md) – die Agenten, denen Sie Quellen und Gruppen zuweisen.
- [API-Zugriff](../integrations/api-access.md) – Generieren Sie Ihren API-Schlüssel.
- [Authentifizierung](authentication.md) – alle Möglichkeiten, Ihren Schlüssel zu übermitteln.