Endpoint Learning & Version API

Riferimento completo per gli endpoint REST API dei learning e delle versioni di learning - gestisci i learning degli agenti IA, compila versioni e attiva basi di conoscenza.

11 min letto
apilearningsversions

I learning catturano la conoscenza estratta dalle session degli agenti IA - pattern, insidie e comportamenti corretti che gli agenti devono seguire. Le versioni di learning sono snapshot compilati iniettati nei prompt degli agenti. Insieme, questi 19 endpoint gestiscono l’intero ciclo di vita del learning: creazione, curation, compilazione e attivazione.

Endpoint di lettura Learning

GET /api/v1/learnings/list

Elenca i learning con filtri opzionali.

Parametri di query:

  • status (opzionale) - Filtra per stato (ad es., pending, approved, rejected)
  • category (opzionale) - Filtra per categoria
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/learnings/list?status=approved"

GET /api/v1/learnings/stats

Ottiene statistiche aggregate sui learning (conteggi per stato, per categoria, ecc.).

GET /api/v1/learnings/preview

Visualizza in anteprima il documento di learning compilato che verrebbe iniettato nei prompt degli agenti.

GET /api/v1/learnings/by-sandbox

Elenca tutti i learning estratti da una specifica session di sandbox.

  • sandboxId (obbligatorio) - L’ID del documento sandbox

Endpoint di mutazione Learning

POST /api/v1/learnings/create

Crea manualmente un nuovo learning.

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

Campi del body:

  • description (string, obbligatorio) - Cosa è stato appreso
  • trigger (string, opzionale) - Quando si applica questo learning
  • correctBehavior (string, opzionale) - Il comportamento corretto
  • severity (string, opzionale) - Livello di impatto
  • category (string, opzionale) - Categoria del learning
  • applicableRoles (array, opzionale) - Quali ruoli agente devono riceverlo

POST /api/v1/learnings/update-status

Aggiorna lo stato di approvazione di un learning.

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

POST /api/v1/learnings/update-content

Aggiorna i campi di contenuto di un learning.

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

POST /api/v1/learnings/delete

Elimina (soft-delete) un learning.

{ "learningId": "..." }

POST /api/v1/learnings/restore

Ripristina un learning eliminato con soft-delete.

{ "learningId": "..." }

POST /api/v1/learnings/permanent-delete

Elimina definitivamente un learning.

{ "learningId": "..." }

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

Aggiorna lo stato di più learning contemporaneamente.

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

POST /api/v1/learnings/bulk-delete

Elimina (soft-delete) più learning.

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

Endpoint Learning Version

Le versioni di learning sono snapshot compilati di learning approvati. Ogni versione è scoped a un tipo di ruolo (ad es., designer, checker) e può essere attivata per iniettare il proprio contenuto nei prompt degli agenti.

GET /api/v1/learning-versions/list

Elenca le versioni di learning con filtri opzionali.

Parametri di query:

  • roleType (opzionale) - Filtra per tipo di ruolo
  • status (opzionale) - Filtra per stato della versione

GET /api/v1/learning-versions/get

Recupera una singola versione di learning.

  • id (obbligatorio) - L’ID del documento versione

GET /api/v1/learning-versions/active

Ottiene la versione di learning attualmente attiva per un tipo di ruolo.

  • roleType (obbligatorio) - Il tipo di ruolo da interrogare

POST /api/v1/learning-versions/compile

Compila una nuova versione di learning a partire da learning selezionati.

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

Attiva una versione di learning. Questo la rende la versione attiva per il suo tipo di ruolo - tutte le future session di agenti di quel ruolo la useranno.

{ "versionId": "..." }

POST /api/v1/learning-versions/deactivate

Disattiva una versione di learning.

{ "versionId": "..." }