query.getbible.net /v2/
The getBible query endpoint: give it a scripture reference, get the verses. public, metered · tokens unlimited API v2
The one route
GET https://query.getbible.net/v2/{translation}/{reference}| Part | Meaning | Examples |
|---|---|---|
v2 | API version; serves Bible data version v2. | v2 |
translation | Translation abbreviation. | kjv, aov, vulgate |
reference | A scripture reference, or several separated by ;. Book names, abbreviations, chapters, verses and ranges are all understood. | John3:16, Genesis 1:1-3, Ps23;Mat7:7 |
curl https://query.getbible.net/v2/kjv/John%203:16The response is a JSON object with one entry per chapter, keyed {translation}_{book}_{chapter}, each holding the translation metadata, the references that selected it, and its verses. Responses carry Cache-Control: public, max-age=2592000 and an ETag; the full description is in openapi.json.
Scripture comes from the selected v2 data source. Chapter entries carry compact translation metadata. Verse objects retain their source fields, including nested metadata: v3 can include paragraph, word-level tokens and annotation spans. These fields are optional and are not added when absent from the source. Chapter-level editorial from static v3 documents is excluded from assembled results. See the source data contract for the static documents.
Short forms
A valid reference in a shorter route is a permanent redirect (301) to its canonical route. When a translation is omitted, the reference is resolved in kjv. A missing or unresolved reference returns 404; an explicitly supplied unknown translation also returns 404. No request is replaced with a default verse.
| Request | Redirects to |
|---|---|
/v2/John3:16 | /v2/kjv/John3:16 |
/aov/John3:16 | /v2/aov/John3:16 |
/John3:16 | /v2/kjv/John3:16 |
For example, /v2/kjv has no reference and answers 404. The same applies when a reference cannot be resolved, including a request containing one valid and one invalid reference. A query string answers 400, because this endpoint takes no parameters. Public documentation pages remain available at their published addresses.
Access
This endpoint is public and metered. Anonymous callers share a budget per client address; callers with a bearer token are not limited at all.
| Budget (per address) | Value |
|---|---|
| Sustained rate | 50 requests per second, bursts up to 250 |
| Per hour | about 100000 requests |
| Per day | about 1000000 requests |
| Concurrent connections | 100 |
Budgets are enforced as token buckets, so steady traffic under the quota is never touched and bursts above it are slowed with a 429 rather than cut off.
Using a token
Send it as a bearer credential. Tokens never go in the URL.
curl -H "Authorization: Bearer gb..." https://query.getbible.net/v2/kjv/John3:16Tokens are issued to applications and partners by the getBible team; ask through getBible.net.
Documentation pages, openapi.json, GET /healthz and GET /readyz are available without a token. Token checks apply to API data requests.
Errors
Every error is an RFC 9457 problem document (application/problem+json) with type, title, status, code, detail and instance. The detail field carries the message.
| Status | Code | Meaning |
|---|---|---|
| 400 | request_limit | Too many references or verses in one request. |
| 400 | parameters_not_accepted | A query string was sent. |
| 401 | unauthorized | A bearer token is required and was missing or invalid. |
| 404 | missing_reference | No scripture reference was supplied. |
| 404 | invalid_reference | The reference does not resolve. |
| 404 | not_found | The requested scripture or route was not found. |
| 404 | translation_not_found | No such translation. |
| 404 | unknown_version | Only v2 is served here. |
| 429 | rate_limited | The public budget for your address is used up. |
| 503 | repository_unavailable, readiness_failed | The Scripture files are temporarily unreadable. |
Health
GET /healthz answers when the service is up; GET /readyz answers 200 only after reading scripture for the configured readiness reference (Mat7:7), or 503 with a problem document and Retry-After when unavailable. The readiness reference is not a fallback for API requests. Token-protected responses use Cache-Control: private, no-store.