Gå til indholdet
Sursa Developers

Hurtig start

Denne vejledning fører dig fra ingenting til en fungerende integration på fem minutter: Du opretter en API-nøgle, kontrollerer den, tilføjer et dokument til vidensbasen, finder det og stiller et spørgsmål om det. Hvert trin er én HTTP-anmodning. Vælg dit sprog én gang i et vilkårligt eksempel; alle eksempler på siden skifter med.

Eksemplerne med sprogvælger bruger denne portals API-adresse: https://api.sursa.com i Sursas cloud eller API-adressen for din egen installation. Hvor et eksempel viser https://api.example.com, så indsæt din API-adresse i stedet. Se API-adresse og miljøer, hvis du ikke er sikker på, hvilken adresse du har.

1. Opret en API-nøgle

En administrator i organisationen opretter nøgler i Sursa under Administration → API keys (administration, API-nøgler). Giv nøglen et navn, der fortæller, hvor den bruges (fx »CRM sync«), og vælg dens rolle og, hvis du vil indsnævre den yderligere, dens scopes. Nøglen kan det samme som en bruger med den rolle og ikke mere, end dens scopes tillader. Til denne vejledning er rollen editor nok.

Nøglen vises én gang. Gem den i dit systems hemmelighedslager, og giv den videre til din kode i en miljøvariabel:

export SURSA_API_KEY="kb_…"

Hver anmodning sender nøglen i headeren Authorization som bearer-token. API-nøgler og scopes forklarer roller, scopes, udløb og rotation.

2. Sæt en klient op

Du behøver intet bibliotek: API’et er almindelig HTTPS og JSON. Eksemplerne i denne vejledning bruger en lille hjælpefunktion i hvert sprog. Kopiér den til dit sprog; senere vejledninger bruger den samme hjælpefunktion. De officielle klientbiblioteker står under SDK’er.

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

3. Kontrollér nøglen

GET /v1/me beskriver den, der kalder: organisationen, nøglen, dens rolle og scopes og den hastighedsgrænse, der gælder for den. Den virker med enhver gyldig nøgle og er derfor den bedste første anmodning i enhver integration.

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 betyder, at nøglen mangler, er tilbagekaldt eller forkert indtastet; api_keys.expired betyder, at den er udløbet.

4. Find en samling

Kort ligger i samlinger. GET /v1/collections viser de samlinger, som din nøgle kan se:

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

Notér id og name for den samling, du vil arbejde med. Eksemplerne nedenfor bruger samlingen 3 med navnet support.

5. Tilføj et dokument

PUT /v1/cards-by-external-id/{external_id} opretter et kort med dit eget id eller erstatter det, hvis kortet allerede findes. Det er sikkert at køre anmodningen to gange: Anden gang er indholdet ikke ændret, og svaret er skipped med årsagen unchanged. Brug id’et på posten i dit system 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."
  }'

Anmodningen returnerer, når kortet er klar til at blive fundet: 201 med "status": "ready" for et nyt kort og 200 for et erstattet kort. HTML og almindelig tekst fungerer på samme måde med "content_type": "html" eller "text". Filer (PDF, Word, Excel og andre) sendes til den samme operation som multipart/form-data; Importér dokumenter dækker filer, mapper, metadata og import af mange dokumenter.

POST /v1/search finder de uddrag af kort, der matcher en forespørgsel, med det bedste match 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 tager samlingens navn. Uden den omfatter søgningen samlingen med navnet default.

7. Stil et spørgsmål

POST /v1/ask besvarer et spørgsmål i almindeligt sprog og returnerer svarets kilder. Assistenten finder den relevante viden og svarer kun ud fra kort, som nøglen har lov til at læse.

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 der ikke findes noget relevant, er svaret stadig 200 med "empty": "no_hits" og en kort forklaring i answer. Din kode bestemmer, hvad brugeren skal se i så fald.

Næste skridt