Learning- & Versions-API-Endpunkte

Learnings erfassen Wissen, das aus KI-Agenten-Sessions extrahiert wurde - Muster, Stolperfallen und korrektes Verhalten, dem Agenten folgen sollten. Learning-Versionen sind kompilierte Snapshots, die in Agent-Prompts eingefügt werden. Zusammen verwalten diese 19 Endpunkte den vollständigen Learning-Lifecycle: Erstellung, Kuratierung, Kompilierung und Aktivierung.

Learning-Lese-Endpunkte

GET /api/v1/learnings/list

Learnings mit optionaler Filterung auflisten.

Query-Parameter:

• status (optional) -- Nach Status filtern (z. B. pending, approved, rejected)
• category (optional) -- Nach Kategorie filtern

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/learnings/list?status=approved"

GET /api/v1/learnings/stats

Aggregierte Statistiken für Learnings abrufen (Anzahl nach Status, nach Kategorie usw.).

GET /api/v1/learnings/preview

Vorschau des kompilierten Learning-Dokuments, das in Agent-Prompts eingefügt würde.

GET /api/v1/learnings/by-sandbox

Alle Learnings auflisten, die aus einer bestimmten Sandbox-Session extrahiert wurden.

• sandboxId (erforderlich) -- Die Sandbox-Dokument-ID

Learning-Mutation-Endpunkte

POST /api/v1/learnings/create

Ein neues Learning manuell erstellen.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Always use index-based queries on large tables",
    "trigger": "When querying tables with >1000 records",
    "correctBehavior": "Use .withIndex() instead of .filter()",
    "severity": "high",
    "category": "performance",
    "applicableRoles": ["designer", "optimizer"]
  }' \
  https://<deployment>.convex.site/api/v1/learnings/create

Body-Felder:

• description (string, erforderlich) -- Was gelernt wurde
• trigger (string, optional) -- Wann dieses Learning greift
• correctBehavior (string, optional) -- Das korrekte Verhalten
• severity (string, optional) -- Auswirkungs-Level
• category (string, optional) -- Learning-Kategorie
• applicableRoles (array, optional) -- Welche Agent-Rollen dies erhalten sollen

POST /api/v1/learnings/update-status

Den Freigabestatus eines Learnings aktualisieren.

{ "learningId": "...", "status": "approved" }

POST /api/v1/learnings/update-content

Die Inhaltsfelder eines Learnings aktualisieren.

{
  "learningId": "...",
  "description": "Updated description",
  "trigger": "Updated trigger",
  "correctBehavior": "Updated behavior",
  "severity": "medium",
  "category": "security",
  "applicableRoles": ["checker"]
}

POST /api/v1/learnings/delete

Ein Learning per Soft-Delete löschen.

{ "learningId": "..." }

POST /api/v1/learnings/restore

Ein per Soft-Delete gelöschtes Learning wiederherstellen.

{ "learningId": "..." }

POST /api/v1/learnings/permanent-delete

Ein Learning dauerhaft löschen.

{ "learningId": "..." }

POST /api/v1/learnings/bulk-update-status

Den Status mehrerer Learnings auf einmal aktualisieren.

{
  "learningIds": ["id1", "id2", "id3"],
  "status": "approved"
}

POST /api/v1/learnings/bulk-delete

Mehrere Learnings per Soft-Delete löschen.

{ "learningIds": ["id1", "id2"] }

Learning-Versions-Endpunkte

Learning-Versionen sind kompilierte Snapshots freigegebener Learnings. Jede Version ist auf einen Rollentyp beschränkt (z. B. designer, checker) und kann aktiviert werden, um ihren Inhalt in Agent-Prompts einzufügen.

GET /api/v1/learning-versions/list

Learning-Versionen mit optionaler Filterung auflisten.

Query-Parameter:

• roleType (optional) -- Nach Rollentyp filtern
• status (optional) -- Nach Versionsstatus filtern

GET /api/v1/learning-versions/get

Eine einzelne Learning-Version abrufen.

• id (erforderlich) -- Die Dokument-ID der Version

GET /api/v1/learning-versions/active

Die aktuell aktive Learning-Version für einen Rollentyp abrufen.

• roleType (erforderlich) -- Der abzufragende Rollentyp

POST /api/v1/learning-versions/compile

Eine neue Learning-Version aus ausgewählten Learnings kompilieren.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "roleType": "designer",
    "learningIds": ["id1", "id2", "id3"]
  }' \
  https://<deployment>.convex.site/api/v1/learning-versions/compile

POST /api/v1/learning-versions/activate

Eine Learning-Version aktivieren. Damit wird sie zur aktiven Version ihres Rollentyps - alle zukünftigen Agent-Sessions dieser Rolle verwenden sie.

{ "versionId": "..." }

POST /api/v1/learning-versions/deactivate

Eine Learning-Version deaktivieren.

{ "versionId": "..." }