API-dokumentasjon

1. Autentisering

API-et bruker en API-nøkkel per assistent. Opprett en nøkkel under fanen Integrasjoner på assistenten din. Nøkkelen begynner med dk_ og vises i sin helhet kun én gang — oppbevar den trygt og aldri i klientkode. Send den med i Authorization-headeren som et Bearer-token:

Authorization: Bearer dk_your_api_key

Du kan opprette flere nøkler (f.eks. én per miljø) og tilbakekalle dem enkeltvis. En tilbakekalt nøkkel slutter umiddelbart å virke. API-tilgang krever et aktivt abonnement med tillegget Integrasjoner (API og Slack).

2. /v1/ask-endepunktet

Et enkeltstående, kildebasert spørsmål-og-svar-kall. Endepunktet er tilstandsløst (lagrer ingen samtale) og svarer kun ut fra assistentens egne kilder.

POST /v1/ask

Forespørselskropp (JSON): question (string) — Spørsmålet du vil ha besvart. Påkrevd. Maks 4000 tegn.

curl -X POST https://tryggai.no/api/v1/ask \
  -H "Authorization: Bearer dk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are your opening hours?"}'

const res = await fetch("https://tryggai.no/api/v1/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASSISTANT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ question: "What are your opening hours?" }),
});
const { answer, sources, refused, confidence } = await res.json();

3. Responsformat

En vellykket forespørsel gir 200 OK med følgende JSON-felt:

answer (string)

Det genererte svaret, basert utelukkende på assistentens kilder.

sources (array)

Kildene svaret er bygget på (kan være tom).

sources[].sourceFileId (string)

Intern ID for kildefilen.

sources[].originalFilename (string)

Filnavn eller sidetittel for kilden.

sources[].kind (string | null)

Type kilde, f.eks. fil eller nettside.

sources[].sourceUrl (string | null)

Lenke til kilden hvis den finnes (nettsider).

sources[].chunkIndex (number)

Hvilken del av kilden som ble brukt.

sources[].similarity (number)

Relevansscore (0–1) for kildebiten.

refused (boolean)

true når assistenten ikke fant grunnlag i kildene og avstod fra å svare.

confidence (number | null)

Modellens estimerte sikkerhet (0–1), eller null.

4. Feilkoder

Feil returneres med passende HTTP-statuskode og en JSON-kropp på formen {"error": "..."}.

5. Bruksgrenser

API-kall måles mot eierens abonnement, akkurat som vanlig chat. Hvert svar bruker tokens fra den månedlige inkluderte mengden i planen din. Når den inkluderte mengden er brukt opp, faktureres ekstra bruk som overforbruk dersom du har slått det på — ellers svarer endepunktet med 402 til neste faktureringsperiode.

Det er ingen fast grense på antall kall per sekund, men du bør håndtere 402 ved å stoppe videre kall og varsle eieren. Hver assistent svarer ett spørsmål om gangen per kall.

6. Slack slash-kommando

La teamet stille spørsmål til assistenten rett fra Slack med en slash-kommando, f.eks. /spør Hva er åpningstidene?. Oppsettet gjøres én gang per assistent.

1. Gå til api.slack.com/apps og opprett en ny Slack-app i arbeidsområdet ditt.
2. Under Basic Information finner du Signing Secret. Kopier den.
3. Lim signeringshemmeligheten inn i Slack-feltet under fanen Integrasjoner på assistenten din, og lagre. Du får da en forespørsels-URL (Request URL) tilbake.
4. I Slack-appen, gå til Slash Commands og opprett en kommando (f.eks. /spør). Lim forespørsels-URL-en inn i feltet Request URL.
5. Installer (eller reinstaller) appen i arbeidsområdet. Test kommandoen i en kanal.

Hver forespørsel signeres av Slack med signeringshemmeligheten (HMAC-SHA256) og verifiseres på serveren. Forespørsler eldre enn 5 minutter avvises. Assistenten bekrefter umiddelbart og leverer svaret kort etter via Slacks response_url, med kildelenker når de finnes. Slack-bruk telles mot samme kvote som API og chat.

7. MCP-server (koble til AI-verktøy)

Hver assistent kan eksponeres som en MCP-server (Model Context Protocol) — den åpne standarden for å koble AI-verktøy til eksterne kunnskapskilder. ChatGPT, Claude og egne AI-agenter kan da slå opp i assistentens kunnskapsbase og få kildebaserte svar direkte i verktøyet de bruker. Endepunkt: POST /api/v1/mcp med assistentens API-nøkkel som Bearer-token. Serveren tilbyr verktøyet «ask» som svarer utelukkende fra assistentens kilder, med kildehenvisninger. MCP-tilgang slås på under Integrasjoner-fanen på assistenten og krever tillegget Integrasjoner (API og Slack).

8. Partnerkanal (Service-API)

For partnere som vil tilby TryggAI-funksjonalitet i egne systemer finnes en egen partnerkanal (Service-API) med multitenant-støtte. Ta kontakt på kontakt@tryggai.no for tilgang og dokumentasjon.