API Documentation

Authentication

Every request must include the approved token as a Bearer token.

Authorization: Bearer YOUR_API_TOKEN

Alternative header supported by the planned API security core:

X-API-Key: YOUR_API_TOKEN

Base URL

/es/api/v1

Quick curl examples

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/ping.php"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/manifest.php"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/training.php?limit=10"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/games.php?limit=10"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/comics.php?limit=10"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/exams.php?limit=10"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/chapters.php?subject_id=12&class_level=standard_3&include_preview=1"

Build Quiz Homework source type

Use this flow when an external teacher wants to build a quiz/homework from the Rolytech question bank.

1. Load chapters/forms: call GET /chapters.php with subject_id and enum class_level, for example standard_3.
2. Generate real rows: call POST /quizzes-generate.php with selected chapter(s), question forms, question_count, drawing_count and optional assign_to.
3. Render/assign: use the returned generated_quiz_id and safe question aliases. Answer keys are not exposed.
4. Capture attempts: call POST /attempts.php with content_type=generated_quiz.
5. Validate server-side: call POST /quizzes-validate.php or POST /attempts-validate.php.

drawing_count means maximum allowed drawings, not minimum required drawings. Example: drawing_count=2 means return up to two safe drawing questions when available. If no safe drawing questions exist, the API may still return a valid 20-question quiz with a drawing warning.

External builders must not create fake question selections. If Rolytech returns no question rows, block the builder and show the API error/insufficient-pool message.

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/chapters.php?subject_id=12&class_level=standard_3&include_preview=1"

curl -X POST "/es/api/v1/quizzes-generate.php" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Science Standard III Homework",
    "subject_id": 12,
    "class_level": "standard_3",
    "chapter_ids": [1, 2],
    "question_types": ["multiple_choice", "true_false"],
    "question_count": 20,
    "drawing_count": 2,
    "rotation_key": "teacher-123-standard-3-science",
    "teacher_ref": "teacher-123",
    "assign_to": [
      {"learner_ref": "student-001", "learner_name": "Student One", "class_ref": "standard_3"}
    ]
  }'

Detail requests

Use ?id=NUMBER to load one approved record with extra safe details.

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/games.php?id=55"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/comics.php?id=3"

curl -H "Authorization: Bearer YOUR_API_TOKEN" "/es/api/v1/exams.php?id=1"

Detail payload contract

List endpoints return cards. Detail endpoints use ?id=NUMBER and include the actual learner-facing data.

• Games: data.item.playable_contract, data.item.questions, data.item.questions[].options, data.item.rules, data.item.score_policy, data.item.completion_policy, and data.item.validation_policy. Correct answers are not included.
• Comics: data.item.reader_contract, data.item.pages, data.item.reader_pages, data.item.pages[].image_url, data.item.navigation_policy, data.item.completion_policy, and data.item.quiz_policy. Comic quiz answer keys are not included.
• Exams: data.item.practice_contract, data.item.questions, data.item.question_rows, data.item.quiz_question_rows, data.item.safe_question_rows, data.item.rows, data.item.questions[].options, data.item.sections, data.item.timing_policy, data.item.score_policy, data.item.completion_policy, and data.item.validation_policy. Correct options, answer keys, explanations, and marking schemes are not included. Exam detail is a legacy/practice detail route; use the Build Quiz Homework flow for chapter-based random quiz creation.
• Training: data.item.training_contract, data.item.lesson_contract, data.item.sections, data.item.content, data.item.lesson_body, data.item.materials, data.item.resources, and data.item.media.

Games playable contract v1

Use a detail request such as /games.php?id=55. Bamma should render from data.item.playable_contract or the top-level aliases.

{
  "success": true,
  "data": {
    "resource": "game",
    "item": {
      "id": 55,
      "game_type": "scenario_mission",
      "render_mode": "interactive",
      "instructions": "Complete the mission...",
      "questions": [
        {
          "id": "q1",
          "type": "multiple_choice",
          "prompt": "Mission question...",
          "options": [
            {"id": "A", "label": "A", "text": "Option A"}
          ],
          "answer_mode": "server_validate"
        }
      ],
      "score_policy": {"pass_mark_percent": 70},
      "completion_policy": {"complete_when": "all_questions_answered"},
      "validation_policy": {"answer_keys_exposed": false}
    }
  }
}

Comics reader contract v1

Use a detail request such as /comics.php?id=3. Bamma should render from data.item.reader_contract or from the direct page aliases.

{
  "success": true,
  "data": {
    "resource": "comic",
    "item": {
      "id": 3,
      "render_mode": "reader",
      "reader_mode": "paginated",
      "pages": [
        {
          "page_number": 1,
          "title": "Why Did It Rain?",
          "image_url": "https://example.com/uploads/comics/page_01.png",
          "caption": "Amina asks why it rained last night.",
          "assets": []
        }
      ],
      "navigation_policy": {"navigation": "next_previous"},
      "completion_policy": {"complete_when": "last_page_viewed"},
      "quiz_policy": {"answer_keys_exposed": false}
    }
  }
}

Exams practice contract v1

Use a detail request such as /exams.php?id=1. Bamma should render practice/exam items from data.item.practice_contract or the direct question aliases.

{
  "success": true,
  "data": {
    "resource": "exam",
    "item": {
      "id": 1,
      "render_mode": "practice",
      "practice_mode": "question_list",
      "questions": [
        {
          "id": "101",
          "type": "multiple_choice",
          "prompt": "Choose the correct answer...",
          "options": [
            {"id": "201", "label": "A", "text": "Option A"}
          ],
          "marks": 1,
          "answer_mode": "server_validate"
        }
      ],
      "sections": [{"id": "section-a", "question_count": 10}],
      "timing_policy": {"timer_mode": "countdown"},
      "score_policy": {"answer_keys_exposed": false},
      "validation_policy": {"answer_keys_exposed": false}
    }
  }
}

Training reader contract v1

Use a detail request such as /training.php?id=NUMBER. Bamma should render lessons from data.item.training_contract, data.item.lesson_contract, or the direct section/content aliases.

{
  "success": true,
  "data": {
    "resource": "training",
    "item": {
      "id": 12,
      "render_mode": "reader",
      "reader_mode": "lesson_reader",
      "content": "Lesson body...",
      "sections": [
        {
          "id": "summary",
          "title": "Summary",
          "type": "summary",
          "content": "Short lesson summary...",
          "plain_text": "Short lesson summary..."
        }
      ],
      "resources": [
        {"id": "file-1", "type": "file", "url": "https://example.com/uploads/file.pdf"}
      ],
      "media": [
        {"id": "video-1", "type": "video", "url": "https://example.com/video"}
      ],
      "completion_policy": {"complete_when": "content_viewed"},
      "progress_policy": {"track_viewed_sections": true}
    }
  }
}

Filters

Supported filters include q, subject_id, topic_id, class_level, limit and offset. Some endpoints also support type, difficulty, game_type, category, language, target_audience, exam_mode and visibility.

/es/api/v1/training.php?q=science&class_level=standard_3&limit=10

PHP example

<?php
$token = 'YOUR_API_TOKEN';
$url = '/es/api/v1/training.php?limit=10';

$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => "Authorization: Bearer {$token}\r\nAccept: application/json\r\n",
        'timeout' => 20,
    ],
]);

$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);
print_r($data);

JavaScript example

const token = 'YOUR_API_TOKEN';
const response = await fetch('/es/api/v1/training.php?limit=10', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json'
  }
});

const data = await response.json();
console.log(data);

Active endpoint rules

Standard error format

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API token."
  }
}