🔌 API Reference

Technical documentation for developers integrating with the Content Cache API.

Authentication

All API requests require authentication via httpOnly cookies.

JavaScript

// All requests must include credentials
fetch('/api/class-content/{classId}', {
    credentials: 'include',  // Required for httpOnly cookies
    headers: {
        'Content-Type': 'application/json'
    }
});

⚠️ Access Control Only the class owner and invited content experts can access these endpoints. Unauthorized requests return 403 Forbidden.

List Class Content

Get all cached content for a class organized by competency and mode.

HTTP

GET /api/class-content/:classId

Response

JSON

{
  "success": true,
  "classId": "class-123",
  "competencies": [
    {
      "competencyId": "comp-1",
      "competencyName": "AI Ethics",
      "modes": {
        "KE": {
          "versions": [1, 2, 3, 4],
          "activeVersion": 2
        },
        "SPL": {
          "versions": [1],
          "activeVersion": 1
        },
        "SATA": {
          "versions": [1, 2],
          "activeVersion": 2
        }
      }
    }
  ]
}

Get Specific Version

Retrieve content for a specific version.

HTTP

GET /api/class-content/:classId/:competencyId/:mode/:version

Parameters

Parameter	Type	Description
`classId`	string	The class identifier
`competencyId`	string	The competency identifier
`mode`	string	KE, SPL, or SATA
`version`	number	Version number (1-4)

Response

JSON

{
  "success": true,
  "content": {
    // Content data varies by mode
  },
  "metadata": {
    "version": 2,
    "generatedAt": "2025-11-25T10:30:00Z",
    "editedBy": "teacher@school.edu",
    "lastEditedAt": "2025-11-25T14:45:00Z",
    "editCount": 3,
    "isActive": true
  }
}

Edit Version

Update content for a specific version. Creates a new version.

HTTP

PUT /api/class-content/:classId/:competencyId/:mode/:version

Request Body

JSON

{
  "content": {
    // Updated content data
  }
}

Response

JSON

{
  "success": true,
  "newVersion": 3,
  "message": "Content updated successfully"
}

Set Active Version

Change which version students see.

HTTP

POST /api/class-content/:classId/:competencyId/:mode/set-active

Request Body

JSON

{
  "version": 2
}

Response

JSON

{
  "success": true,
  "activeVersion": 2,
  "message": "Active version updated"
}

Delete Version

Remove a specific version. Cannot delete active version.

HTTP

DELETE /api/class-content/:classId/:competencyId/:mode/:version

Response

JSON

{
  "success": true,
  "message": "Version deleted successfully"
}

⚠️ Cannot Delete Active Attempting to delete the active version returns 400 Bad Request. Switch to a different active version first.

Regenerate Content

Request new AI-generated versions.

HTTP

POST /api/class-content/:classId/:competencyId/:mode/regenerate

Request Body

JSON

{
  "count": 2,           // Number of new versions (1-4)
  "customPrompt": null  // Optional: custom generation instructions
}

Response

JSON

{
  "success": true,
  "newVersions": [3, 4],
  "message": "Generated 2 new versions"
}

AI Critic

Get AI-powered quality feedback on content.

HTTP

POST /api/class-content/critic/:classId

Request Body

JSON

{
  "content": { ... },         // The content to analyze
  "criticType": "factual",    // Type: factual, pedagogical, bias, assessment, technical, comprehensive
  "competencyName": "AI Ethics",
  "competencyDescription": "Understanding ethical AI",
  "system": "SATA"            // Content system: KE, SPL, SATA
}

Critic Types

Type	Description
`factual`	Verifies facts, dates, formulas, statistics
`pedagogical`	Checks learning objectives, scaffolding, difficulty
`bias`	Identifies cultural, gender, socioeconomic bias
`assessment`	Reviews questions, answers, distractors (SATA)
`technical`	Validates JSON structure, rendering, formatting
`comprehensive`	Full analysis across all dimensions

Response

JSON

{
  "success": true,
  "criticism": "## Factual Accuracy Review\n\n🔴 **Must Fix**\n- The formula...\n\n🟡 **Should Address**\n- Statistics need sources...\n\n🟢 **Nice to Have**\n- Consider adding examples..."
}

Criticism Chat

Chat with AI to understand technical criticism feedback.

HTTP

POST /api/class-content/criticism-chat/:classId

Request Body

JSON

{
  "userMessage": "What does 'insufficient semantic plausibility' mean?",
  "criticism": "The distractors exhibit insufficient semantic plausibility...",
  "criticismType": "assessment",
  "competencyName": "AI Ethics",
  "competencyDescription": "Understanding ethical AI",
  "system": "SATA",
  "originalContent": { ... },   // The content being discussed
  "chatHistory": [              // Previous messages (optional)
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

Response

JSON

{
  "success": true,
  "response": "In plain language: your wrong answers are too obviously wrong. Students can eliminate them without really understanding the topic...\n\n**To fix this:**\n- Make wrong answers sound more similar to the right answer\n- Use common misconceptions as distractors..."
}

💡 Chat Context The chat endpoint maintains context of the original content and criticism, allowing teachers to ask follow-up questions without repeating information.

Error Codes

Code	Meaning	Resolution
`400`	Bad Request	Check request body format
`401`	Unauthorized	Login required
`403`	Forbidden	Not owner/content expert
`404`	Not Found	Class or content doesn't exist
`500`	Server Error	Contact support