REST- und MCP-API

Voraussetzungen

• knowmind-Konto — der API-/CLI-Zugang ist in jedem Tarif enthalten, auch im kostenlosen Privat-Tarif
• 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

   Beispiel: Suche und Speichern über MCP

   Für Suche und Anlage mit einem API-Token ist der MCP-Endpunkt /api/mcp/v1 der verlässliche Weg (Tool-Aufrufe per JSON-RPC 2.0).

   curl:

   bashkopieren

   # Suchen (MCP tools/call → knowmind_recall)
   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/call",
       "params": {
         "name": "knowmind_recall",
         "arguments": {
           "query": "Wer ist Ansprechpartnerin für die Einarbeitung?",
           "k": 5,
           "hops": 2
         }
       }
     }'
   
   # Erinnerung anlegen (MCP tools/call → knowmind_store_memory)
   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_store_memory",
         "arguments": {
           "title": "QM-Schulung Pflicht",
           "content": "Alle Service-Mitarbeitenden absolvieren die QM-Schulung jährlich.",
           "memory_type": "semantic",
           "tags": ["qm", "schulung"],
           "source": "internal-handbook"
         }
       }
     }'

   TypeScript (Node 20+):

   tskopieren

   const TOKEN = process.env.KNOWMIND_TOKEN!;
   const MCP = "https://knowmind.de/api/mcp/v1";
   
   async function recall(query: string, k = 5) {
     const r = await fetch(MCP, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${TOKEN}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
         method: "tools/call",
         params: { name: "knowmind_recall", arguments: { query, k, hops: 2 } },
       }),
     });
     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"]
   MCP = "https://knowmind.de/api/mcp/v1"
   HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
   
   def recall(query: str, k: int = 5) -> dict:
       r = requests.post(
           MCP,
           headers=HEADERS,
           json={
               "jsonrpc": "2.0",
               "id": 1,
               "method": "tools/call",
               "params": {"name": "knowmind_recall", "arguments": {"query": query, "k": k, "hops": 2}},
           },
           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

   Anfragen pro Minute je Tarif: Privat 30, Pro 60, Team 120, Business 120, 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