Learning & Version API Endpoints

Learnings capture knowledge extracted from AI agent sessions -- patterns, gotchas, and correct behaviors that agents should follow. Learning versions are compiled snapshots that get injected into agent prompts. Together these 19 endpoints manage the full learning lifecycle: creation, curation, compilation, and activation.

Learning Read Endpoints

GET /api/v1/learnings/list

List learnings with optional filtering.

Query parameters:

• status (optional) -- Filter by status (e.g., pending, approved, rejected)
• category (optional) -- Filter by category

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

GET /api/v1/learnings/stats

Get aggregate statistics for learnings (counts by status, by category, etc.).

GET /api/v1/learnings/preview

Preview the compiled learning document that would be injected into agent prompts.

GET /api/v1/learnings/by-sandbox

List all learnings extracted from a specific sandbox session.

• sandboxId (required) -- The sandbox document ID

Learning Mutation Endpoints

POST /api/v1/learnings/create

Create a new learning manually.

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 fields:

• description (string, required) -- What was learned
• trigger (string, optional) -- When this learning applies
• correctBehavior (string, optional) -- The correct behavior
• severity (string, optional) -- Impact level
• category (string, optional) -- Learning category
• applicableRoles (array, optional) -- Which agent roles should receive this

POST /api/v1/learnings/update-status

Update the approval status of a learning.

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

POST /api/v1/learnings/update-content

Update the content fields of a learning.

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

POST /api/v1/learnings/delete

Soft-delete a learning.

{ "learningId": "..." }

POST /api/v1/learnings/restore

Restore a soft-deleted learning.

{ "learningId": "..." }

POST /api/v1/learnings/permanent-delete

Permanently delete a learning.

{ "learningId": "..." }

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

Update the status of multiple learnings at once.

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

POST /api/v1/learnings/bulk-delete

Soft-delete multiple learnings.

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

Learning Version Endpoints

Learning versions are compiled snapshots of approved learnings. Each version is scoped to a role type (e.g., designer, checker) and can be activated to inject its content into agent prompts.

GET /api/v1/learning-versions/list

List learning versions with optional filtering.

Query parameters:

• roleType (optional) -- Filter by role type
• status (optional) -- Filter by version status

GET /api/v1/learning-versions/get

Retrieve a single learning version.

• id (required) -- The version document ID

GET /api/v1/learning-versions/active

Get the currently active learning version for a role type.

• roleType (required) -- The role type to query

POST /api/v1/learning-versions/compile

Compile a new learning version from selected learnings.

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

Activate a learning version. This makes it the active version for its role type -- all future agent sessions of that role will use it.

{ "versionId": "..." }

POST /api/v1/learning-versions/deactivate

Deactivate a learning version.

{ "versionId": "..." }