REST-API
Alle REST-Endpoints des KnowledgeSDK im Ueberblick. Die Classifier-Endpoints erfordern einen API-Key als Bearer-Token:
Authorization: Bearer <API_KEY>Ohne konfigurierten CLASSIFIER_API_KEY bzw. QMD_API_KEY sind die Endpoints offen (Entwicklungsmodus).
Eine interaktive API-Dokumentation ist unter /api/docs (Swagger UI) verfuegbar.
GET /api/search
Durchsucht die indexierte Dokumentation (BM25 + optionale Vektor-Suche).
Query-Parameter
| Parameter | Typ | Default | Beschreibung |
|---|---|---|---|
q | string | (Pflicht) | Suchbegriff |
collection | string | (alle) | Filter auf eine bestimmte Collection |
limit | number | 10 | Max. Anzahl Ergebnisse (1–50) |
Beispiel
curl
curl "https://docs.processcube.io/api/search?q=deployment&collection=engine&limit=5" \
-H "Authorization: Bearer $QMD_API_KEY"Response
interface SearchResponse {
results: Array<{
title: string;
path: string;
collection: string;
snippet: string;
score: number;
}>;
query: string;
collection: string | null;
total: number;
duration_ms: number;
}Status-Codes
| Code | Bedeutung |
|---|---|
| 200 | Suche erfolgreich |
| 400 | Parameter q fehlt |
| 401 | API-Key fehlt oder ungueltig |
| 429 | Zu viele Anfragen (Backpressure) |
POST /api/classify-ticket
Klassifiziert ein Ticket und ordnet es der passenden Collection, dem Sub-Thema und dem Quell-Repository zu.
Request
interface ClassifyRequest {
/** Stabiler Schluessel (Pflicht) */
correlationId: string;
/** Ticket-Titel (Pflicht) */
title: string;
/** Ticket-Beschreibung */
body?: string;
/** Tags/Markierungen */
tags?: string[];
/** Quell-Repository */
repo?: string;
/** Anhaenge */
attachments?: Array<{
type: 'image' | 'log' | 'file';
url?: string;
content?: string;
description?: string;
}>;
}Response
interface ClassifyResponse {
correlationId: string;
collection: string;
subTheme: string | null;
confidence: 'high' | 'medium' | 'low';
path: 'fast' | 'slow';
repo: { org: string; name: string; branch: string } | null;
relevantDocs: Array<{ title: string; url: string; score: number }>;
reasoning: string;
alternatives?: Array<{ collection: string; confidence: number; reason: string }>;
duration_ms: number;
}Beispiel
curl
curl -X POST https://docs.processcube.io/api/classify-ticket \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLASSIFIER_API_KEY" \
-d '{
"correlationId": "5minds/ProcessCube.Engine.MonoRepo#1234",
"title": "Timer Event feuert nicht bei cron-Expression",
"body": "In einem BPMN-Prozess mit Timer Intermediate Event...",
"tags": ["bug", "engine"],
"repo": "5minds/ProcessCube.Engine.MonoRepo"
}'Status-Codes
| Code | Bedeutung |
|---|---|
| 200 | Klassifikation erfolgreich |
| 400 | correlationId oder title fehlt |
| 401 | API-Key fehlt oder ungueltig |
| 429 | Zu viele Anfragen (Backpressure) |
| 500 | Klassifikation fehlgeschlagen |
POST /api/classify-ticket/feedback
Sendet eine Korrektur zu einer vorherigen Klassifikation. Verbessert zukuenftige Klassifikationen (Self-Improvement).
Request
interface FeedbackRequest {
/** correlationId der urspruenglichen Klassifikation (Pflicht) */
correlationId: string;
/** Die korrekte Collection (Pflicht) */
correctCollection: string;
/** Korrektes Sub-Thema */
correctSubTheme?: string;
/** Begruendung der Korrektur */
comment?: string;
}Beispiel
curl
curl -X POST https://docs.processcube.io/api/classify-ticket/feedback \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLASSIFIER_API_KEY" \
-d '{
"correlationId": "5minds/ProcessCube.Engine.MonoRepo#1234",
"correctCollection": "lowcode",
"comment": "War ein LowCode-Flow-Problem"
}'Status-Codes
| Code | Bedeutung |
|---|---|
| 200 | Feedback angenommen |
| 400 | correlationId oder correctCollection fehlt |
| 401 | Unauthorized |
| 404 | Keine Klassifikation mit dieser correlationId gefunden |
GET /api/classify-ticket/stats
Liefert Statistiken ueber Klassifikationen und Feedback.
Response
interface StatsResponse {
total: number;
withFeedback: number;
accuracy: number;
topMisclassifications: Array<{
predicted: string;
correct: string;
count: number;
}>;
}Beispiel
curl
curl https://docs.processcube.io/api/classify-ticket/stats \
-H "Authorization: Bearer $CLASSIFIER_API_KEY"Status-Codes
| Code | Bedeutung |
|---|---|
| 200 | Statistiken erfolgreich |
| 401 | API-Key fehlt oder ungueltig |
UPSERT-Verhalten der correlationId
Die correlationId ist ein Unique Key ueber alle Classifier-Endpoints hinweg:
| Situation | Verhalten |
|---|---|
| Erster Request mit einer neuen ID | Neue Klassifikation wird gespeichert |
| Gleiche ID wird erneut gesendet | Vorhersage wird aktualisiert (UPSERT), vorhandenes Feedback bleibt erhalten |
| Feedback zu einer bestehenden ID | Nur die Korrektur-Felder werden aktualisiert |
Das bedeutet: Wird ein Ticket mehrfach klassifiziert (z.B. nach einer Titel-Aenderung), reicht es, den Request mit derselben correlationId erneut zu senden. Die bisherige Klassifikation wird ueberschrieben, ohne dass ein vorheriges Feedback verloren geht.
MCP-Tools
Die Classifier-Endpoints sind auch als MCP-Tools verfuegbar:
| MCP-Tool | Entspricht |
|---|---|
classify_ticket | POST /api/classify-ticket |
classify_ticket_feedback | POST /api/classify-ticket/feedback |
search_docs | GET /api/search |
Siehe MCP-Server Dokumentation fuer Setup-Anleitungen.