IQ Bible API v2 — what’s shipped since beta-54

v2.0.0-rc.1 · everything worth calling out from beta-55 through the 2.0.0 release candidate

Since the beta-54 roundup we’ve kept a near-daily cadence, and as of September 7 v2 is at 2.0.0-rc.1 — the public API surface, response contracts, pricing, and served version catalog are now frozen for the 2.0.0 GA. What landed on the way there: verse-card images built for link previews, a responsive image pipeline for the illustration catalog, guided onboarding in the developer portal, and a catalog-wide content-health pass. Here’s what you’d build against.

---

The 2.0.0 release candidate

The beta → rc step means the surface you build against is final: from here, only defects found in RC testing land before the plain 2.0.0 heading. No breaking changes to endpoints, parameters, or response shapes are planned between now and GA. Every version the API serves now reads content-health good, and the staged lexicon and verse-text fixes are verified in production. A short list of non-blocking, non-breaking items — cosmetic version_id / language_code cleanup, a content-health false-positive allowlist, two reading-plan enhancements — is deferred to a point release after GA.

Overage billing — for requests and for audio minutes — is now wired on every paid plan, so the pricing you sign up under is the pricing that carries into GA.

---

Verse-card images, built for link previews

GET /api/v2/image/verse now renders a proper link-preview card. Pass ?preset=og for a 1200×630 image (the summary_large_image size Facebook and LinkedIn upscale a smaller card to) or ?scale=1.0–3.0 for finer control; the default 600×315 is unchanged, so existing embeds are untouched. ?ref= accepts a verse range (GAL.5.14-16) and a whole chapter (GAL.5), not just a single verse. Both image/verse and parse/citation now trim a leading editorial mark (¶, §, *) that some KJV-tradition editions carry — noise on a share card — while every other verse-text route returns it verbatim.

Two fixes for the crawlers that build previews: HEAD on /embed/verse and /image/verse no longer returns 401, and GET /api/v2/parse/citation (single citation) is now public with no API key, same as the two image endpoints — a fork building the same Scripture previews shouldn’t have to proxy a key. Free-text parse/citations stays key-gated.

The public routes also got more headroom: a 24-hour immutable cache on card responses, parse/citation cached for an hour, and the per-IP rate limit on public routes raised to 120 requests/minute, so a crawler unfurling a page full of shared links won’t hit a 429 mid-preview.

---

A responsive image pipeline for the illustration catalog

GET /api/v2/illustrations/{book}/{chapter} entries carry an image object — src, srcset, full, plus width/height. Every URL takes a ?w=<px> parameter, and the media layer serves the closest pre-generated variant at or above that width as WebP or JPEG per the request’s Accept header. A Doré plate rendered inline at ~250px pulls a ~40 KB WebP instead of a 1–3 MB master. The variants are a fixed width ladder (320 / 640 / 960 / 1280 / 1920), generated once as a build step — nothing new runs in the API. width and height are the master’s intrinsic size, constant across the ladder, so a client can reserve the plate’s layout box before it loads instead of reflowing the page as each one arrives.

The API Explorer in the developer portal gained an in-page lightbox for image results — thumbnails at 320px, the lightbox at ~1280px, the multi-megabyte master only on an explicit “Open original” click — instead of a browser tab per plate.

---

Guided onboarding in the developer portal

A first-visit welcome dialog now offers a guided Tour — a spotlight walkthrough of every nav panel, plus an opt-in deep dive into the API Explorer’s search, attribute-to-app, send and code-snippet flow — re-launchable any time from the Help panel.

The Overview panel gained a Getting Started checklist tracking five first-run steps: verify email, create your first key, make your first call, group keys into an app, and grab a client snippet. Signup now lands on a persistent “check your email” screen with a resend link, rather than flashing a one-line confirmation and bouncing to the login form.

---

Data quality and the served catalog

• Catalog readiness pass. Roughly 270 versions that don’t pass the deep content-health scan now return a clear 503 on a direct hit instead of sitting in a “still processing” limbo and answering version_not_ready. GET /bibles is unchanged — it only ever listed healthy versions — so every version it returns is good. The gated set is mostly fragmentary source texts and agglutinative-language false positives from an earlier bulk import.
• eng_darby (Darby Bible, 1889) was missing the space before the divine name “God” throughout — 3,681 occurrences across 3,241 verses. Fixed, and back in the served catalog.
• Arabic versions are listed as “Arabic” again in GET /bibles and GET /bibles/languages, not “Standard Arabic” (SIL’s reference name for the individual language code), which had filed them under “S” in a client that sorts its list by language name.
• The OpenAPI spec’s dangling $ref (GET /morphology/{code}’s response schema, never added when that endpoint shipped) is fixed — it had been making RapidAPI Studio reject the whole document on import. Every internal reference in the spec now resolves.
• /illustrations was returning 500 in production — a dimensions migration shipped ahead of being applied. Fixed, and 6,743 rows backfilled.

---

What’s next

When RC testing clears, 2.0.0 GA, with the deferred items following in a point release. Beyond GA, v2 keeps moving on study depth and the developer surface.

We build the biblical data infrastructure. You build the tools that help people encounter God’s Word. Build boldly, build well.