API DOCUMENTATION
Read a chapter with its available v3 metadata
Bible v3 publishes Scripture text together with the source information needed for richer reading and study applications. The basic translation → book → chapter → verse structure is familiar from v2. Optional metadata adds word-level lexical attributes, annotations, paragraph starts, chapter layout and introductory material when the source supplies them.
Base URL: https://api.getbible.net/v3/
Live documentation · OpenAPI JSON · All Bible API versions · Support
Quick start#
# Read a chapter with its available v3 metadata
curl --fail-with-body --compressed \
'https://api.getbible.net/v3/kjv/43/3.json'
# Read a complete book
curl --fail-with-body --compressed \
'https://api.getbible.net/v3/kjv/43.json'
# Download an entire translation for offline reading
curl --fail-with-body --compressed \
'https://api.getbible.net/v3/kjv.json' --output kjv-v3.json
The static API returns published files and accepts no URL query parameters. To resolve John3:16, use Query v3. To find verses containing words, use Search v3.
Inventory and addresses#
curl --fail-with-body --compressed 'https://api.getbible.net/v3/translations.json'
curl --fail-with-body --compressed 'https://api.getbible.net/v3/kjv/books.json'
curl --fail-with-body --compressed 'https://api.getbible.net/v3/kjv/43/chapters.json'
Indexes are JSON objects keyed by translation abbreviation, book number or chapter number. Follow each entry's url and retain its sha. They list the resources actually published for the selected translation.
| Parameter | Type | Rules |
|---|---|---|
translation |
String | Abbreviation from translations.json; pattern ^[a-z0-9][a-z0-9_-]{0,29}$ |
book |
Integer | Actual number listed by books.json; minimum 1, maximum 281474977710655 |
chapter |
Integer | Positive chapter number from the book's chapters.json |
Established addresses remain stable: Genesis is 1, Matthew 40, John 43 and Revelation 66. Established additional books continue through 89. Previously unseen source book identities can receive deterministic numbers starting at 1000000. Those values remain exactly representable in JavaScript; avoid storing book identifiers in a database column restricted to a tiny integer or assuming every translation ends at book 66.
Chapter and verse numbering follows the translation's own versification. A book containing only source titles or introductions can be present even if its chapters array is empty. A chapter with introductory material but no verse text remains inside its book/translation with an empty verses array; it has no standalone chapter file or chapter-index entry. These cases preserve supplied source content without inventing Scripture positions.
Every described resource#
Each path below is relative to the v3 base. Every JSON file has the listed .sha companion.
| JSON path | Contents | Hash path |
|---|---|---|
translations.json |
Translation catalogue, keyed by abbreviation | translations.sha |
checksum.json |
Whole-translation hashes | checksum.sha |
openapi.json |
Generated standalone OpenAPI 3.1 contract | openapi.sha |
{translation}.json |
Translation and all its books | {translation}.sha |
{translation}/books.json |
Book catalogue for a translation | {translation}/books.sha |
{translation}/checksum.json |
Book hashes for a translation | {translation}/checksum.sha |
{translation}/{book}.json |
One book and its chapters | {translation}/{book}.sha |
{translation}/{book}/chapters.json |
Published chapters for a book | {translation}/{book}/chapters.sha |
{translation}/{book}/checksum.json |
Chapter hashes for a book | {translation}/{book}/checksum.sha |
{translation}/{book}/{chapter}.json |
One chapter and its verses | {translation}/{book}/{chapter}.sha |
The builder also produces extensionless tab-separated companion listings, but these are not described by the v3 OpenAPI contract. Use the documented JSON indexes on the public endpoint; do not assume that v2's .txt routes exist in v3.
Core response structure#
Standalone chapter documents contain:
| Field | Type | Meaning |
|---|---|---|
translation |
String | Translation display name |
abbreviation |
String | Translation identifier |
lang |
String | Language code supplied by the source |
language |
String | Language label; can be empty when no label is available |
direction |
String | Reading direction, normally LTR or RTL |
encoding |
String | Source module encoding label; generated JSON is UTF-8 |
book_nr |
Integer | Stable GetBible book identity |
book_name |
String | Translation's book name |
chapter |
Integer | Chapter number |
name |
String | Chapter display name |
verses |
Array | Ordered verse objects |
editorial |
Array, optional | Ordered chapter headings and paragraph ranges |
introduction |
Array, optional | Source introduction entries, each with text |
A book contains the shared translation fields, nr, name and chapters, plus any available titles and introduction. A full translation has books and source distribution metadata. Nested chapters carry the same chapter-level reading data as their standalone representation after shared translation/book context is removed.
Use translations.json for translation descriptions, history, provenance, version and distribution terms. The catalogue includes source fields such as description, distribution_about, distribution_license, distribution_source, distribution_versification and distribution_history, alongside url and sha. These broad translation details do not need to accompany every selected verse in your application.
Reading a verse#
Every verse includes the core fields chapter, verse, name and text. text is the display text. It does not begin with a line ending; line endings within the verse are preserved. Do not rebuild display text by joining token strings: source tokens and displayed words do not always map one-to-one.
| Optional field | Meaning |
|---|---|
paragraph: true |
The source marks this verse as beginning a paragraph |
tokens |
Word-level records in reading order, with source lexical attributes and display positions |
spans |
Source annotations covering token and display-word ranges |
The static v3 contract pairs tokens and spans when source word markup exists; an empty span array is valid. A source without the relevant markup does not receive fabricated tokens or annotations.
Tokens: lexical information without losing display position#
A token's required fields are token, word_start and word_end. For example, the live John 3:16 data includes this token for “the world”:
{
"token": "the world",
"lemma": {
"strong": ["G3588", "G2889"],
"lemma.TR": ["τον", "κοσμον"]
},
"morph": {
"robinson": ["T-ASM", "N-ASM"]
},
"src": [6, 7],
"word_start": 5,
"word_end": 6
}
| Token member | Type | Meaning |
|---|---|---|
token |
String | Visible token text; may cover more than one display word |
word_start, word_end |
Integers | Inclusive positions in whitespace-separated display words, starting at 1; 0 means unlocated |
lemma |
Object of string arrays | Lexical identifiers grouped by scheme, such as strong or lemma.TR |
morph |
Object of string arrays | Morphological attributes grouped by source scheme |
xlit |
Object of string arrays | Transliterations grouped by source scheme |
src |
Array of integers/strings | Source positions carried by the module |
gloss |
String | Source gloss when present |
n, type, subType, variantType |
Strings | Additional source token attributes |
variant, morphSegmented |
Booleans | Additional source flags |
Only the required token members can be assumed. Lexical schemes and attributes are source-dependent; preserve them rather than replacing their grouped structure with one flat string. The Dictionaries API supplies related lexical resources, with its own discovery and key conventions.
Spans: two coordinate systems#
The spans array describes supported annotations such as divineName, transChange and q. The live 1 Corinthians 13:13 data includes a supplied-word annotation:
{
"tag": "transChange",
"span": "is",
"token_start": 11,
"token_end": 11,
"attrs": {"type": "added"},
"word_start": 14,
"word_end": 14
}
| Coordinate | Interpretation |
|---|---|
token_start / token_end |
Zero-based, inclusive indexes into this verse's tokens array |
word_start / word_end |
One-based, inclusive positions in whitespace-separated text; 0 means not located |
tag identifies the source annotation, span contains its text and optional attrs retains its string attributes. Highlighting can use display-word ranges; lexical inspection can use token ranges. Do not treat either range as a byte or character offset. One token can span several words, so the two coordinate systems are intentionally different.
Chapter editorial layout#
The optional editorial array is the chapter's ordered reading layout. order runs contiguously from 0 across headings and paragraphs. It is present consistently in the standalone chapter and the same chapter nested in a book or whole translation.
Headings#
A heading contains exactly order, type: "heading", anchor, text, heading_type and canonical. anchor.verse is an emitted verse in this chapter; anchor.edge is before.
{
"order": 0,
"type": "heading",
"anchor": {"verse": 1, "edge": "before"},
"text": "CHAPTER 3.",
"heading_type": "chapter",
"canonical": false
}
heading_type reflects the source title type, or unspecified when absent. canonical is true only when explicitly marked by the source. It records source metadata and is not an independent theological judgment by the builder.
Paragraphs#
A paragraph contains exactly order, type: "paragraph", start and end. Its range is inclusive and uses emitted verse numbers in the current chapter:
{
"order": 3,
"type": "paragraph",
"start": 16,
"end": 17
}
When paragraph entries exist, their ranges cover the chapter's emitted verses contiguously. An implicit opening range can precede the first explicit paragraph start. If the source supplies no paragraph starts, no paragraph ranges are manufactured. Headings may still exist. The entire editorial field is absent when there are neither headings nor explicit paragraph markers.
Chapters containing verses do not duplicate headings in a titles array, and verse objects do not contain titles. Use editorial for their headings. A chapter without published verses may retain title metadata only in its nested representation.
Titles and introductions#
Titles belong to the translation or book that supplies them. A title has text and may also carry type, canonical, subtype, and title-local tokens/spans when available. Introduction prose is an array of objects with a text member, placed at the translation, book or chapter level. Optional data is absent when the source has nothing to provide.
The published API deliberately excludes the extraction stream's raw byte projections, base64 fields and source-contract envelopes. The reading representation is documented by the builder's checked-in schemas and generated OpenAPI contract.
Integrate with query and search#
Query v3 and Search v3 preserve the selected verses' full source objects, including nested tokens and spans. Their assembled chapter results carry compact translation metadata and intentionally omit static chapter-level editorial. Fetch the static chapter when the application needs full paragraph and heading layout.
For an app moving from v2, keep its text renderer, add optional metadata handling and partition caches by API version. Validate the translations actually required by the app; do not assume that changing /v2/ to /v3/ supplies identical data, catalogue contents or hashes.
Caching, hashes and access#
Every JSON resource has a .sha sibling containing its SHA-1 as 40 lowercase hexadecimal characters and a newline. Hashes identify the exact JSON bytes. Index entries also provide the sha of their target. Re-download and atomically replace changed documents with their matching hashes; do not hash a pretty-printed transformation and compare it with the original file hash.
HTTP freshness is separate. Respect returned Cache-Control, use ETag with If-None-Match, and treat 304 as permission to reuse the saved body. Static files also provide Last-Modified. Open CORS allows browser access. The accepted methods are GET, HEAD and OPTIONS; query strings are rejected.
Public access is metered by client address. Applications and partners can request a bearer token or contact support. A token is scoped to its issuing domain and must be sent in an Authorization: Bearer header, never in a query parameter. Public rate exemption does not bypass structural or execution limits.
Errors#
| HTTP | Code | Meaning |
|---|---|---|
| 400 | bad_request |
Malformed request or a query string on a static path |
| 401 | unauthorized |
Missing/invalid credential when token-only access is configured |
| 404 | not_found |
Resource not published at that path |
| 405 | method_not_allowed |
Use GET, HEAD or OPTIONS |
| 429 | rate_limited |
Respect the response's Retry-After value |
| 503 | unavailable |
Temporary service outage |
Error bodies use application/problem+json and carry type, title, status, code, detail and instance. Include the X-Request-ID response header in a support request.
OpenAPI import and sources#
The v3 specification intentionally has no host in servers and its paths already begin with /v3. When importing the raw contract into Postman, set the server/base host to https://api.getbible.net if the importer asks. The resulting chapter request must be https://api.getbible.net/v3/kjv/43/3.json, with the version appearing once.
This guide follows the live v3 contract, live service documentation, generated-output documentation, and runtime response contract.
Complete contract reference#
Open the complete endpoint and schema reference for every operation, parameter, response and component model in the published OpenAPI contract.