Knowledge Base API

Die Knowledge Base API verwaltet Wissensdatenbank-Artikel mit Rich-Text-Content, Kategorien, Zugriffskontrolle über Sichtbarkeit und Status, View-Tracking, Tags und Anhängen. Verknüpfungen zu Tickets/Problems/Incidents/Changes laufen zentral über die Linking-API. Basis-Pfad: /api/knowledge-base.

🔐 Auth: Nur für angemeldete Benutzer; API-Keys werden abgelehnt. Rechte über knowledgeBase.*, Kategorien über settings.manageCategories. status und visibility werden in Ein- und Ausgabe in Großbuchstaben geschrieben (PUBLIC/INTERNAL/RESTRICTED, DRAFT/PUBLISHED/ARCHIVED); Kleinschreibung wird mit 400 abgelehnt. Siehe RBAC →.

Endpunkte — Artikel

* view = der Artikel ist nicht gelöscht und der Aufrufer ist entweder der Autor oder hat sowohl das Visibility- als auch das Status-Recht. Visibility: viewPublic/viewInternal/viewRestricted bzw. bei RESTRICTED eine Freigabe; Status: viewDraft/viewPublished/viewArchived. Eine Rolle mit viewPublished, aber ohne viewInternal sieht INTERNAL-Artikel auch per Direkt-ID nicht. Liste und Einzelabruf wenden dieselbe Regel an.

Endpunkte — Kategorien

KBCategory: name (eindeutig, 1–50), description? (max 200), color (#RRGGBB, Default #3b82f6), isActive, articleCount. DELETE einer Kategorie mit Artikeln → 400 CATEGORY_HAS_ARTICLES.

Zugriffsmodell (Sichtbarkeit und Status)

Ein Artikel ist nur sichtbar, wenn der Aufrufer sowohl das Visibility- als auch das Status-Recht besitzt (bzw. bei RESTRICTED eine Freigabe hat). Ausnahme: Der Autor sieht eigene Artikel immer, unabhängig von beiden Rechten. Eine Freigabe ersetzt nur das Visibility-Recht — einen Entwurf sieht weiterhin nur, wer viewDraft hat.

Status-Transitionen

Diese Rechte gelten zusätzlich zum Bearbeitungsrecht (editAll, oder editOwn für eigene Artikel) und werden auch beim Anlegen geprüft, sobald der Status vom Standard DRAFT abweicht — „direkt als veröffentlicht anlegen" erfordert also create + publish.

Artikel erstellen

POST /api/knowledge-base/articles

{
  "title": "Reset password in the self-service portal",
  "summary": "Quick guide for password reset",
  "content": "# Password Reset\n\n## Step 1 ...",
  "categoryId": "clx-cat-self-service",
  "visibility": "PUBLIC",
  "status": "DRAFT",
  "tags": ["password", "self-service"]
}

Felder: title (5–200), content (10–50 000), summary? (max 500), categoryId (Pflicht), visibility (PUBLIC/INTERNAL/RESTRICTED, Default INTERNAL), status (DRAFT/PUBLISHED/ARCHIVED, Default DRAFT), tags (max 20, je max 50 Zeichen; case-insensitiv, bestehende Schreibweise gewinnt). Die EINGABE ist eine Namensliste; in den Antworten (Liste, Detail, Anlage, Änderung, Wiederherstellung) tragen tags dagegen Referenzen der Form { id, name } — mit der ID filtert die Artikelliste (f.tagIds=hasAny:…). Revisions-Snapshots behalten die historischen NAMEN. Der Autor ist immer der angemeldete Benutzer. RESTRICTED-Freigaben werden NICHT hier gesetzt, sondern über die eigenen /grants-Endpoints. Anhänge separat über POST /api/attachments/KB_ARTICLE/:id.

Artikel aktualisieren

PUT /api/knowledge-base/articles/:id

{
  "version": 3,
  "title": "Reset password (updated)",
  "status": "PUBLISHED"
}

version ist Pflicht (Schutz vor gleichzeitigem Überschreiben, wie bei Tickets): Der Client sendet die zuletzt gelesene Version; hat inzwischen jemand anders gespeichert, antwortet der Server mit 409 KB_VERSION_CONFLICT (expected/actual in details), statt dessen Änderung zu überschreiben. Jeder erfolgreiche PUT erhöht version und schreibt eine Revision. Inhaltsfelder sind optional (mind. eines nötig); eine status-Änderung erfordert das passende Recht (z. B. PUBLISHED → publish). Enums in Großbuchstaben. Freigaben werden hier nicht gesetzt; ein Wechsel weg von RESTRICTED entfernt bestehende Freigaben im selben Speichervorgang (auditiert).

Liste & Filter

GET /api/knowledge-base/articles?q=vpn&f.status=PUBLISHED&f.categoryId=clx-cat&page=1&per=20&sort=viewCount

Die Liste nutzt die einheitliche Filter-Syntax (auch für gespeicherte Ansichten): q (Volltext), f.status/f.visibility/f.categoryId/f.tagIds, page/per (per Default 20, max. 100), sort. search, status, visibility, categoryId, limit, sortBy, sortDirection und sortOrder als einfache Parameter werden mit 400 LEGACY_QUERY_PARAM_REMOVED abgelehnt. Die Liste enthält nur Artikel, die der Aufrufer sehen darf. Die Volltextsuche erkennt Wortstämme und Umlaute. Antwort:

{
  "data": [ /* ... */ ],
  "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3, "hasMore": true }
}

Freigaben, Papierkorb & Revisionen

• Freigaben: RESTRICTED-Artikel werden über Freigaben geöffnet — Subjekt-Typ USER, GROUP oder ROLE. Verwaltung über GET/POST/DELETE /articles/:id/grants (erfordert Bearbeitungsrecht am Artikel; Audit GRANT_ADDED/GRANT_REMOVED). Liste und Detail tragen einen grantCount; die Freigabeliste selbst erhalten nur Benutzer, die den Artikel bearbeiten dürfen. Rollen für die Freigabe-Auswahl: GET /api/roles/options (id/displayName/color).
• Soft-Delete + Papierkorb: DELETE markiert nur (deletedAt) — Links/Tags/Anhänge bleiben. Der Papierkorb ist GET /articles?deleted=1 (Recht viewDeleted); POST /articles/:id/restore holt zurück (Recht restore, kritisch). Gelöschte Artikel sind überall sonst 404. Nach 90 Tagen (Standardwert der Aufbewahrungsfrist) werden sie samt Revisionen endgültig gelöscht; dabei verwaiste Tags werden mit entfernt.
• Revisionen: Jeder Create/Update schreibt einen Snapshot (Revision.version == article.version). GET /articles/:id/revisions ({data}, ohne content) · GET /revisions/:version (voller Snapshot; unbekannt = 404 KB_REVISION_NOT_FOUND) · POST /revisions/:version/restore (wirkt wie eine normale Änderung: erzeugt eine neue Revision und prüft die Status-Rechte). Alle drei erfordern das Bearbeitungsrecht am Artikel.

Verlinkung zu anderen Entities

Artikel werden zentral über die Linking-API mit Tickets, Problems, Incidents und Changes verknüpft — z.B. POST /api/linking/tickets/:id/link-article bzw. /api/linking/problems/:id/link-article. Auf dem Artikel erscheinen die Verknüpfungen als linkedTickets, linkedProblems, linkedIncidents, linkedChanges.

Sichtbarkeits-Check beim Verlinken: POST /api/linking/{tickets|problems|incidents|changes}/:id/check-article-visibility ({articleIds[]}) prüft je Artikel, ob die Zielgruppe (Ticket→Kunde · Incident/Problem→Melder · Change→Requestor+Approver) ihn überhaupt sehen darf — der Agent bekommt vor dem Speichern einen Warnhinweis „für {Name} nicht sichtbar". Artikel-Titel erscheinen nicht in Timelines/Aktivitäten (Datensparsamkeit); das Frontend löst den Titel nur für Artikel auf, die der Betrachter sehen darf.

🔗 Details, Statusregeln und gestufte Listen: Entity Linking API →.

Permissions (knowledgeBase)

Zum Wiederherstellen sind zwei Rechte nötig: restore für die Aktion und viewDeleted, um den Papierkorb zu sehen — wer den Papierkorb nicht sehen darf, holt auch nichts daraus zurück. Zusätzlich gilt dieselbe Sichtbarkeitsregel wie in der Liste (einschließlich der Autoren-Ausnahme), damit Papierkorb und Wiederherstellen dieselben Artikel umfassen. Dasselbe gilt beim Löschen: Was nicht sichtbar ist, kann auch nicht gelöscht werden.

Kategorien (POST/PUT/DELETE /categories) werden mit settings.manageCategories verwaltet.