Ragnova · Docs
Customer API · v1

API-Referenz

Binde deinen Ragnova-Bot programmatisch an: Wissen pushen, erfasste Anfragen abrufen, Kennzahlen lesen und Live-Tools registrieren, die der Bot zur Laufzeit aufruft.

Einführung

Alle Endpunkte liegen unter dem /v1-Präfix, sprechen JSON und sind an genau einen Bot gebunden. Ein Aufruf braucht immer einen API-Key.

Key-basiert
Ein Bearer-Key pro Bot, mit fein granularen Scopes.
Synchron
Wissens-Push wird sofort eingebettet — du bekommst ready zurück.
Signiert
Live-Tool-Aufrufe sind HMAC-signiert & SSRF-geprüft.

Authentifizierung

Jeder Aufruf braucht einen API-Key im Authorization-Header. Keys erzeugst du im Dashboard unter Konnektoren → API-Zugriff. Jeder Key ist an einen Bot gebunden und trägt Scopes; fehlt ein Scope, antwortet die API mit 403.

Header 
Authorization: Bearer rk_live_...
knowledge:read Wissensquellen lesen
knowledge:write Wissen pushen, aktualisieren, löschen
leads:read Kontaktanfragen lesen
analytics:read Kennzahlen lesen
tools:read Live-Tools lesen
tools:write Live-Tools anlegen, ändern, löschen

Basis-URL & Limits

Basis-URL
https://api.ragnova.de
Rate-Limit
120 Anfragen / Minute · pro Key
Max. Payload
256 KB · POST /v1/knowledge
Format
JSON · UTF-8

Fehler

Fehler kommen als JSON mit maschinenlesbarem error-Code und optionaler message.

400 invalid_input Ungültige oder fehlende Felder im Body.
401 unauthorized Kein oder ungültiger API-Key im Header.
403 forbidden Dem Key fehlt der nötige Scope.
403 upgrade_required Der API-Zugriff ist ab dem Pro-Plan aktiv.
404 not_found Ressource existiert nicht (oder anderer Bot).
409 name_taken Tool-Name ist bereits vergeben.
413 payload_too_large Inhalt über 256 KB.
429 rate_limited Über 120 Anfragen/Minute für diesen Key.

Knowledge

Inhalte in die Wissensbasis pushen und verwalten. Der Bot antwortet daraus.

POST /v1/knowledge knowledge:write

Inhalt pushen oder syncen

Bettet den Inhalt synchron ein und macht ihn durchsuchbar. Mit externalId ist der Aufruf idempotent: ein erneuter Push mit derselben ID ersetzt die bestehende Quelle (alte Chunks werden entfernt).

Body
content Pflicht
string

Klartext, der eingebettet wird.

externalId
string

ID im Kundensystem. Gleiche ID → idempotenter Upsert.

title
string

Anzeigename der Quelle.

url
string (uri)

Optionaler Quell-Link.

curl -X POST "https://api.ragnova.de/v1/knowledge" \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"externalId":"prod-123","title":"NodeMCU ESP8266","content":"Der NodeMCU ist ein WLAN-Mikrocontroller … Lieferzeit 1-2 Tage.","url":"https://shop.de/p/nodemcu"}'
Antwort · 200 
{
  "id": "b1e...",
  "externalId": "prod-123",
  "status": "ready",
  "chunks": 3
}
GET /v1/knowledge knowledge:read

Wissensquellen listen

Alle über die API angelegten Quellen dieses Bots, neueste zuerst.

curl -X GET "https://api.ragnova.de/v1/knowledge" \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "data": [
    {
      "id": "b1e...",
      "external_id": "prod-123",
      "url": "https://shop.de/p/nodemcu",
      "status": "ready",
      "chunks": 3,
      "created_at": "2026-07-01T10:00:00Z",
      "updated_at": "2026-07-01T10:00:00Z"
    }
  ]
}
GET /v1/knowledge/{id} knowledge:read

Quelle lesen

Liest eine Quelle. id ist die Quellen-UUID oder ext:<externalId> für die externe ID.

Parameter
id Pflicht
string · path

UUID oder ext:<externalId>.

curl -X GET "https://api.ragnova.de/v1/knowledge/b1e5f2a0-..." \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "id": "b1e...",
  "external_id": "prod-123",
  "url": "https://shop.de/p/nodemcu",
  "status": "ready",
  "chunks": 3
}
DELETE /v1/knowledge/{id} knowledge:write

Quelle löschen

Entfernt die Quelle samt aller Chunks. Idempotent per ext:<externalId>.

Parameter
id Pflicht
string · path

UUID oder ext:<externalId>.

curl -X DELETE "https://api.ragnova.de/v1/knowledge/b1e5f2a0-..." \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "ok": true
}

Leads

Vom Bot erfasste Kontaktanfragen abrufen (Nachricht, Rückruf, Termin).

GET /v1/leads leads:read

Kontaktanfragen lesen

Anfragen des Bots, neueste zuerst.

Parameter
limit
integer · query

Anzahl 1-200 (Default 100).

curl -X GET "https://api.ragnova.de/v1/leads" \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "data": [
    {
      "id": "9a...",
      "type": "callback",
      "name": "Erika Muster",
      "email": "erika@example.com",
      "phone": "+49 170 ...",
      "message": "Bitte um Rückruf zu Angebot.",
      "preferred_time": "vormittags",
      "source_question": "Was kostet Variante B?",
      "status": "new",
      "created_at": "2026-07-02T08:30:00Z"
    }
  ]
}

Analytics

Aggregierte Kennzahlen des Bots der letzten 30 Tage.

GET /v1/analytics analytics:read

Kennzahlen (30 Tage)

Gespräche, Antwortquote, Leads und CSAT als Momentaufnahme.

curl -X GET "https://api.ragnova.de/v1/analytics" \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "rangeDays": 30,
  "conversations": 812,
  "answered": 749,
  "answeredRate": 92,
  "leads": 37,
  "csatRated": 120,
  "csatPositiveRate": 88
}

Live-Tools

Webhooks, die der Bot zur Laufzeit aufruft. Ragnova ruft deinen Endpoint SSRF-geprüft und HMAC-signiert auf — siehe Webhooks.

GET /v1/tools tools:read

Live-Tools listen

Alle registrierten Tools dieses Bots.

curl -X GET "https://api.ragnova.de/v1/tools" \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "data": [
    {
      "id": "3c...",
      "name": "bestellstatus",
      "description": "Verfolgt eine Bestellung anhand von Bestellnummer und E-Mail.",
      "endpoint_url": "https://shop.de/api/ragnova/order",
      "method": "POST",
      "auth_type": "bearer",
      "enabled": true
    }
  ]
}
POST /v1/tools tools:write

Tool registrieren

Registriert eine Live-Action. Das zurückgegebene signingSecret wird nur EINMAL ausgegeben — damit verifizierst du die Echtheit der Aufrufe.

Body
name Pflicht
string (slug)

z. B. bestellstatus.

description Pflicht
string

Wann das Tool greift — der Router entscheidet danach.

endpointUrl Pflicht
string (https)

Dein Webhook.

method
POST | GET

Default POST.

authType
none | bearer | header

Auth deiner API. Default none.

authHeaderName
string

Nur bei authType=header.

authSecret
string

Verschlüsselt gespeichert, nie zurückgegeben.

timeoutMs
integer

1000-10000, Default 5000.

parameters
array

Bis 20 { name, description, required }.

curl -X POST "https://api.ragnova.de/v1/tools" \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"bestellstatus","description":"Verfolgt eine Bestellung anhand von Bestellnummer und E-Mail.","endpointUrl":"https://shop.de/api/ragnova/order","authType":"bearer","authSecret":"sk_shop_...","parameters":[{"name":"order_id","description":"Bestellnummer","required":true},{"name":"email","description":"E-Mail des Kunden","required":true}]}'
Antwort · 200 
{
  "id": "3c...",
  "name": "bestellstatus",
  "signingSecret": "whsec_..."
}
GET /v1/tools/{id} tools:read

Tool lesen

Ein einzelnes Tool.

Parameter
id Pflicht
uuid · path

Tool-UUID.

curl -X GET "https://api.ragnova.de/v1/tools/b1e5f2a0-..." \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "id": "3c...",
  "name": "bestellstatus",
  "endpoint_url": "https://shop.de/api/ragnova/order",
  "method": "POST",
  "enabled": true
}
PATCH /v1/tools/{id} tools:write

Tool ändern

Partielles Update; nur gesendete Felder werden geändert (inkl. enabled-Toggle).

Parameter
id Pflicht
uuid · path

Tool-UUID.

curl -X PATCH "https://api.ragnova.de/v1/tools/b1e5f2a0-..." \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
Antwort · 200 
{
  "ok": true
}
DELETE /v1/tools/{id} tools:write

Tool löschen

Entfernt das Tool.

Parameter
id Pflicht
uuid · path

Tool-UUID.

curl -X DELETE "https://api.ragnova.de/v1/tools/b1e5f2a0-..." \
  -H "Authorization: Bearer rk_live_..."
Antwort · 200 
{
  "ok": true
}

Webhooks — Tool-Aufruf verifizieren

Löst der Bot ein registriertes Live-Tool aus, sendet Ragnova einen POST an deine endpointUrl. Verifiziere die Signatur, bevor du antwortest. Antworte mit JSON (≤ 32 KB) innerhalb deines Timeouts — der Inhalt wird dem Bot als geprüfter Kontext bereitgestellt.

Signatur 
X-Ragnova-Signature = "sha256=" + HMAC_SHA256(signingSecret, timestamp + "." + body)
Verifikation · Node.js 
import crypto from "node:crypto";

function verify(req, signingSecret) {
  const ts = req.headers["x-ragnova-timestamp"];
  const sig = req.headers["x-ragnova-signature"];
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", signingSecret)
      .update(ts + "." + req.rawBody)
      .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
Vollständige, maschinenlesbare Spezifikation: openapi.v1.yaml — importierbar in Postman, Insomnia oder zum Client-Codegen.