Points de terminaison Learning & Version API

Les learnings capturent la connaissance extraite des sessions d’agents IA - patterns, pièges, et comportements corrects que les agents doivent suivre. Les versions de learnings sont des snapshots compilés injectés dans les prompts des agents. Ensemble, ces 19 points de terminaison gèrent le cycle de vie complet du learning : création, curation, compilation et activation.

Points de terminaison de lecture Learning

GET /api/v1/learnings/list

Liste les learnings avec filtrage optionnel.

Paramètres de query :

• status (optionnel) - Filtrer par statut (p. ex., pending, approved, rejected)
• category (optionnel) - Filtrer par catégorie

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

GET /api/v1/learnings/stats

Obtient des statistiques agrégées sur les learnings (comptes par statut, par catégorie, etc.).

GET /api/v1/learnings/preview

Prévisualise le document de learning compilé qui serait injecté dans les prompts des agents.

GET /api/v1/learnings/by-sandbox

Liste tous les learnings extraits d’une session de sandbox spécifique.

• sandboxId (requis) - L’ID du document sandbox

Points de terminaison de mutation Learning

POST /api/v1/learnings/create

Crée un nouveau learning manuellement.

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

Champs du body :

• description (string, requis) - Ce qui a été appris
• trigger (string, optionnel) - Quand ce learning s’applique
• correctBehavior (string, optionnel) - Le comportement correct
• severity (string, optionnel) - Niveau d’impact
• category (string, optionnel) - Catégorie du learning
• applicableRoles (array, optionnel) - Quels rôles d’agents doivent le recevoir

POST /api/v1/learnings/update-status

Met à jour le statut d’approbation d’un learning.

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

POST /api/v1/learnings/update-content

Met à jour les champs de contenu d’un learning.

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

POST /api/v1/learnings/delete

Supprime un learning (soft-delete).

{ "learningId": "..." }

POST /api/v1/learnings/restore

Restaure un learning supprimé en soft-delete.

{ "learningId": "..." }

POST /api/v1/learnings/permanent-delete

Supprime définitivement un learning.

{ "learningId": "..." }

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

Met à jour le statut de plusieurs learnings en une seule fois.

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

POST /api/v1/learnings/bulk-delete

Supprime plusieurs learnings (soft-delete).

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

Points de terminaison Learning Version

Les versions de learnings sont des snapshots compilés de learnings approuvés. Chaque version est scopée à un type de rôle (p. ex., designer, checker) et peut être activée pour injecter son contenu dans les prompts des agents.

GET /api/v1/learning-versions/list

Liste les versions de learnings avec filtrage optionnel.

Paramètres de query :

• roleType (optionnel) - Filtrer par type de rôle
• status (optionnel) - Filtrer par statut de version

GET /api/v1/learning-versions/get

Récupère une seule version de learning.

• id (requis) - L’ID du document version

GET /api/v1/learning-versions/active

Récupère la version de learning actuellement active pour un type de rôle.

• roleType (requis) - Le type de rôle à requêter

POST /api/v1/learning-versions/compile

Compile une nouvelle version de learning à partir de learnings sélectionnés.

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

Active une version de learning. Ceci en fait la version active pour son type de rôle - toutes les futures sessions d’agents de ce rôle l’utiliseront.

{ "versionId": "..." }

POST /api/v1/learning-versions/deactivate

Désactive une version de learning.

{ "versionId": "..." }