REST- und MCP-API

Voraussetzungen

• knowmind-Konto im Tarif Business API oder Enterprise (für eigene API-Tokens und Rate-Limit ab 60 Anfragen pro Minute)
• API-Token im Format kmt_… (Anleitung: API-Token erstellen)
• TLS-fähiger HTTP-Client in Ihrer Wahl-Sprache

Schritte

1. 1

   Endpunkt und Authentifizierung

   Alle Anfragen gehen gegen https://knowmind.de. Die Authentifizierung erfolgt über den Authorization: Bearer kmt_… Header.

   textkopieren

   REST:   https://knowmind.de/api/v1/...
   MCP:    https://knowmind.de/api/mcp/v1
   Auth:   Authorization: Bearer kmt_…

   Ergebnis: curl -H "Authorization: Bearer kmt_…" https://knowmind.de/api/health liefert eine Erfolgsmeldung.

2. 2

   REST-Beispiel: Suche und Speichern

   curl:

   bashkopieren

   # Suchen
   curl -X POST https://knowmind.de/api/v1/memory/recall \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "Wer ist Ansprechpartnerin für die Einarbeitung?",
       "k": 5,
       "hops": 2,
       "use_graph": true
     }'
   
   # Erinnerung anlegen
   curl -X POST https://knowmind.de/api/v1/memory/entries \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "memory_type": "semantic",
       "title": "QM-Schulung Pflicht",
       "content": "Alle Service-Mitarbeitenden absolvieren die QM-Schulung jährlich.",
       "tags": ["qm", "schulung"],
       "source": "internal-handbook"
     }'

   TypeScript (Node 20+):

   tskopieren

   const TOKEN = process.env.KNOWMIND_TOKEN!;
   const BASE = "https://knowmind.de/api/v1";
   
   async function recall(query: string, k = 5) {
     const r = await fetch(`${BASE}/memory/recall`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${TOKEN}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({ query, k, hops: 2, use_graph: true }),
     });
     if (!r.ok) throw new Error(`recall failed: ${r.status}`);
     return r.json();
   }
   
   const hits = await recall("Wer hat den Müller-Vertrag verfasst?");
   console.log(hits);

   Python:

   pythonkopieren

   import os, requests
   
   TOKEN = os.environ["KNOWMIND_TOKEN"]
   BASE = "https://knowmind.de/api/v1"
   HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
   
   def recall(query: str, k: int = 5) -> dict:
       r = requests.post(
           f"{BASE}/memory/recall",
           headers=HEADERS,
           json={"query": query, "k": k, "hops": 2, "use_graph": True},
           timeout=10,
       )
       r.raise_for_status()
       return r.json()
   
   print(recall("DSGVO-Schulung Pflicht?"))

3. 3

   MCP-Beispiel: JSON-RPC 2.0

   MCP-Aufrufe sind JSON-RPC-2.0-Anfragen an /api/mcp/v1. Standardmäßig wird eine einmalige JSON-Antwort geliefert. Wer Streamable-HTTP braucht (für native Custom Connectoren), setzt Accept: text/event-stream.

   bashkopieren

   # Tools auflisten
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   
   # Recall aufrufen
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/call",
       "params": {
         "name": "knowmind.recall",
         "arguments": { "query": "Wann ist der nächste Quartalsbericht fällig?", "k": 5 }
       }
     }'

   Ergebnis: Antwort ist ein JSON-RPC-Response-Objekt mit result (bei Erfolg) oder error (bei Fehler).

4. 4

   Rate-Limits beachten

   Tarif Business API: 60 Anfragen pro Minute. Tarif Enterprise: 600. Überschreitungen liefern HTTP 429 mit Retry-After-Header in Sekunden.

   Setzen Sie in eigenen Clients einen Backoff-Mechanismus ein, der bei 429 wartet und erneut versucht. Im Pseudo-Code: lesen Sie Retry-After, warten Sie die angegebene Anzahl Sekunden (mit Jitter), wiederholen Sie die Anfrage maximal dreimal.

Prüfung des Ergebnisses

Fehlerbehebung