# Slik fyller du en coreAI-assistent med data via API-et

coreAI-API-et er laget for systemer som vil sende egne data direkte inn i en assistent og bruke dem som svargrunnlag i chat eller søk. Integrasjonen handler først om å holde kunnskapsbasen oppdatert, deretter om å velge hvordan brukerne skal møte assistenten: gjennom coreAI-widgeten, et eget chatgrensesnitt eller et rent søk.

## Start med assistent, kilde og token

Alle kall mot API v2 går mot `https://portal.coreai.no/api/v2` i produksjon eller `https://stage.coreai.no/api/v2` i testmiljøet. API-et bruker et Bearer-token, og de viktigste stiene trenger både `assistantId` og `contentImporterId`.

`assistantId` peker på assistenten som skal svare. `contentImporterId` peker på API-kilden hvor dataene lagres. Når du leser entiteter tilbake med ekstern ID, søker coreAI i den angitte kilden.

## Upsert er hovedløypen for å fylle assistenten

For en løpende integrasjon bør systemet ditt sende en `POST` til `/assistants/{assistantId}/sources/{contentImporterId}` hver gang et objekt opprettes eller endres. Upsert erstatter hele entiteten: første kall oppretter den, senere kall oppdaterer den samme `id`-en. Du trenger altså ikke å gjøre ekstra kall for å sjekke om entiteten allerede finnes, upsert løser dette for deg.

```json
{
  "data": [
    {
      "id": "product-123",
      "type": "products",
      "lastModifiedAt": "2026-04-28T12:00:00Z",
      "attributes": {
        "productNumber": "123",
        "name": "Fjelljakke",
        "description": "Lett skalljakke for skiftende vær.",
        "url": "https://example.com/products/123",
        "price": 1299,
        "inStock": true
      }
    }
  ]
}
```

Entitetstypene dekker de vanligste datakildene en assistent trenger: `products`, `contents`, `documents`, `events`, `contacts`, `job_postings` og `educations`. Hver type har sine egne påkrevde felter. Produkter trenger for eksempel `name` og `productNumber`, mens innhold trenger `name` og `longDescription`.

## Bruk PATCH når bare deler av entiteten endres

`PATCH` mot samme endepunkt lar deg sende bare feltene som er endret. Det passer når et eksternt system publiserer små statusendringer, for eksempel pris, lagerstatus eller dato.

## Sletting av entiteter

`DELETE` tar en enkel liste med `id` og `type`, og fjerner både entiteten og relasjonslenker til den. Bruk det når et objekt ikke lenger skal kunne dukke opp i svar — for eksempel et utgått produkt eller en avlyst stilling.

## Egendefinerte properties gjør dataene filtrerbare

Noen entitetstyper kan ha `properties` med korte, strukturerte verdier. Bruk camelCase-navn som `categoryName`, `publishedAt` eller `market`, og velg type `string`, `number`, `boolean` eller `date`. De samme feltene kan senere brukes i chat- og søkekall med filtre som `$eq`, `$gt`, `$gte`, `$lt`, `$lte` og `$in`.

Dette er nyttig når én assistent har flere markeder, varegrupper eller publiseringsnivåer. Du kan fylle den samme kunnskapsbasen bredt, men be chatten svare fra bare én kilde, ett marked eller én innholdstype.

## Chat kan integreres på tre nivåer

Den enkleste veien er å bruke coreAI sin chatwidget. Da håndterer widgeten samtale-ID, språk, gjeldende URL og strømming for deg. For en skreddersydd opplevelse kan du kalle `/assistants/{assistantId}/chat` direkte og sende `question`, valgfri `cid`, `lang`, `model`, `sources`, `resources`, `filters` og `stream`.

Dersom du integrerer chat selv, må du hente påkrevd konfigurasjon fra `/assistants/{assistantId}/config`. Svaret gir tilgjengelige modeller, kilder og WebSocket-oppsett for strømming. Chatstrømmer publiseres på `ai-chat.<cid>` med hendelsene `ChatStreamProgress` og `ChatStreamUpdated` via WebSocket.

Hvis du ikke trenger en full samtale, kan `/assistants/{assistantId}/search` brukes som kunnskapsbasesøk. Det returnerer treff, faner per type og eventuelt et KI-generert sammendrag. Strømmet sammendrag bruker kanalen `ai-summary.<uuid>` og hendelsen `SummaryUpdated`.

## En god integrasjon er en synkronisering, ikke en engangsimport

Den robuste modellen er å la kildesystemet eie sannheten og coreAI være den søkbare, samtaleklare kopien. Send oppdateringer med stabile eksterne ID-er, bruk `lastModifiedAt`, slett objekter som ikke lenger skal gi svar, og legg på properties som gjør filtrering mulig. Da får assistenten ferske data, sporbare kilder og et chatgrensesnitt som kan bygges så enkelt eller spesialisert som produktet ditt krever.