Question API
Bible quiz questions for your app
Licence questions from the Gospel Genius bank: 4,341 multiple-choice questions, each with a KJV reference, five difficulty levels, eight categories and 219 children's questions. A JSON API you call from your server.
Plans
Documentation
Base URL https://gospelgenius.ng/api/v1. All endpoints are GET and return JSON.
Send your key in the Authorization header. Keep the key on your server: anyone who has it can use your quota.
Authorization: Bearer gg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GET /api/v1/questions
Random questions within your plan. Each call counts as one request against your quota.
| Parameter | Meaning |
|---|---|
| limit | How many questions (default 10, capped at your plan's maximum). |
| category | Category id, or several separated by commas (see /categories). |
| difficulty | 1 Beginner to 5 Scholar, or a list like 1,2. |
| exclude | Comma-separated ids you have already used (up to 1,000). |
| language | en, ha, ig, yo or pcm, if your plan has it. Untranslated questions come back in English (each question says its language); add translated_only=1 to skip them. |
| kids | 1 = children's (Little Light, ages 4 to 10) questions only. |
{
"success": true,
"message": "OK",
"data": {
"questions": [
{
"id": 1042,
"category": { "id": 1, "name": "History & Narrative" },
"difficulty": 1,
"language": "en",
"kids": true,
"question": "How many days and nights did it rain in the flood?",
"options": { "a": "Seven", "b": "Forty", "c": "Twelve", "d": "Three" },
"answer": "b",
"explanation": "It rained on the earth forty days and forty nights.",
"scripture_ref": "Genesis 7:12"
}
],
"count": 1, "limit": 10, "limit_capped": false, "overage": false
}
}
answer, explanation and scripture_ref appear only if your plan includes them.
GET /api/v1/categories
The categories your plan covers, with question counts. Not counted against your quota.
GET /api/v1/usage
Your plan, requests used and left this period, when the quota resets and when access ends. Not counted against your quota.
Examples
curl
curl -H "Authorization: Bearer $GG_API_KEY" \
"https://gospelgenius.ng/api/v1/questions?limit=5&difficulty=1,2"
JavaScript (Node 18+, server side)
const res = await fetch('https://gospelgenius.ng/api/v1/questions?limit=5&kids=1', {
headers: { Authorization: `Bearer ${process.env.GG_API_KEY}` },
});
const body = await res.json();
if (!body.success) throw new Error(`${body.errors?.code}: ${body.message}`);
for (const q of body.data.questions) console.log(q.question, q.options);
PHP
$ch = curl_init('https://gospelgenius.ng/api/v1/questions?limit=5&category=5');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GG_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
if (!$body['success']) throw new RuntimeException($body['errors']['code'] . ': ' . $body['message']);
foreach ($body['data']['questions'] as $q) echo $q['question'], PHP_EOL;
Errors
Errors use the same envelope with "success": false, a readable message and a stable errors.code:
{ "success": false, "message": "Too many requests. Your plan allows 30 per minute.", "status": 429, "data": null, "errors": { "code": "rate_limited" } }
| HTTP | Code | Meaning |
|---|---|---|
| 400 | bad_parameter | A parameter is malformed. |
| 401 | invalid_key | Missing or unknown key. |
| 402 | payment_pending | The key is waiting for payment to be confirmed. |
| 402 | expired | Your access period has ended; renew to continue. |
| 403 | suspended | The key has been suspended. |
| 403 | category_not_in_plan / difficulty_not_in_plan / language_not_in_plan | You asked for something your plan does not include. |
| 405 | method_not_allowed | Use GET. |
| 429 | rate_limited | Over your per-minute limit. Wait (see Retry-After) and try again. |
| 429 | quota_exceeded | This period's requests are used up (plans without overage). errors.resets says when it resets. |
Plans with an overage price keep working past the quota; extra requests are marked "overage": true and invoiced per 1,000.
Good to know
Questions are written for Nigerian Christians across traditions and quote the King James Version. Please show the credit "Questions by Gospel Genius" with a link to gospelgenius.ng, cache what you fetch rather than requesting the same questions repeatedly, and contact us about bulk or offline licences.