# Core-API-Referenz für Module

*(Quelle: `docs/core/core-api-implementation-plan.md` §3a/§9, `docs/core/hubrobotix-manifest.md`
Gesetz 1/2, interne Server-Details entfernt)*

## Grundprinzip

Dein Modul-Code hält **nie** ein Datenbank-Passwort — auch nicht für dein eigenes Schema. Jeder
Datenzugriff läuft über HTTP-Aufrufe gegen die Core-API, authentifiziert mit einem
**pro-Modul-scoped Token** (`Authorization: Bearer <token>` + `X-Module-Key: <dein_module_key>`).

## Zwei Endpunkt-Familien

### 1. `mod/data/*` — deine eigenen Tabellen

Eine generische, auf dein eigenes Schema (`mod_<dein_key>`) beschränkte Endpunkt-Familie für
CRUD auf deinen eigenen Tabellen. Dein Token kann ausschließlich auf `mod_<dein_key>.*` zugreifen —
selbst ein Bug in deinem Code kann nie eine fremde Tabelle erreichen (das ist keine reine
Anwendungslogik-Prüfung, sondern serverseitig auf Datenbank-Rollen-Ebene erzwungen).

### 2. Freigegebene Querschnittsdienste

Für Funktionen, die dein Modul braucht, die aber Core-Daten betreffen (kein eigenes Schema):

| Endpunkt | Zweck |
|---|---|
| `auth/verify` | JWT-Verifikation eines eingeloggten Nutzers |
| `llm/complete` | KI-Vervollständigung (Anthropic/OpenAI/Ollama je nach Mandanten-Konfiguration) |
| `prompt/get` | Lädt einen deklarierten Prompt-Text (System-Standard oder Mandanten-Override) |
| `authz/check` | Prüft Modul-Freischaltung + Nutzerrechte für den aktuellen Request |
| `template/render` | Rendert ein E-Mail-Template mit Platzhaltern |
| `email/send` | Versendet eine E-Mail über den zentralen SMTP-Dienst |
| `log/write` | Schreibt einen strukturierten Log-Eintrag |

**Wichtig:** Für komplexere eigene Server-Logik (Joins, Transaktionen über mehrere eigene Tabellen,
eigene Business-Regeln) gibt es **keinen** bespoken Custom-Endpunkt in der Core-API — diese Logik
gehört in deinen eigenen Workflow/Dienst, der mehrere `mod/data/*`-Aufrufe kombiniert.

## Fehlerbehandlung

Jede Antwort mit HTTP-Status ≥ 400 enthält `{ "error": "<Nachricht>" }`. Statuscode 5xx zeigt einen
internen Fehler an unsererseits (dein Modul sollte das nicht als Nutzerfehler behandeln), 4xx zeigt
einen Fehler auf deiner Seite (falscher Scope, ungültige Parameter etc.).

## Contract-Versionierung

Die Core-API-Endpunkte stehen unter `/v1/...`. Dein `manifest.json` deklariert `"api_contract": "v1"`
— ein zukünftiger `/v2`-Bruch wird rechtzeitig angekündigt und betrifft dich nur, wenn du selbst auf
`v2` migrierst.

Weiter mit [03-security-rules.md](03-security-rules.md).