Skip to content

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

Plans are being finalised. To licence questions now, contact us and we'll set up access for you.

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.

ParameterMeaning
limitHow many questions (default 10, capped at your plan's maximum).
categoryCategory id, or several separated by commas (see /categories).
difficulty1 Beginner to 5 Scholar, or a list like 1,2.
excludeComma-separated ids you have already used (up to 1,000).
languageen, 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.
kids1 = 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" } }
HTTPCodeMeaning
400bad_parameterA parameter is malformed.
401invalid_keyMissing or unknown key.
402payment_pendingThe key is waiting for payment to be confirmed.
402expiredYour access period has ended; renew to continue.
403suspendedThe key has been suspended.
403category_not_in_plan / difficulty_not_in_plan / language_not_in_planYou asked for something your plan does not include.
405method_not_allowedUse GET.
429rate_limitedOver your per-minute limit. Wait (see Retry-After) and try again.
429quota_exceededThis 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.