Collections API Reference

Base path: /api/collections

Collections organize H5P content items into ordered groups with optional curriculum metadata. Each collection supports Bloom's Taxonomy gap analysis to suggest content that fills cognitive-level gaps.

Endpoints

POST /api/collections

Create a new collection.

Auth: Teacher (JWT, teacherAuthMiddleware)

Request Body:

{
  "title": "Algebra Fundamentals",
  "description": "Core algebra exercises for Grade 8",
  "frameworkCode": "TR-MEB-2024",
  "frameworkName": "MEB 2024",
  "gradeCode": "grade-8",
  "gradeName": "8th Grade",
  "subjectCode": "math",
  "subjectName": "Mathematics",
  "topicCodes": ["algebra-basics", "equations"],
  "topicNames": ["Algebra Basics", "Equations"],
  "difficulty": "medium",
  "language": "tr"
}

Response (201):

{
  "success": true,
  "data": {
    "id": "uuid",
    "userId": "uuid",
    "title": "Algebra Fundamentals",
    "description": "Core algebra exercises for Grade 8",
    "coverImageUrl": null,
    "visibility": "private",
    "frameworkCode": "TR-MEB-2024",
    "frameworkName": "MEB 2024",
    "gradeCode": "grade-8",
    "gradeName": "8th Grade",
    "subjectCode": "math",
    "subjectName": "Mathematics",
    "topicCodes": ["algebra-basics", "equations"],
    "topicNames": ["Algebra Basics", "Equations"],
    "difficulty": "medium",
    "language": "tr",
    "itemCount": 0,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}

Errors:

GET /api/collections

List the authenticated user's collections with pagination.

Auth: Authenticated user (JWT, authMiddleware)

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "userId": "uuid",
      "title": "Algebra Fundamentals",
      "description": "Core algebra exercises for Grade 8",
      "coverImageUrl": null,
      "visibility": "private",
      "frameworkCode": "TR-MEB-2024",
      "frameworkName": "MEB 2024",
      "gradeCode": "grade-8",
      "gradeName": "8th Grade",
      "subjectCode": "math",
      "subjectName": "Mathematics",
      "topicCodes": ["algebra-basics"],
      "topicNames": ["Algebra Basics"],
      "difficulty": "medium",
      "language": "tr",
      "itemCount": 5,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    }
  ],
  "total": 12
}

Collections are ordered by updatedAt DESC. The server-side limit cap is 100.

Errors:

GET /api/collections/:id

Get collection detail with enriched items. Items include H5P metadata, curriculum data, quality scores, ownership, and access status.

Auth: Authenticated user (JWT, authMiddleware)

Access rules: Owner can always view. Non-owners can view only if collection visibility is public.

Response (200):

{
  "success": true,
  "data": {
    "collection": {
      "id": "uuid",
      "userId": "uuid",
      "title": "Algebra Fundamentals",
      "visibility": "private",
      "itemCount": 2,
      "...": "..."
    },
    "items": [
      {
        "id": "uuid",
        "collectionId": "uuid",
        "contentId": "42",
        "position": 0,
        "addedAt": "2025-01-15T10:30:00.000Z",
        "title": "Quadratic Equations Quiz",
        "mainLibrary": "H5P.QuestionSet",
        "contentTypeSlug": "question-set",
        "authorId": "uuid",
        "authorName": "Teacher A",
        "status": "available",
        "curriculum": {
          "frameworkCode": "TR-MEB-2024",
          "frameworkName": "MEB 2024",
          "gradeCode": "grade-8",
          "gradeName": "8th Grade",
          "subjectCode": "math",
          "subjectName": "Mathematics",
          "topicCodes": ["equations"],
          "topicNames": ["Equations"],
          "difficulty": "medium",
          "language": "tr"
        },
        "quality": {
          "overallScore": 85,
          "dimensions": {}
        }
      }
    ]
  }
}

Item status values:

Errors:

PATCH /api/collections/:id

Update collection metadata. Only the owner can update.

Auth: Teacher (JWT, teacherAuthMiddleware)

Request Body: Any subset of the fields below.

{
  "title": "Updated Title",
  "description": "New description",
  "visibility": "public",
  "frameworkCode": "TR-MEB-2024",
  "frameworkName": "MEB 2024",
  "gradeCode": "grade-8",
  "gradeName": "8th Grade",
  "subjectCode": "math",
  "subjectName": "Mathematics",
  "topicCodes": ["algebra-basics"],
  "topicNames": ["Algebra Basics"],
  "difficulty": "hard",
  "language": "en"
}

Response (200):

{
  "success": true,
  "message": "Collection updated"
}

Errors:

DELETE /api/collections/:id

Delete a collection and all its items. Only the owner can delete.

Auth: Teacher (JWT, teacherAuthMiddleware)

Response (200):

{
  "success": true,
  "message": "Collection deleted"
}

Errors:

POST /api/collections/:id/items

Add one or more content items to a collection. Content existence and accessibility are verified via H5P before adding. Items are appended at the end (next available position).

Auth: Teacher (JWT, teacherAuthMiddleware)

Request Body (single item):

{
  "contentId": "42"
}

Request Body (batch):

{
  "contentIds": ["42", "43", "44"]
}

One of contentId or contentIds must be provided.

Response (201, single):

{
  "success": true,
  "data": {
    "id": "uuid",
    "collectionId": "uuid",
    "contentId": "42",
    "position": 5,
    "addedAt": "2025-01-15T11:00:00.000Z"
  }
}

Response (201, batch):

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "collectionId": "uuid",
      "contentId": "42",
      "position": 5,
      "addedAt": "2025-01-15T11:00:00.000Z"
    },
    {
      "id": "uuid",
      "collectionId": "uuid",
      "contentId": "43",
      "position": 6,
      "addedAt": "2025-01-15T11:00:00.000Z"
    }
  ]
}

Batch add uses ON CONFLICT DO NOTHING for duplicate content IDs within the same collection. The item_count on the collection is incremented only for actually inserted items.

Errors:

DELETE /api/collections/:id/items/:itemId

Remove a single item from a collection. The itemId is the collection_item UUID, not the H5P content ID.

Auth: Teacher (JWT, teacherAuthMiddleware)

Response (200):

{
  "success": true,
  "message": "Item removed from collection"
}

Errors:

PATCH /api/collections/:id/items/reorder

Reorder items within a collection by specifying new positions.

Auth: Teacher (JWT, teacherAuthMiddleware)

Request Body:

{
  "items": [
    { "id": "item-uuid-1", "position": 0 },
    { "id": "item-uuid-2", "position": 1 },
    { "id": "item-uuid-3", "position": 2 }
  ]
}

Response (200):

{
  "success": true,
  "message": "Items reordered"
}

Errors:

GET /api/collections/:id/suggestions

Get smart content suggestions for a collection based on curriculum metadata and Bloom's Taxonomy gap analysis. Returns public content that matches the collection's curriculum filters, sorted so that content filling Bloom's gaps appears first.

Auth: Authenticated user (JWT, authMiddleware)

How it works:

1. Reads the collection's existing items and resolves each item's H5P content type to a Bloom's level using the CONTENT_TYPE_BLOOMS_MAP.
2. Computes a Bloom's distribution (percentage per level) and identifies gaps (levels with 0% coverage).
3. Queries public content matching the collection's curriculum filters (frameworkCode, gradeCode, subjectCode, difficulty, language), excluding content already in the collection and content owned by the requesting user.
4. Sorts suggestions so that content filling Bloom's gaps ranks first.

Bloom's ideal distribution (target):

Response (200):

{
  "success": true,
  "data": {
    "matchingContents": [
      {
        "contentId": "55",
        "title": "Interactive Sorting Exercise",
        "mainLibrary": "H5P.DragQuestion",
        "contentTypeSlug": "drag-question",
        "bloomsLevel": "apply",
        "curriculum": {
          "frameworkName": "MEB 2024",
          "stageName": "Middle School",
          "gradeName": "8th Grade",
          "subjectName": "Mathematics",
          "topicNames": ["Equations"],
          "difficulty": "medium",
          "language": "tr"
        }
      }
    ],
    "bloomsAnalysis": {
      "distribution": {
        "remember": 25,
        "understand": 25,
        "apply": 50,
        "analyze": 0,
        "evaluate": 0,
        "create": 0
      },
      "gaps": ["analyze", "evaluate", "create"],
      "score": 50
    }
  }
}

bloomsAnalysis fields:

Errors:

Data Model

Collection

CollectionItem

Unique constraint: (collectionId, contentId) -- a content item can appear at most once in a collection.