Academic Quiz API

This API provides generates multiple-choice questions (MCQs) for educational purposes. It covers core STEM subjects including Physics, Chemistry, Biology, Mathematics, and Computer Science.

Batch Generation

This endpoint supports batch requests! You can fetch up to 10 unique questions in a single request without duplicates.

Endpoint

POST /api/v1/quiz

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description
subject	string	Optional	Filter by subject. Options: physics, chemistry, biology, mathematics, computer. Pass random (or omit) for mixed subjects.
count	number	Optional	Number of questions to retrieve (Max: 10, Default: 1).

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/quiz \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"subject": "mathematics", "count": 5}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/quiz', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    subject: 'computer',
    count: 1
  })
});

const res = await response.json();
console.log(res.data[0].question);

Heavstal SDK

import { tools } from '@heavstal/api';

// Fetch 5 computer science questions
const quiz = await tools.quiz("computer", 5);
console.log(quiz.data[0].question);
console.log(quiz.data[0].options);

Python

import requests

url = "https://heavstal.com.ng/api/v1/quiz"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "subject": "mathematics",
    "count": 5
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "total_results": 1,
  "subject": "physics",
  "data": [
    {
      "id": 1,
      "subject": "physics",
      "question": "What is the SI unit of Force?",
      "options": [
        "Joule",
        "Newton",
        "Watt",
        "Pascal"
      ],
      "answer": "Newton"
    }
  ]
}

Error Response

{
  "status": "error",
  "error": "Count cannot exceed 10 questions per request."
}