Hopp til innholdet
Sursa Developers

Hurtigstart

Denne veiledningen tar deg fra ingenting til en fungerende integrasjon på fem minutter: Du oppretter en API-nøkkel, kontrollerer den, legger til et dokument i kunnskapsbasen, finner det og stiller et spørsmål om det. Hvert steg er én HTTP-forespørsel. Velg språket ditt én gang i et hvilket som helst eksempel; alle eksemplene på siden bytter språk sammen med det.

Eksemplene med språkvelger bruker API-adressen til denne portalen: https://api.sursa.com i Sursa-skyen eller API-adressen til din egen installasjon. Der et eksempel viser https://api.example.com, setter du inn API-adressen din i stedet. Se API-adresse og miljøer hvis du ikke er sikker på hvilken du har.

1. Opprett en API-nøkkel

En administrator i organisasjonen oppretter nøkler i Sursa under Administration → API keys (administrasjon, API-nøkler). Gi nøkkelen et navn som sier hvor den brukes (for eksempel «CRM sync»), og velg rollen og, hvis du vil snevre den inn ytterligere, scopene. Nøkkelen kan gjøre det en bruker med den rollen kan gjøre, og ikke mer enn scopene tillater. For denne veiledningen holder rollen editor.

Nøkkelen vises én gang. Lagre den i hemmelighetslageret i systemet ditt, og gi den til koden din i en miljøvariabel:

export SURSA_API_KEY="kb_…"

Hver forespørsel sender nøkkelen i headeren Authorization som bearer-token. API-nøkler og scopes forklarer roller, scopes, utløp og rotasjon.

2. Sett opp en klient

Du trenger ikke noe bibliotek: API-et er vanlig HTTPS og JSON. Eksemplene i denne veiledningen bruker en liten hjelpefunksjon i hvert språk. Kopier den for språket ditt; senere veiledninger bruker den samme hjelpefunksjonen. De offisielle klientbibliotekene er oppført under SDK-er.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. Kontroller nøkkelen

GET /v1/me beskriver den som kaller: organisasjonen, nøkkelen, rollen og scopene til nøkkelen og hastighetsgrensen som gjelder for den. Den fungerer med alle gyldige nøkler, så den er den beste første forespørselen i enhver integrasjon.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

En 401 med koden auth.not_authenticated betyr at nøkkelen mangler, er trukket tilbake eller er skrevet feil; api_keys.expired betyr at den har utløpt.

4. Finn en samling

Kort ligger i samlinger. GET /v1/collections viser samlingene som nøkkelen din kan se:

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

Noter id og name for samlingen du vil arbeide med. Eksemplene nedenfor bruker samlingen 3, som heter support.

5. Legg til et dokument

PUT /v1/cards-by-external-id/{external_id} oppretter et kort under din egen ID, eller erstatter det hvis kortet allerede finnes. Det er trygt å kjøre forespørselen to ganger: Andre gang er innholdet ikke endret, og svaret er skipped med årsaken unchanged. Bruk ID-en til posten i systemet ditt som external_id.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

Forespørselen returnerer når kortet er klart til å bli funnet: 201 med "status": "ready" for et nytt kort, 200 for et erstattet kort. HTML og ren tekst fungerer på samme måte med "content_type": "html" eller "text". Filer (PDF, Word, Excel og andre) går gjennom den samme operasjonen som multipart/form-data; Importer dokumenter dekker filer, mapper, metadata og import av mange dokumenter.

POST /v1/search finner utdrag fra kort som samsvarer med et søk, med det beste treffet først:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection tar navnet på samlingen. Uten den søker du i samlingen som heter default.

7. Still et spørsmål

POST /v1/ask svarer på et spørsmål i vanlig språk og returnerer kildene for svaret. Assistenten finner den relevante kunnskapen og svarer bare ut fra kort som nøkkelen har lov til å lese.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

Når ingenting relevant blir funnet, er svaret likevel 200, med "empty": "no_hits" og en kort forklaring i answer. Koden din avgjør hva brukeren skal se i så fall.

Neste steg