BreakPilot Developer Portal

Uebersicht

Das Training-Modul bietet ein vollstaendiges Compliance-Schulungssystem mit:

Modulverwaltung mit Regulierungsbereichen (DSGVO, NIS2, ISO 27001, AI Act, GeschGehG, HinSchG)
Compliance Training Matrix (CTM) — rollenbasierte Zuweisung
KI-gestuetzte Content- und Quiz-Generierung
Audio/Video-Schulungsinhalte via TTS
Quiz-Engine mit Bestehens-Schwelle
Eskalationsstufen (7/14/30/45 Tage)
PDF-Zertifikate nach Schulungsabschluss
Training Blocks — automatische Modul-Erstellung aus Canonical Controls

Basis-URL

Alle Endpoints nutzen den Prefix /sdk/v1/training. Authentifizierung via X-Tenant-ID und X-User-ID Header.

1. Module

Schulungsmodule sind die zentrale Einheit des Training-Systems.

GET/sdk/v1/training/modules

Alle Module auflisten (mit optionalen Filtern)

Parameter	Type	Required	Description
`regulation_area`	`string`	No	Filter: dsgvo, nis2, iso27001, ai_act, geschgehg, hinschg
`frequency_type`	`string`	No	Filter: onboarding, annual, event_trigger, micro
`search`	`string`	No	Volltextsuche in Titel und Beschreibung

GET/sdk/v1/training/modules/:id

Einzelnes Modul mit Content und Quiz-Fragen laden

POST/sdk/v1/training/modules

Neues Schulungsmodul erstellen

Parameter	Type	Required	Description
`module_code`	`string`	Yes	Eindeutiger Modulcode (z.B. CP-TRAIN-001)
`title`	`string`	Yes	Titel des Moduls
`description`	`string`	No	Beschreibung
`regulation_area`	`string`	Yes	Regulierungsbereich
`frequency_type`	`string`	Yes	Schulungsfrequenz
`duration_minutes`	`integer`	No	Dauer in Minuten (Standard: 30)
`pass_threshold`	`integer`	No	Quiz-Bestehensgrenze in Prozent (Standard: 70)

PUT/sdk/v1/training/modules/:id

Modul aktualisieren

DELETE/sdk/v1/training/modules/:id

Modul loeschen

// POST /sdk/v1/training/modules — Beispiel
{
  "module_code": "CP-DSGVO-001",
  "title": "DSGVO Grundlagen fuer Mitarbeiter",
  "description": "Einfuehrung in die Datenschutz-Grundverordnung",
  "regulation_area": "dsgvo",
  "frequency_type": "annual",
  "duration_minutes": 30,
  "pass_threshold": 70
}

2. Compliance Training Matrix (CTM)

Die CTM ordnet Rollen zu Schulungsmodulen zu. 10 vordefinierte Rollen (R1–R10).

GET/sdk/v1/training/matrix

Vollstaendige Training-Matrix abrufen (alle Rollen → Module)

GET/sdk/v1/training/matrix/:role

Module fuer eine bestimmte Rolle abrufen

POST/sdk/v1/training/matrix

Matrix-Eintrag setzen (Rolle → Modul)

Parameter	Type	Required	Description
`role_code`	`string`	Yes	Rollencode (R1–R10)
`module_id`	`uuid`	Yes	Modul-UUID
`is_mandatory`	`boolean`	No	Pflichtschulung (Standard: false)
`priority`	`integer`	No	Prioritaet (1 = hoechste)

DELETE/sdk/v1/training/matrix/:role/:moduleId

Matrix-Eintrag entfernen

Rollen

R1: Geschaeftsfuehrung, R2: IT-Leitung, R3: DSB, R4: ISB, R5: HR, R6: Einkauf, R7: Fachabteilung, R8: IT-Admin, R9: Alle Mitarbeiter, R10: Behoerden

3. Zuweisungen

Zuweisungen verbinden Mitarbeiter mit Schulungsmodulen und tracken den Fortschritt.

POST/sdk/v1/training/assignments/compute

Zuweisungen fuer einen Benutzer berechnen (basierend auf Rollen + CTM)

Parameter	Type	Required	Description
`user_id`	`uuid`	Yes	Benutzer-UUID
`user_name`	`string`	Yes	Name des Benutzers
`user_email`	`string`	Yes	E-Mail
`roles`	`string[]`	Yes	Rollencodes des Benutzers
`trigger`	`string`	No	Ausloeser: onboarding, annual, event, manual

GET/sdk/v1/training/assignments

Zuweisungen auflisten

Parameter	Type	Required	Description
`user_id`	`uuid`	No	Filter nach Benutzer
`module_id`	`uuid`	No	Filter nach Modul
`role`	`string`	No	Filter nach Rolle
`status`	`string`	No	Filter: pending, in_progress, completed, overdue, expired
`limit`	`integer`	No	Pagination (Standard: 50)
`offset`	`integer`	No	Pagination Offset

GET/sdk/v1/training/assignments/:id

Einzelne Zuweisung laden

PUT/sdk/v1/training/assignments/:id

Zuweisung aktualisieren (z.B. Deadline aendern)

POST/sdk/v1/training/assignments/:id/start

Schulung starten (Status → in_progress)

POST/sdk/v1/training/assignments/:id/progress

Fortschritt aktualisieren (0–100%)

POST/sdk/v1/training/assignments/:id/complete

Schulung abschliessen (Status → completed)

// POST /sdk/v1/training/assignments/compute — Response
{
  "assignments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "module_id": "...",
      "user_id": "...",
      "status": "pending",
      "progress_percent": 0,
      "deadline": "2026-04-15T00:00:00Z",
      "escalation_level": 0
    }
  ],
  "created": 5
}

4. Quiz-Engine

Multiple-Choice-Quiz mit automatischer Bewertung und Bestehensgrenze.

GET/sdk/v1/training/quiz/:moduleId

Quiz-Fragen fuer ein Modul abrufen

POST/sdk/v1/training/quiz/:moduleId/submit

Quiz-Antworten einreichen

Parameter	Type	Required	Description
`assignment_id`	`uuid`	Yes	Zuweisungs-UUID
`answers`	`QuizAnswer[]`	Yes	Array von {question_id, selected_index}
`duration_seconds`	`integer`	No	Bearbeitungsdauer in Sekunden

GET/sdk/v1/training/quiz/attempts/:assignmentId

Quiz-Versuche fuer eine Zuweisung anzeigen

// POST /sdk/v1/training/quiz/:moduleId/submit — Response
{
  "attempt_id": "...",
  "score": 80.0,
  "passed": true,
  "correct_count": 4,
  "total_count": 5,
  "threshold": 70
}

5. KI-Content-Generierung

LLM-basierte Erstellung von Schulungsinhalten und Quiz-Fragen.

POST/sdk/v1/training/content/generate

Schulungsinhalt fuer ein Modul generieren (Markdown)

Parameter	Type	Required	Description
`module_id`	`uuid`	Yes	Modul-UUID
`language`	`string`	No	Sprache: de (Standard) oder en

POST/sdk/v1/training/content/generate-quiz

Quiz-Fragen fuer ein Modul generieren

Parameter	Type	Required	Description
`module_id`	`uuid`	Yes	Modul-UUID
`count`	`integer`	No	Anzahl Fragen (Standard: 5)

GET/sdk/v1/training/content/:moduleId

Veroeffentlichten Content eines Moduls abrufen

POST/sdk/v1/training/content/:contentId/publish

Content veroeffentlichen (Freigabe)

POST/sdk/v1/training/content/generate-all

Content fuer alle Module ohne Content generieren (Bulk)

POST/sdk/v1/training/content/generate-all-quiz

Quiz fuer alle Module ohne Fragen generieren (Bulk)

LLM-Kosten

Content- und Quiz-Generierung nutzt LLM-APIs (Ollama/Anthropic). Bulk-Generierung kann signifikante Token-Kosten verursachen. PII-Detektion ist aktiv — personenbezogene Daten werden automatisch redaktiert.

6. Media (Audio/Video)

TTS-basierte Audio- und Videogenerierung fuer Schulungsmodule.

POST/sdk/v1/training/content/:moduleId/generate-audio

Audio-Datei aus Schulungsinhalt generieren (Piper TTS)

POST/sdk/v1/training/content/:moduleId/generate-video

Praesentationsvideo generieren (TTS + Folien)

POST/sdk/v1/training/content/:moduleId/preview-script

Video-Script als JSON-Vorschau generieren

GET/sdk/v1/training/media/module/:moduleId

Alle Medien eines Moduls auflisten

GET/sdk/v1/training/media/:mediaId/url

Metadaten (Bucket, Object Key) fuer eine Media-Datei

POST/sdk/v1/training/media/:mediaId/publish

Media veroeffentlichen/zurueckziehen

GET/sdk/v1/training/media/:mediaId/stream

Media streamen (307-Redirect zu Presigned URL)

Streaming

Der /stream-Endpoint liefert einen 307 Temporary Redirect zu einer zeitlich begrenzten Presigned URL (MinIO/S3). Browser und Audio/Video-Player folgen dem Redirect automatisch.

// POST /sdk/v1/training/content/:moduleId/preview-script — Response
{
  "title": "DSGVO Grundlagen",
  "sections": [
    {
      "heading": "Was ist die DSGVO?",
      "text": "Die DSGVO regelt den Umgang mit personenbezogenen Daten.",
      "bullet_points": [
        "Gilt seit 25. Mai 2018",
        "EU-weit verbindlich",
        "Hohe Bussgelder bei Verstoessen"
      ]
    }
  ]
}

7. Deadlines & Eskalation

Automatisches Eskalationssystem mit 4 Stufen.

GET/sdk/v1/training/deadlines

Anstehende Deadlines auflisten

Parameter	Type	Required	Description
`limit`	`integer`	No	Maximale Anzahl (Standard: 50)

GET/sdk/v1/training/deadlines/overdue

Ueberfaellige Zuweisungen auflisten

POST/sdk/v1/training/escalation/check

Eskalationspruefung ausfuehren

// POST /sdk/v1/training/escalation/check — Response
{
  "results": [
    {
      "assignment_id": "...",
      "user_name": "Max Mustermann",
      "module_title": "DSGVO Grundlagen",
      "previous_level": 1,
      "new_level": 2,
      "days_overdue": 15,
      "escalation_label": "Benachrichtigung Teamleitung"
    }
  ],
  "total_checked": 42,
  "escalated": 3
}

Parameter	Type	Required	Description
`Stufe 1 (7 Tage)`	`-`	No	Erinnerung an Mitarbeiter
`Stufe 2 (14 Tage)`	`-`	No	Benachrichtigung Teamleitung
`Stufe 3 (30 Tage)`	`-`	No	Benachrichtigung Management
`Stufe 4 (45 Tage)`	`-`	No	Benachrichtigung Compliance Officer

8. Zertifikate

PDF-Zertifikate nach erfolgreichem Schulungsabschluss.

POST/sdk/v1/training/certificates/generate/:assignmentId

Zertifikat fuer eine abgeschlossene Zuweisung generieren

GET/sdk/v1/training/certificates

Alle Zertifikate des Tenants auflisten

GET/sdk/v1/training/certificates/:id/pdf

Zertifikat als PDF herunterladen

GET/sdk/v1/training/certificates/:id/verify

Zertifikat verifizieren (z.B. fuer Audit)

Voraussetzungen

Zertifikate koennen nur generiert werden, wenn die Zuweisung den Status completed hat UND das Quiz bestanden wurde (quiz_passed = true).

// POST /sdk/v1/training/certificates/generate/:assignmentId — Response
{
  "certificate_id": "a1b2c3d4-...",
  "assignment": {
    "id": "...",
    "status": "completed",
    "quiz_passed": true,
    "certificate_id": "a1b2c3d4-...",
    "module_title": "DSGVO Grundlagen"
  }
}

// GET /sdk/v1/training/certificates/:id/verify — Response
{
  "valid": true,
  "assignment": { ... }
}

9. Audit & Statistiken

Compliance-konformes Audit-Logging aller Schulungsaktivitaeten.

GET/sdk/v1/training/audit-log

Audit-Log abrufen

Parameter	Type	Required	Description
`action`	`string`	No	Filter: assigned, started, completed, quiz_submitted, escalated, certificate_issued, content_generated
`entity_type`	`string`	No	Filter: assignment, module, quiz, certificate
`limit`	`integer`	No	Pagination (Standard: 50)
`offset`	`integer`	No	Pagination Offset

GET/sdk/v1/training/stats

Aggregierte Schulungsstatistiken

// GET /sdk/v1/training/stats — Response
{
  "total_modules": 28,
  "total_assignments": 156,
  "completion_rate": 72.5,
  "overdue_count": 8,
  "pending_count": 23,
  "in_progress_count": 14,
  "completed_count": 111,
  "avg_quiz_score": 81.3,
  "avg_completion_days": 4.2,
  "upcoming_deadlines": 12
}

10. Training Blocks (Controls → Module)

Training Blocks automatisieren die Erstellung von Schulungsmodulen aus Canonical Controls. Ein Block definiert Filter (Domain, Kategorie, Severity, Zielgruppe) und generiert automatisch Module, Content und CTM-Eintraege.

GET/sdk/v1/training/blocks

Alle Block-Konfigurationen auflisten

POST/sdk/v1/training/blocks

Neue Block-Konfiguration erstellen

Parameter	Type	Required	Description
`name`	`string`	Yes	Name des Blocks
`description`	`string`	No	Beschreibung
`domain_filter`	`string`	No	Domain-Filter (z.B. AUTH, CRYP, NET)
`category_filter`	`string`	No	Kategorie-Filter (z.B. authentication, encryption)
`severity_filter`	`string`	No	Severity-Filter (high, critical)
`target_audience_filter`	`string`	No	Zielgruppe: enterprise, authority, provider, all
`regulation_area`	`string`	Yes	Regulierungsbereich
`module_code_prefix`	`string`	Yes	Prefix fuer generierte Modulcodes
`frequency_type`	`string`	No	Schulungsfrequenz
`duration_minutes`	`integer`	No	Dauer pro Modul
`pass_threshold`	`integer`	No	Quiz-Bestehensgrenze
`max_controls_per_module`	`integer`	No	Max. Controls pro Modul (Standard: 10)

GET/sdk/v1/training/blocks/:id

Block-Konfiguration laden

PUT/sdk/v1/training/blocks/:id

Block-Konfiguration aktualisieren

DELETE/sdk/v1/training/blocks/:id

Block-Konfiguration loeschen

POST/sdk/v1/training/blocks/:id/preview

Vorschau: Welche Controls und Module wuerden generiert?

POST/sdk/v1/training/blocks/:id/generate

Module aus Block generieren (Content + CTM)

Parameter	Type	Required	Description
`language`	`string`	No	Sprache: de (Standard) oder en
`auto_matrix`	`boolean`	No	Automatisch CTM-Eintraege erstellen (Standard: true)

GET/sdk/v1/training/blocks/:id/controls

Verlinkte Controls eines Blocks anzeigen

// POST /sdk/v1/training/blocks/:id/generate — Response
{
  "modules_created": 3,
  "controls_linked": 24,
  "matrix_entries_created": 15,
  "content_generated": 3,
  "errors": []
}

11. Canonical Controls

Referenz-Datenbank mit standardisierten Sicherheitskontrollen.

GET/sdk/v1/training/canonical/controls

Canonical Controls auflisten (mit Filtern)

Parameter	Type	Required	Description
`domain`	`string`	No	Domain-Filter (z.B. AUTH, CRYP)
`category`	`string`	No	Kategorie-Filter
`severity`	`string`	No	Severity-Filter
`target_audience`	`string`	No	Zielgruppen-Filter

GET/sdk/v1/training/canonical/meta

Aggregierte Metadaten (Domains, Kategorien, Audiences mit Counts)

// GET /sdk/v1/training/canonical/meta — Response
{
  "domains": [
    { "domain": "AUTH", "count": 12 },
    { "domain": "CRYP", "count": 8 }
  ],
  "categories": [
    { "category": "authentication", "count": 12 },
    { "category": "encryption", "count": 8 }
  ],
  "audiences": [
    { "audience": "enterprise", "count": 45 },
    { "audience": "all", "count": 30 }
  ],
  "total": 102
}

Typischer Workflow

Module erstellen — via POST /modules oder Training Blocks
Content generieren — POST /content/generate (LLM)
Content freigeben — POST /content/:id/publish
Quiz generieren — POST /content/generate-quiz
Audio/Video — POST /content/:id/generate-audio, generate-video
CTM konfigurieren — POST /matrix (Rolle → Modul)
Zuweisungen berechnen — POST /assignments/compute
Mitarbeiter absolviert — start → progress → Quiz → complete
Zertifikat — POST /certificates/generate/:assignmentId
Audit — GET /audit-log + GET /stats

Training API