Integrasjon av Karla AI-søk via API

Denne guiden viser hvordan dere tester Karla Search API i API-dokumentasjonen og deretter bruker de samme requestene i deres egen frontend-integrasjon. Målet er et søkegrensesnitt, inline eller popup, med AI-svar og relevante kilder.

Start i API-dokumentasjonen. Her finner dere endepunkter, request bodies, svarformater og feilsvar. I API-et identifiseres en agent med feltet model_id. I eksemplene er MODEL_ID en plassholder som dere skal erstatte med ID-en til deres egen agent.

Opprett OAuth 2.0-credentials

Logg inn på Karla-plattformen, gå til Karlas utviklerinnstillinger og opprett et sett med OAuth 2.0-credentials. Oppbevar client_id og client_secret på et sikkert sted. Credentials må tilhøre den organisasjonen som agenten ligger i.

Oppbevar client_secret i backend

I deres egen integrasjon skal client_secret oppbevares i backend og må aldri inngå i frontend-koden.

Logg inn i API-dokumentasjonen og autoriser først

Åpne API-dokumentasjonen, og logg inn hvis dere blir bedt om det.
Skriv inn Client ID og Client Secret fra trinn 1 i feltene øverst, og klikk på Authorize.
Vent til dokumentasjonen viser ✓ Authorized før dere tester endepunkter med Try it out og Execute.

Autoriser før første API-kall

Innlogging i Karla erstatter ikke autorisering av API-requests. Uten et gyldig access token vil de beskyttede kallene feile. Dokumentasjonen henter tokenet og legger selv til Authorization: Bearer <access_token> i requestene deres.

Hent den publiserte versjonen av agenten deres

Velg search-agenten dere vil integrere med, og bruk modell-ID-en dens. Agenten må tilhøre organisasjonen deres og ha en publisert versjon. Kontakt Karla hvis dere mangler agentens ID.

Finn GET /v1/models/{model_id}/published under Models. Klikk på Try it out, legg inn agentens ID som model_id, og klikk på Execute.

HTTP

GET https://api.getkarla.ai/v1/models/{model_id}/published
Authorization: Bearer <access_token>

Ved suksess inneholder svaret type: "success" og konfigurasjonen til den publiserte search-agenten under response. De relevante feltene er:

Felt i svaret

Bruk

response.id

Agentens modell-ID. Brukes som model_id i søkekallet.

response.version_id

ID-en til den publiserte versjonen. Kan sendes som model_version_id hvis dere vil velge denne versjonen eksplisitt.

response.metadata og response.styles

Konfigurasjon som dere etter behov kan bruke til tekster og styling i UI-et deres.

Dere trenger ikke angi en versjon i det første søkekallet: uten model_version_id bruker API-et agentens gjeldende publiserte versjon.

Send et søk

Finn POST /v1/search/query under Search, og klikk på Try it out. Bruk følgende request body med OAuth-credentials deres, og erstatt MODEL_ID med samme agent-ID som i trinn 3:

JSON

{
  "model_id": "MODEL_ID",
  "message": {
    "role": "user",
    "content": "Skriv søket deres her"
  },
  "stream": false,
  "conversation_id": null
}

Feltene må ligge direkte i JSON-objektet ved OAuth-kall. Bruk Content-Type: application/json. Eksempelet bruker stream: false, slik at dere kan lese hele svaret direkte i dokumentasjonen uten å sette opp en socket-tilkobling.

Klikk på Execute, og kontroller svaret:

type er "success" ved et fullført kall.
response.messages inneholder meldingene. Vis content fra meldinger med role: "assistant" som AI-svar.
response.search_query_hits inneholder søkeresultatene. Bruk title og, når den finnes, url til kildelisten.
response.id er samtalens ID. Send den som conversation_id ved et oppfølgingsspørsmål. Bruk null ved en ny samtale.

Se endepunktets schema og eksempler i API-dokumentasjonen for øvrige felter og mulige feilsvar.

Overfør kallene til koden deres og bygg UI-et

Når modell- og søkekallet fungerer i dokumentasjonen, kan dere bruke nøyaktig de samme URL-ene, headerne og request bodies i deres egen integrasjon. Kopier gjerne cURL-requesten som dokumentasjonen genererer, som utgangspunkt.

Backend: credentials og access token

La backend hente og oppbevare access tokenet og videresende modell- og søkekall til Karla API. Frontend kaller backend, som legger til Bearer-tokenet.

Tokenet hentes med følgende request. Erstatt plassholderne med credentials deres, og send body som URL-encoded form-data:

HTTP

POST https://api.getkarla.ai/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Les access_token og expires_in fra token-svaret. Den nåværende API-implementeringen utsteder OAuth-tokens med en levetid på 3600 sekunder. Gjenbruk tokenet så lenge det er gyldig, og hent et nytt med samme client-credentials-kall når det utløper. Denne flyten utsteder ikke et refresh token.

Frontend: svar og kilder

Bygg et responsivt søkefelt, inline eller popup.
Vis en tydelig lastetilstand mens søket kjører, og en forståelig feilmelding hvis kallet feiler.
Vis AI-svaret med støtte for Markdown, inkludert overskrifter, lister og fet tekst.
Vis kilder med tittel og lenke til originalkilden når en lenke finnes.
Lagre samtalens ID hvis brukeren skal kunne stille oppfølgingsspørsmål. Legg eventuelt til foreslåtte spørsmål som knapper.

Streaming med Socket.IOValgfritt

Når den vanlige requesten fungerer, kan dere legge til fortløpende visning av svaret. Koble til via Socket.IO til namespace /v1/search/query, bli med i et unikt room med join_room, og send samme room i søkerequesten sammen med stream: true.

Event

Bruk

receive_message

Motta opprettelse av meldinger og fortløpende tekstdeler til AI-svaret.

receive_conversation_id

Lagre samtalens ID for oppfølgingsspørsmål.

search_query_hits

Oppdater kildelisten med søkeresultatene.

finished_text_generation

Marker at genereringen av svaret er ferdig.

Hvis et kall feiler

Kontroller først at dokumentasjonen viser Authorized, at credentials tilhører riktig organisasjon, og at agenten har en publisert versjon. Kontroller deretter request body mot endepunktets schema, og les HTTP-statusen og feilmeldingen i svaret.

Skriv til oss hvis dere støter på noe underveis, så hjelper vi dere videre.