🔌 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"
}

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