Marketplace API Reference

Base path: /api/marketplace

The marketplace enables public content discovery, filtering, and cloning. Teachers can browse content published by other users, inspect curriculum metadata and quality scores, and clone content into their own library.

Endpoints

GET /api/marketplace/public-contents/facets

Return distinct filter values available across all public content. Use these values to populate filter dropdowns in the UI.

Auth: Authenticated user (JWT, authMiddleware)

Response (200):

{
  "success": true,
  "data": {
    "subjects": ["Mathematics", "Science", "English"],
    "grades": ["5th Grade", "8th Grade", "10th Grade"],
    "difficulties": ["easy", "medium", "hard"],
    "languages": ["en", "tr", "fr"],
    "frameworks": ["MEB 2024", "Common Core"]
  }
}

All arrays are sorted alphabetically and have null/empty values filtered out.

Errors:

GET /api/marketplace/public-contents

Browse public content from other users with optional search and curriculum filters. Results are enriched with H5P metadata, curriculum data, quality scores, and author information.

Auth: Authenticated user (JWT, authMiddleware)

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "id": "42",
      "title": "Quadratic Equations Quiz",
      "mainLibrary": "H5P.QuestionSet",
      "contentTypeSlug": "question-set",
      "authorId": "uuid",
      "authorName": "Teacher A",
      "viewCount": 128,
      "publishedAt": "2025-01-10T08:00:00.000Z",
      "curriculum": {
        "frameworkName": "MEB 2024",
        "stageName": "Middle School",
        "gradeName": "8th Grade",
        "subjectName": "Mathematics",
        "topicNames": ["Equations"],
        "difficulty": "medium",
        "language": "tr"
      },
      "quality": {
        "overallScore": 92,
        "dimensions": {}
      }
    }
  ],
  "total": 47
}

Enrichment details:

• Content owned by the authenticated user is excluded from results.
• Content that cannot be read from H5P storage is silently excluded.
• curriculum is null if the content has no curriculum metadata attached.
• quality is null if no quality assessment has been performed.
• authorName falls back to "Anonymous" if the author record is missing.

Errors:

POST /api/marketplace/public-contents/:contentId/clone

Clone a public content item into the authenticated user's own library. Creates a full copy of the H5P content, ownership record, and curriculum metadata.

Auth: Teacher (JWT, teacherAuthMiddleware)

URL Parameters:

Request Body: None.

Process:

1. Verifies the source content exists and has visibility: public.
2. Checks the user's subscription quota (content limit).
3. Copies H5P content (parameters + metadata) via h5pEditor.saveOrUpdateContent.
4. Records ownership for the new content as private.
5. Copies curriculum metadata from the source content to the clone.
6. Increments the user's content usage counter.
7. Increments the source content's viewCount (fire-and-forget).

Response (201):

{
  "success": true,
  "data": {
    "contentId": "99"
  }
}

Errors:

Referral System

The marketplace includes a referral service (referralService) for user acquisition. While the referral endpoints are defined in the referral service layer, they share the marketplace domain.

Referral Types

interface Referral {
  id: string;
  referrerId: string;
  referredEmail: string;
  referralCode: string;
  status: "pending" | "converted" | "expired";
  rewardType: "extra_credits" | "plan_discount";
  createdAt: Date;
  convertedAt: Date | null;
}

Referral Constants

Referral Flow

1. Generate link: Each user gets a unique referral code stored in creatiq_users.referral_code. The link format is {APP_URL}/login?ref={CODE}.
2. Convert: When a new user signs up via a referral link, the referral is recorded as converted. The referrer receives REFERRAL_EXTRA_CREDITS (5) additional AI generation credits.
3. Stats: Referrers can view their total, converted, and pending referral counts along with total rewards earned.

Data Model

Public Content List Item