mindnet/docs/03_Technical_References/03_tech_api_reference.md

---
doc_type: technical_reference
audience: developer, integrator
scope: api, endpoints, integration
status: active
version: 2.9.1
context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung."
---

# API Reference

Diese Dokumentation beschreibt alle verfügbaren API-Endpunkte von Mindnet. Die API basiert auf FastAPI und nutzt automatische OpenAPI-Dokumentation (verfügbar unter `/docs`).

## Basis-URL

```
http://localhost:8001  # Production
http://localhost:8002  # Development
```

## Health Check

### `GET /healthz`

Prüft den Status der API und der Verbindung zu Qdrant.

**Response:**
```json
{
  "status": "ok",
  "qdrant": "http://localhost:6333",
  "prefix": "mindnet"
}
```

---

## Query Endpoints

### `POST /query`

Führt eine hybride oder semantische Suche im Wissensgraph durch.

**Request Body:**
```json
{
  "query": "Was ist Mindnet?",
  "mode": "hybrid",  // "hybrid" oder "semantic"
  "top_k": 10,
  "expand_depth": 1,
  "explain": true
}
```

**Response:**
```json
{
  "query_id": "uuid-v4",
  "hits": [
    {
      "chunk_id": "uuid",
      "note_id": "uuid",
      "text": "Auszug...",
      "score": 0.85,
      "explanation": {
        "reasons": [...]
      }
    }
  ],
  "stats": {
    "total_hits": 10,
    "query_time_ms": 45
  }
}
```

**Hinweis:** Das Feedback-Logging erfolgt asynchron im Hintergrund (Background Tasks).

---

## Chat Endpoints

### `POST /chat/`

Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming.

**Request Body:**
```json
{
  "message": "Was ist Mindnet?",
  "history": [],  // Optional: Chat-Verlauf
  "stream": true   // Optional: SSE-Streaming
}
```

**Response (Non-Streaming):**
```json
{
  "intent": "FACT",
  "response": "Mindnet ist ein persönliches KI-Gedächtnis...",
  "sources": [...],
  "query_id": "uuid"
}
```

**Response (Streaming):**
Server-Sent Events (SSE) mit Chunks der Antwort.

**Intent-Typen:**
- `FACT`: Wissensabfrage
- `DECISION`: Entscheidungsfrage
- `EMPATHY`: Emotionale Anfrage
- `INTERVIEW`: Wissen erfassen

---

## Graph Endpoints

### `GET /graph/{note_id}`

Lädt den Subgraphen um eine Note herum.

**Query Parameters:**
- `depth` (int, default: 1): Tiefe der Graph-Expansion
- `edge_types` (List[str], optional): Filter für Kanten-Typen

**Response:**
```json
{
  "center_note_id": "uuid",
  "nodes": [
    {
      "id": "uuid",
      "type": "project",
      "title": "Projekt Alpha",
      "tags": ["ki"],
      "in_degree": 5,
      "out_degree": 3
    }
  ],
  "edges": [
    {
      "id": "uuid->uuid:depends_on",
      "kind": "depends_on",
      "source": "uuid",
      "target": "uuid",
      "target_section": "P3 – Disziplin",  // Optional: Abschnitts-Name bei Deep-Links
      "weight": 1.4,
      "direction": "out",
      "provenance": "explicit",
      "confidence": 1.0
    }
  ],
  "stats": {
    "node_count": 10,
    "edge_count": 15
  }
}
```

---

## Ingest Endpoints

### `POST /ingest/analyze`

Analysiert einen Text-Draft und liefert Link-Vorschläge (Intelligence-Feature).

**Request Body:**
```json
{
  "text": "Markdown-Text...",
  "type": "concept"  // Optional: Notiz-Typ
}
```

**Response:**
```json
{
  "suggestions": [
    {
      "text": "Mindnet",
      "type": "exact_match",
      "note_id": "uuid",
      "confidence": 0.95
    },
    {
      "text": "KI-Gedächtnis",
      "type": "semantic",
      "note_id": "uuid",
      "confidence": 0.82
    }
  ]
}
```

### `POST /ingest/save`

Speichert eine Notiz und startet die Ingestion im Hintergrund (WP-14: Background Tasks).

**Request Body:**
```json
{
  "markdown_content": "---\nid: ...\n---\n# Titel\n...",
  "filename": "meine-notiz.md",  // Optional
  "folder": "00_Inbox"            // Optional, default: "00_Inbox"
}
```

**Response:**
```json
{
  "status": "queued",
  "file_path": "00_Inbox/meine-notiz.md",
  "note_id": "pending",
  "message": "Speicherung & Hybrid-KI-Analyse (WP-20) im Hintergrund gestartet.",
  "stats": {
    "chunks": -1,  // -1 = Async Processing
    "edges": -1
  }
}
```

**Wichtig:** 
- Die Datei wird sofort auf der Festplatte gespeichert
- Die Ingestion (Chunking, Embedding, Smart Edges) läuft asynchron im Hintergrund
- Dies verhindert Timeouts bei großen Dateien oder langsamen LLM-Calls

---

## Feedback Endpoints

### `POST /feedback`

Nimmt explizites User-Feedback entgegen (WP-04c).

**Request Body:**
```json
{
  "query_id": "uuid",
  "rating": 5,  // 1-5 Sterne
  "feedback_type": "global",  // "global" oder "granular"
  "chunk_id": "uuid"  // Optional für granular feedback
}
```

**Response:**
```json
{
  "status": "recorded",
  "query_id": "uuid"
}
```

---

## Tools Endpoints

### `GET /tools/ollama`

Liefert JSON-Schemas für die Integration als Tools in externe Agenten (Ollama, OpenAI, etc.).

**Response:**
```json
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "mindnet_query",
        "description": "Hybrid-Retrieval über mindnet (Semantik + Edges).",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Freitext-Query"
            },
            "top_k": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            }
          }
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "mindnet_subgraph",
        "description": "Gibt die Nachbarschaft (Edges) einer Note/Seed-ID zurück.",
        "parameters": {
          "type": "object",
          "properties": {
            "note_id": {
              "type": "string"
            },
            "depth": {
              "type": "integer",
              "default": 1,
              "minimum": 0,
              "maximum": 3
            }
          },
          "required": ["note_id"]
        }
      }
    }
  ]
}
```

**Verwendung:** Diese Schemas können direkt in Ollama-Function-Calling oder OpenAI-Tools integriert werden.

---

## Admin Endpoints

### `GET /admin/stats`

Liefert Statistiken über die Qdrant-Collections und die aktuelle Konfiguration.

**Response:**
```json
{
  "collections": {
    "notes": {
      "name": "mindnet_notes",
      "count": 150
    },
    "chunks": {
      "name": "mindnet_chunks",
      "count": 1250
    },
    "edges": {
      "name": "mindnet_edges",
      "count": 3200
    }
  },
  "config": {
    "qdrant": "http://localhost:6333",
    "prefix": "mindnet",
    "vector_size": 768,
    "distance": "Cosine",
    "retriever": {
      "w_sem": 0.70,
      "w_edge": 0.25,
      "w_cent": 0.05,
      "top_k": 10,
      "expand_depth": 1
    }
  }
}
```

**Hinweis:** Dieser Endpunkt ist optional und kann deaktiviert sein, wenn der `admin`-Router nicht geladen wird.

---

## Fehlerbehandlung

Alle Endpunkte verwenden standardisierte HTTP-Status-Codes:

- `200 OK`: Erfolgreiche Anfrage
- `201 Created`: Ressource erfolgreich erstellt
- `400 Bad Request`: Ungültige Anfrage (z.B. fehlende Parameter)
- `500 Internal Server Error`: Server-Fehler

**Fehler-Response-Format:**
```json
{
  "detail": "Fehlerbeschreibung"
}
```

---

## Rate Limiting & Timeouts

- **Chat-Endpunkte:** Keine Retries (max_retries=0) für schnelle Fallback-Kaskade
- **Ingest-Endpunkte:** Background Tasks verhindern Timeouts
- **Query-Endpunkte:** Standard-Timeout konfigurierbar via `MINDNET_API_TIMEOUT`

---

## OpenAPI Dokumentation

Die vollständige interaktive API-Dokumentation ist verfügbar unter:
- Swagger UI: `http://localhost:8001/docs`
- ReDoc: `http://localhost:8001/redoc`
- OpenAPI JSON: `http://localhost:8001/openapi.json`

---

## Integration Beispiele

### Python (requests)

```python
import requests

# Query
response = requests.post(
    "http://localhost:8001/query",
    json={"query": "Was ist Mindnet?", "top_k": 5}
)
print(response.json())

# Chat
response = requests.post(
    "http://localhost:8001/chat/",
    json={"message": "Erkläre mir Mindnet"}
)
print(response.json())
```

### cURL

```bash
# Health Check
curl http://localhost:8001/healthz

# Query
curl -X POST http://localhost:8001/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Was ist Mindnet?", "top_k": 5}'
```

---

## Weitere Informationen

- **Chat-Backend Details:** Siehe [Chat Backend Dokumentation](03_tech_chat_backend.md)
- **Ingestion-Pipeline:** Siehe [Ingestion Pipeline](03_tech_ingestion_pipeline.md)
- **Retrieval & Scoring:** Siehe [Retrieval & Scoring](03_tech_retrieval_scoring.md)