Zum Inhalt springen
Sursa Developers

Schnellstart

Diese Anleitung bringt Sie in fünf Minuten von null zu einer funktionierenden Integration: Sie erstellen einen API-Schlüssel, prüfen ihn, fügen der Wissensbasis ein Dokument hinzu, finden es wieder und stellen eine Frage dazu. Jeder Schritt ist eine einzige HTTP-Anfrage. Wählen Sie Ihre Sprache einmal in einem beliebigen Beispiel aus – alle Beispiele der Seite wechseln mit.

Die Beispiele mit Sprachumschalter verwenden die API-Adresse dieses Portals: https://api.sursa.com in der Sursa-Cloud oder die API-Adresse Ihrer eigenen Installation. Wo ein Beispiel https://api.example.com zeigt, setzen Sie Ihre API-Adresse ein. Wenn Sie nicht sicher sind, welche Adresse Sie haben, lesen Sie API-Adresse und Umgebungen.

1. API-Schlüssel erstellen

Schlüssel legen Administratorinnen und Administratoren der Organisation in Sursa unter Administration → API keys an. Geben Sie dem Schlüssel einen Namen, der sagt, wo er verwendet wird (zum Beispiel „CRM sync“), wählen Sie seine Rolle und, wenn Sie ihn weiter einschränken möchten, seine Scopes. Der Schlüssel darf, was eine Person mit dieser Rolle darf, und nicht mehr, als seine Scopes erlauben. Für diese Anleitung genügt die Rolle editor.

Der Schlüssel wird nur einmal angezeigt. Bewahren Sie ihn im Secret-Speicher Ihres Systems auf und übergeben Sie ihn Ihrem Code in einer Umgebungsvariablen:

export SURSA_API_KEY="kb_…"

Jede Anfrage sendet den Schlüssel im Header Authorization als Bearer-Token. API-Schlüssel und Scopes erklärt Rollen, Scopes, Ablauf und Rotation.

2. Client einrichten

Sie brauchen keine Bibliothek: Die API ist reines HTTPS mit JSON. Die Beispiele dieser Anleitung verwenden in jeder Sprache eine kleine Hilfsfunktion. Kopieren Sie die Variante für Ihre Sprache; spätere Anleitungen verwenden dieselbe Hilfsfunktion. Die offiziellen Client-Bibliotheken finden Sie unter SDKs.

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

3. Schlüssel prüfen

GET /v1/me beschreibt den Aufrufer: die Organisation, den Schlüssel, seine Rolle und Scopes sowie das Ratenlimit, das für ihn gilt. Die Anfrage funktioniert mit jedem gültigen Schlüssel und ist daher die beste erste Anfrage jeder 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}
}

Ein 401 mit dem Code auth.not_authenticated bedeutet, dass der Schlüssel fehlt, widerrufen oder falsch eingegeben ist; api_keys.expired bedeutet, dass er abgelaufen ist.

4. Sammlung finden

Karten liegen in Sammlungen. GET /v1/collections listet die Sammlungen auf, die Ihr Schlüssel sehen kann:

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

Notieren Sie id und name der Sammlung, mit der Sie arbeiten möchten. Die folgenden Beispiele verwenden die Sammlung 3 mit dem Namen support.

5. Dokument hinzufügen

PUT /v1/cards-by-external-id/{external_id} erstellt eine Karte unter Ihrer eigenen ID oder ersetzt sie, wenn die Karte bereits existiert. Die Anfrage zweimal auszuführen ist unbedenklich: Beim zweiten Mal hat sich der Inhalt nicht geändert, und die Antwort lautet skipped mit dem Grund unchanged. Verwenden Sie die ID des Datensatzes in Ihrem System 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."
  }'

Die Anfrage kehrt zurück, sobald die Karte gefunden werden kann: 201 mit "status": "ready" für eine neue Karte, 200 für eine ersetzte. HTML und reiner Text funktionieren genauso mit "content_type": "html" oder "text". Dateien (PDF, Word, Excel und andere) laufen als multipart/form-data über denselben Endpunkt; Dokumente importieren behandelt Dateien, Ordner, Metadaten und den Import vieler Dokumente.

POST /v1/search findet die Textstellen von Karten, die zu einer Suchanfrage passen, die beste Übereinstimmung zuerst:

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 erwartet den Namen der Sammlung. Ohne diesen Parameter durchsucht die Suche die Sammlung mit dem Namen default.

7. Frage stellen

POST /v1/ask beantwortet eine Frage in natürlicher Sprache und gibt die Quellen der Antwort zurück. Der Assistent findet das passende Wissen und antwortet nur aus Karten, die der Schlüssel lesen darf.

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

Wird nichts Passendes gefunden, lautet die Antwort trotzdem 200, mit "empty": "no_hits" und einer kurzen Erklärung in answer. Was in diesem Fall angezeigt wird, entscheidet Ihr Code.

Nächste Schritte