Hoppa till innehållet
Sursa Developers

Snabbstart

Den här guiden tar dig från noll till en fungerande integration på fem minuter: du skapar en API-nyckel, kontrollerar den, lägger till ett dokument i kunskapsbasen, hittar det och ställer en fråga om det. Varje steg är ett HTTP-anrop. Välj ditt språk en gång i något exempel; alla exempel på sidan byter då språk.

Exemplen med språkväljare använder den här portalens API-adress: https://api.sursa.com i Sursa-molnet, eller API-adressen för din egen installation. Där ett exempel visar https://api.example.com sätter du in din API-adress i stället. Se API-adress och miljöer om du inte är säker på vilken du har.

1. Skapa en API-nyckel

En administratör i organisationen skapar nycklar i Sursa under Administration → API keys. Ge nyckeln ett namn som säger var den används (till exempel ”CRM-synkning”), välj dess roll och, om du vill snäva in den ytterligare, dess omfång. Nyckeln kan göra det som en användare med den rollen kan göra, och inte mer än vad dess omfång tillåter. För den här guiden räcker rollen editor.

Nyckeln visas en gång. Förvara den i ditt systems hemlighetshanterare och ge den till din kod i en miljövariabel:

export SURSA_API_KEY="kb_…"

Varje anrop skickar nyckeln i huvudet Authorization som en bearer-token. API-nycklar och omfång förklarar roller, omfång, utgångsdatum och rotation.

2. Konfigurera en klient

Du behöver inget bibliotek: API:et är vanlig HTTPS och JSON. Exemplen i den här guiden använder en liten hjälpfunktion på varje språk. Kopiera den för ditt språk; senare guider använder samma hjälpfunktion. De officiella klientbiblioteken finns under SDK:er.

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

3. Kontrollera nyckeln

GET /v1/me beskriver anroparen: organisationen, nyckeln, dess roll och omfång samt den hastighetsbegränsning som gäller för den. Den fungerar med alla giltiga nycklar, så den är det bästa första anropet i varje 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 att nyckeln saknas, är återkallad eller felskriven; api_keys.expired betyder att den har gått ut.

4. Hitta en samling

Kort finns i samlingar. GET /v1/collections listar de samlingar som din nyckel kan se:

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

Anteckna id och name för den samling som du vill arbeta med. Exemplen nedan använder samlingen 3, som heter support.

5. Lägg till ett dokument

PUT /v1/cards-by-external-id/{external_id} skapar ett kort med ditt eget id, eller ersätter det om kortet redan finns. Det är säkert att köra anropet två gånger: andra gången har innehållet inte ändrats, och svaret är skipped med orsaken unchanged. Använd id:t för posten i ditt 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."
  }'

Anropet returnerar när kortet är klart att hittas: 201 med "status": "ready" för ett nytt kort, 200 för ett ersatt kort. HTML och vanlig text fungerar på samma sätt med "content_type": "html" eller "text". Filer (PDF, Word, Excel med flera) går via samma slutpunkt som multipart/form-data; Importera dokument tar upp filer, mappar, metadata och import av många dokument.

POST /v1/search hittar utdrag ur kort som matchar en sökfråga, med bästa träffen 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 samlingens namn. Utan den söker sökningen i samlingen som heter default.

7. Ställ en fråga

POST /v1/ask besvarar en fråga på vanligt språk och returnerar källorna till svaret. Assistenten hittar rätt kunskap och svarar bara utifrån kort som nyckeln får läsa.

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 inget relevant hittas är svaret ändå 200, med "empty": "no_hits" och en kort förklaring i answer. Din kod avgör vad användaren ska se i så fall.

Nästa steg