🔌 API-Referenz

Authentifizierung

Alle Endpunkte außer /health erfordern Authentifizierung per API-Key im HTTP-Header:

Authorization: Bearer <dein-api-key>

Den API-Key findest und konfigurierst du unter Einstellungen → Sicherheit im Dashboard. Alternativ kann er in config.yaml gesetzt werden:

api:
  key: "dein-geheimer-api-key"

Chat

POST /chat

Sendet eine Nachricht und erhält eine vollständige Antwort (blocking).

Request Body (JSON):

{
  "message":     "Erkläre mir Quantenverschränkung.",
  "session_id":  "abc123",          // optional — leer = neue Sitzung
  "use_network": false,             // optional — Netzwerk-Routing aktivieren
  "temperature": 0.7,               // optional
  "max_tokens":  1024               // optional
}

Response (JSON):

{
  "response":    "Quantenverschränkung ist...",
  "session_id":  "abc123",
  "tokens_used": 312,
  "model":       "qwen2.5-7b-q4_k_m.gguf",
  "from_cache":  false,
  "from_peer":   null
}

POST /chat/stream

Wie /chat, aber als Server-Sent Events (SSE) — Antwort wird gestreamt.

Content-Type: text/event-stream

data: {"delta": "Quanten"}
data: {"delta": "ver"}
data: {"delta": "schränkung..."}
data: {"done": true, "tokens_used": 312}

WebSocket

WS /ws

Bidirektionale WebSocket-Verbindung für das Dashboard. Nach Verbindungsaufbau muss ein Auth-Frame gesendet werden:

// Verbindung
ws = new WebSocket("ws://127.0.0.1:8420/ws");

// Authentifizieren
ws.send(JSON.stringify({"type": "auth", "key": "dein-api-key"}));

// Chat-Nachricht senden
ws.send(JSON.stringify({
  "type":       "chat",
  "message":    "Hallo!",
  "session_id": "abc123"
}));

// Eingehende Events
// {"type": "stream_delta",  "delta": "Hallo, "}
// {"type": "stream_done",   "tokens_used": 12}
// {"type": "status",        "cpu": 34, "ram_mb": 4200, ...}
// {"type": "peer_update",   "peers": [...]}

Event-Typen (Server → Client)

Node-Status

GET /status

Gibt den aktuellen Status des Nodes zurück.

{
  "version":       "1.2.2",
  "uptime_s":      3640,
  "model":         "qwen2.5-7b-q4_k_m.gguf",
  "context_len":   32768,
  "gpu_layers":    35,
  "cpu_pct":       12.4,
  "ram_mb":        5120,
  "vram_mb":       6200,
  "peers_active":  4,
  "cache_hits":    142,
  "cache_misses":  38,
  "requests_total":180
}

GET /health

Einfacher Health-Check, keine Authentifizierung erforderlich.

{"status": "ok", "version": "1.2.2"}

Netzwerk

GET /network/peers

Liste aller verbundenen Peers.

[{
  "peer_id":        "QmXyZ...",
  "display_name":   "Node-42",
  "ping_ms":        34,
  "specializations":{"math": 0.87, "code": 0.61},
  "relay":          false
}, ...]

POST /network/connect

Verbindung zu einem neuen Peer herstellen.

{"peer_id": "QmXyZ..."}

DELETE /network/peers/{peer_id}

Verbindung zu einem Peer trennen.

Memory

GET /memory

Alle gespeicherten Memories abrufen. Optional: ?q=suchbegriff für semantische Suche.

POST /memory

{"content": "Mein Name ist Max.", "importance": 0.8}

DELETE /memory/{id}

Einen Memory-Eintrag löschen.

RAG

GET /rag/sources

Alle RAG-Quellen auflisten.

POST /rag/upload

Multipart-Form-Upload: Feld file mit Dokument. Optionale Felder: title, source_type (pdf|txt|url).

DELETE /rag/sources/{id}

Eine RAG-Quelle und ihre Vektoren löschen.

POST /rag/query

Direkte semantische Suche in der RAG-Wissensbasis ohne KI-Antwort.

{"query": "Quantencomputer", "top_k": 5}

Plugins

GET /plugins

Liste aller installierten Plugins mit Status.

POST /plugins/{name}/enable

POST /plugins/{name}/disable

POST /plugins/install

{"source": "https://github.com/user/hivemind-plugin-xyz"}

Sitzungen

GET /sessions

Alle gespeicherten Chat-Sitzungen (Metadaten, kein Verlauf).

GET /sessions/{id}/messages

Vollständiger Nachrichtenverlauf einer Sitzung.

DELETE /sessions/{id}

Eine Sitzung löschen.

Fehlercodes