TL;DR. YouVersion opened its API in April 2026. We wired it into our open-source Bible LMS as a Verse of the Day card on the dashboard. Four small things in their API surface cost us time. Writing them up so you don't repeat them.
Equip is an open-source LMS for Bible schools (FastAPI + React + Supabase, MIT). A dashboard verse-of-the-day card is one of those quietly load-bearing features for a faith-shaped product — it gives the page a pastoral anchor on the right while keeping the actionable column primary, and creates a daily-return habit without screaming for engagement.
YouVersion just opened YouVersion Platform: 1,474 Bibles, 1,283 languages, REST API plus SDKs (Swift, Kotlin, React, React Native). Free for non-commercial use. So we plugged it in.
The endpoints are simple. The friction is in the small print.
Footgun #1: /v1/bibles returns 422 without language_ranges[]
First instinct after pip install httpx:
# Wrong. Will not work.
httpx.get("https://api.youversion.com/v1/bibles",
headers={"X-YVP-App-Key": KEY})
Response:
HTTP 422 Unprocessable Entity
{"detail": [{"type": "missing",
"loc": ["query", "language_ranges[]"],
"msg": "Field required"}]}
The listing endpoint requires at least one ISO 639-3 language filter. We found that out the way everyone does — by reading the 422 body. Correct form:
httpx.get(
"https://api.youversion.com/v1/bibles",
params={"language_ranges[]": "eng"}, # eng, rus, ukr, etc.
headers={"X-YVP-App-Key": KEY},
)
If you're calling from a JS client and reach for URLSearchParams, the brackets matter — language_ranges[] with the literal brackets works, language_ranges without them does not.
Side note while you're here: the auth header is X-YVP-App-Key, not Authorization: Bearer. The 401 you get from forgetting is generic enough that you'll sit there comparing your key character-by-character before going back to the docs. Pin the header name in the integration's docstring on day one.
Footgun #2: all_available=true reveals the real catalog
With language_ranges[]=eng,rus,ukr we got 11 Bibles back — all English (ASV, BSB, Geneva, CPDV, etc.). Zero Russian. Zero Ukrainian.
The marketing number is 1,474 translations. Where are they?
httpx.get(
"https://api.youversion.com/v1/bibles",
params={"language_ranges[]": "rus", "all_available": "true"},
headers={"X-YVP-App-Key": KEY},
)
That returns 5 Russian Bibles: NRT (Новый Русский Перевод — the modern Russian we needed), three CARS variants, and CSLAV (church Slavonic). For Ukrainian: just UKRK 1905 — pre-revolutionary, hard for modern students. No modern Огієнко or UBIO in the platform yet.
The mental model: the listing endpoint without all_available shows what is enabled for your app key, not what exists in the platform. Fetching a passage via /bibles/{id}/passages/{ref} works for the broader catalog regardless of listing visibility — at least for non-commercial use as of this writing.
Worth two minutes verifying for your own keys before you build a UI that says "no Russian translations available." We almost did.
Footgun #3: content is HTML, even when you didn't ask
The passage endpoint is the cleanest part of the API. You hand it a Bible ID and a USFM ref:
GET /v1/bibles/143/passages/JHN.3.16
→ {
"id": "JHN.3.16",
"content": "<p>Ведь Бог так полюбил этот мир...</p>",
"reference": "От Иоанна 3:16"
}
Two things to notice. First, reference is localized to the Bible's language — "От Иоанна 3:16" for NRT, "John 3:16" for BSB, automatically. That is free i18n you would otherwise build yourself.
Second, content is HTML. Usually a thin <p> wrapper, sometimes with <span> markers, occasionally a chunk of whitespace bleeding from the source USFM. If you're rendering scripture in a plain-prose sidebar card, you have to strip:
def _strip_html(html: str) -> str:
text = re.sub(r"<[^>]+>", "", html)
# Some responses pack newlines inside <p> from the source markup —
# collapse whitespace so the card renders as a single tidy line.
text = re.sub(r"\s+", " ", text).strip()
return text
YouVersion never injects user-supplied markup into content (it is their licensed text — they control the source), so a regex strip is safe here. Do not copy this pattern verbatim to places where the content origin is untrusted.
Footgun #4: their VOTD endpoint exists, but you cannot pick the verses
YouVersion ships /v1/verse_of_the_days/{day} that returns their curated verse for that day of year:
GET /v1/verse_of_the_days/135
→ { "day": 135, "passage_id": "ISA.12.2" }
Useful if you want to mirror the YouVersion app behavior exactly. But it is their selection — you cannot pass a tag, theme, or audience filter. For an LMS aimed at Bible-school students we wanted curated passages that bias toward doctrinally-neutral, evergreen, ecumenical scripture: no denomination-specific proof texts, nothing that translates badly into Russian or Ukrainian.
So we rolled our own list — 250 references covering salvation, hope, comfort, love, faith, wisdom, prayer, and perseverance. Grouped by canon section: Gospels, Acts, Pauline epistles, Hebrews and General epistles, Revelation, Psalms, Proverbs, Wisdom and Prophets, Torah and Historical books, Job and Minor prophets.
The shape that worked: deterministic by day, cached by day
Selection is a one-liner:
def _pick_reference(date: dt.date) -> str:
"""Everyone, everywhere, sees the same verse on a given UTC date."""
return _VERSES[date.toordinal() % len(_VERSES)]
toordinal() gives a globally monotonic integer. Modulo the catalog size, you get a cycle that takes about eight months to repeat — long enough that no student sees the same verse twice in a school term. No randomness, no per-user state, no cache invalidation drama. The verse on a given date is the same in every browser on every device.
Cache is a process-local dict keyed on (date_iso, locale). Evict any entry whose date is not today on every write — the cache never holds more than len(supported_locales) entries. We support en and ru, so at most two entries deep:
with _CACHE_LOCK:
for k in list(_CACHE):
if k[0] != date_iso:
_CACHE.pop(k, None)
_CACHE[cache_key] = verse
Two YouVersion calls per Python process per day. If the API key is unset (CI, fresh local dev), the service raises a typed exception and the route returns 404. The frontend treats 404 as "hide the card silently."
Never block the dashboard on a third party. Same playbook as every other optional widget — but worth restating, because Bible-school students will not forgive a broken homepage on a Sunday.
A few things to weigh before you adopt this
-
Non-commercial lock-in is real. You agree at app registration. Future paywalls, ads, or paid tiers revoke API access. For an open-source LMS this is fine. For a commercial product, model around it on day one — your
BibleProvidershould be an adapter, not a hard import. - Russian coverage is solid, Ukrainian is sparse. Modern Russian is there (NRT). Ukrainian audiences still need a fallback layer for modern translations.
- The SDKs ship UI components, not just data clients. If you're using their React SDK you may not need most of the integration code above. We chose the REST API because Verse of the Day in our app is server-cached and renders in a slot we already control.
What I'd ask the room
If you have integrated YouVersion Platform yourself — how are you handling the locale → bible_id mapping when there are multiple translations in the same language? We pick one per locale (en → BSB, ru → NRT) because Verse of the Day is a one-card, one-rendering surface. For a reading-plan flow where users want to switch translations on the fly the design space is wider — curious what others have done.
For anyone building Christian software in 2026 — does the non-commercial lock-in change how you architect, or do you accept it and never plan to monetize? Genuinely curious whether anyone has built around the constraint.
And for the YouVersion Platform team if you read this: an Accept: text/plain toggle on /passages would let consumers skip the strip-HTML dance. Probably trivial on your side, ergonomic win on ours.
ArVaViT
/
equip
Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.
Equip
A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs
Live demo · Roadmap · Contributing · Changelog
Why this project?
Hundreds of small Bible schools, home churches, and missionary training programs around the world still manage courses on paper, WhatsApp, or spreadsheets. Commercial LMS platforms are expensive, overkill, or require technical expertise that volunteer-run organizations simply don't have.
Equip is designed to change that:
- Free forever — MIT-licensed, no paywalls, no "premium" tiers.
- Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
- Built for small scale — optimized for 20-100 students, not enterprise pricing models.
- Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.
Features
| Area | What you get |
|---|---|
| Course authoring | Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio) |
| Assessments | Multiple-choice, true/false, short-answer, and essay |