# So befüllen Sie einen coreAI-Assistenten per API mit Daten

Die coreAI-API ist für Systeme gemacht, die eigene Daten direkt in einen Assistenten einspielen und als Antwortgrundlage in Chat oder Suche nutzen wollen. Bei der Integration geht es zunächst darum, die Wissensdatenbank aktuell zu halten – und anschließend zu entscheiden, wie Nutzer dem Assistenten begegnen sollen: über das coreAI-Widget, eine eigene Chat-Oberfläche oder eine reine Suche.

## Beginnen Sie mit Assistent, Quelle und Token

Alle Aufrufe gegen API v2 gehen an `https://portal.coreai.no/api/v2` in Produktion oder `https://stage.coreai.no/api/v2` in der Testumgebung. Die API arbeitet mit einem Bearer-Token, und die wichtigsten Pfade benötigen sowohl `assistantId` als auch `contentImporterId`.

`assistantId` verweist auf den Assistenten, der antworten soll. `contentImporterId` verweist auf die API-Quelle, in der die Daten gespeichert werden. Beim Auslesen von Entitäten anhand der externen ID sucht coreAI in der angegebenen Quelle.

## Upsert ist der Hauptpfad zum Befüllen des Assistenten

Für eine laufende Integration sollte Ihr System bei jedem Anlegen oder Ändern eines Objekts ein `POST` an `/assistants/{assistantId}/sources/{contentImporterId}` schicken. Upsert ersetzt die gesamte Entität: Der erste Aufruf legt sie an, spätere Aufrufe aktualisieren dieselbe `id`. Sie müssen also keine zusätzlichen Aufrufe machen, um zu prüfen, ob die Entität bereits existiert – upsert übernimmt das für Sie.

```json
{
  "data": [
    {
      "id": "product-123",
      "type": "products",
      "lastModifiedAt": "2026-04-28T12:00:00Z",
      "attributes": {
        "productNumber": "123",
        "name": "Bergjacke",
        "description": "Leichte Hardshell-Jacke für wechselhaftes Wetter.",
        "url": "https://example.com/products/123",
        "price": 1299,
        "inStock": true
      }
    }
  ]
}
```

Die Entitätstypen decken die häufigsten Datenquellen eines Assistenten ab: `products`, `contents`, `documents`, `events`, `contacts`, `job_postings` und `educations`. Jeder Typ hat eigene Pflichtfelder. Produkte brauchen etwa `name` und `productNumber`, während Inhalte `name` und `longDescription` benötigen.

## Nutzen Sie PATCH, wenn sich nur Teile der Entität ändern

`PATCH` gegen denselben Endpoint erlaubt es, nur die geänderten Felder zu schicken. Das eignet sich, wenn ein externes System kleine Statusänderungen veröffentlicht, etwa Preis, Lagerbestand oder Datum.

## Löschen von Entitäten

`DELETE` nimmt eine einfache Liste mit `id` und `type` entgegen und entfernt sowohl die Entität als auch deren Beziehungslinks. Nutzen Sie das, wenn ein Objekt nicht mehr in Antworten erscheinen soll – etwa ein ausgelaufenes Produkt oder eine eingestellte Stelle.

## Eigene Properties machen die Daten filterbar

Manche Entitätstypen können `properties` mit kurzen, strukturierten Werten haben. Verwenden Sie camelCase-Namen wie `categoryName`, `publishedAt` oder `market`, und wählen Sie den Typ `string`, `number`, `boolean` oder `date`. Dieselben Felder lassen sich später in Chat- und Suchaufrufen mit Filtern wie `$eq`, `$gt`, `$gte`, `$lt`, `$lte` und `$in` verwenden.

Das ist nützlich, wenn ein Assistent mehrere Märkte, Warengruppen oder Veröffentlichungsstufen abdeckt. Sie können dieselbe Wissensdatenbank breit befüllen, dem Chat aber sagen, nur aus einer bestimmten Quelle, einem Markt oder einer Inhaltsart zu antworten.

## Chat lässt sich auf drei Ebenen integrieren

Der einfachste Weg ist die Nutzung des coreAI-Chat-Widgets. Das Widget übernimmt dann Konversations-ID, Sprache, aktuelle URL und Streaming für Sie. Für ein maßgeschneidertes Erlebnis können Sie `/assistants/{assistantId}/chat` direkt aufrufen und `question`, optional `cid`, `lang`, `model`, `sources`, `resources`, `filters` und `stream` übergeben.

Wenn Sie den Chat selbst integrieren, müssen Sie die nötige Konfiguration unter `/assistants/{assistantId}/config` abrufen. Die Antwort liefert verfügbare Modelle, Quellen und das WebSocket-Setup für Streaming. Chat-Streams werden auf `ai-chat.<cid>` mit den Events `ChatStreamProgress` und `ChatStreamUpdated` über WebSocket veröffentlicht.

Wenn Sie keine vollständige Konversation brauchen, lässt sich `/assistants/{assistantId}/search` als Wissensdatenbanksuche nutzen. Sie liefert Treffer, Reiter pro Typ und optional eine KI-generierte Zusammenfassung. Gestreamte Zusammenfassungen nutzen den Kanal `ai-summary.<uuid>` und das Event `SummaryUpdated`.

## Eine gute Integration ist eine Synchronisation, kein einmaliger Import

Das robuste Modell ist: Das Quellsystem bleibt die Wahrheitsquelle, coreAI ist die durchsuchbare, chatbereite Kopie. Senden Sie Aktualisierungen mit stabilen externen IDs, nutzen Sie `lastModifiedAt`, löschen Sie Objekte, die nicht mehr antworten sollen, und ergänzen Sie Properties, die Filterung ermöglichen. Dann erhält der Assistent frische Daten, nachvollziehbare Quellen und eine Chat-Oberfläche, die so einfach oder so spezialisiert gebaut werden kann, wie Ihr Produkt es verlangt.