Direct naar de inhoud
Sursa Developers

Snelstart

Met deze handleiding ga je in vijf minuten van niets naar een werkende integratie: je maakt een API-sleutel, controleert die, voegt een document toe aan de kennisbank, vindt het terug en stelt er een vraag over. Elke stap is één HTTP-request. Kies in een willekeurig voorbeeld één keer je programmeertaal; alle voorbeelden op de pagina wisselen mee.

De voorbeelden met een taalkeuze gebruiken het API-adres van dit portaal: https://api.sursa.com in de Sursa-cloud, of het API-adres van je eigen installatie. Waar een voorbeeld https://api.example.com toont, zet je je eigen API-adres op die plek. Zie API-adres en omgevingen als je niet zeker weet welk adres je hebt.

1. API-sleutel maken

Een beheerder van de organisatie maakt sleutels in Sursa onder Administration → API keys (beheer → API-sleutels). Geef de sleutel een naam die zegt waar hij wordt gebruikt (bijvoorbeeld “CRM sync”), kies de rol en, als je hem verder wilt beperken, de scopes. De sleutel kan doen wat een gebruiker met die rol kan doen, en niet meer dan zijn scopes toestaan. Voor deze handleiding volstaat de rol editor.

De sleutel wordt één keer getoond. Bewaar hem in de secretmanager van je systeem en geef hem via een omgevingsvariabele door aan je code:

export SURSA_API_KEY="kb_…"

Elk request stuurt de sleutel als bearer-token mee in de header Authorization. API-sleutels en scopes legt rollen, scopes, verloopdatum en rotatie uit.

2. Client instellen

Er is geen bibliotheek nodig: de API is gewoon HTTPS en JSON. De voorbeelden in deze handleiding gebruiken in elke taal een kleine hulpfunctie. Kopieer die voor jouw taal; latere handleidingen gebruiken dezelfde hulpfunctie. De officiële clientbibliotheken staan onder SDK’s.

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

3. Sleutel controleren

GET /v1/me beschrijft de aanroeper: de organisatie, de sleutel, zijn rol en scopes, en de snelheidslimiet die erop van toepassing is. Het werkt met elke geldige sleutel en is daarom het beste eerste request van elke integratie.

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}
}

Een 401 met de code auth.not_authenticated betekent dat de sleutel ontbreekt, is ingetrokken of verkeerd is getypt; api_keys.expired betekent dat hij is verlopen.

4. Collectie zoeken

Kaarten staan in collecties. GET /v1/collections toont de collecties die je sleutel kan zien:

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

Noteer de id en de name van de collectie waarmee je wilt werken. De voorbeelden hieronder gebruiken de collectie 3, met de naam support.

5. Document toevoegen

PUT /v1/cards-by-external-id/{external_id} maakt een kaart onder je eigen ID, of vervangt hem als de kaart al bestaat. Het request twee keer uitvoeren is veilig: de tweede keer is de inhoud niet veranderd en is het antwoord skipped met de reden unchanged. Gebruik de ID van het record in je systeem als 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."
  }'

Het request geeft antwoord zodra de kaart vindbaar is: 201 met "status": "ready" voor een nieuwe kaart, 200 voor een vervangen kaart. HTML en platte tekst werken op dezelfde manier met "content_type": "html" of "text". Bestanden (PDF, Word, Excel en andere) gaan via hetzelfde endpoint als multipart/form-data; Documenten importeren behandelt bestanden, mappen, metadata en het importeren van veel documenten.

POST /v1/search vindt de passages van kaarten die bij een zoekopdracht passen, de beste treffer eerst:

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 neemt de naam van de collectie aan. Zonder deze parameter doorzoekt de zoekopdracht de collectie met de naam default.

7. Vraag stellen

POST /v1/ask beantwoordt een vraag in gewone taal en geeft de bronnen van het antwoord terug. De assistent vindt de juiste kennis en antwoordt alleen op basis van kaarten die de sleutel mag lezen.

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"}'

Wordt er niets relevants gevonden, dan is de response toch 200, met "empty": "no_hits" en een korte uitleg in answer. Je code bepaalt wat de gebruiker in dat geval te zien krijgt.

Volgende stappen