Read John chapter 3

Bible v2 provides a compact, stable JSON hierarchy for applications that need Scripture text. Each translation, book and chapter is an independently addressable file. No database query, request body or URL query parameter is required.

Base URL: https://api.getbible.net/v2/

Live documentation · OpenAPI JSON · All Bible API versions · Support

Quick start#

# Read John chapter 3
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/kjv/43/3.json'

# Read the whole book of John
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/kjv/43.json'

# Download the complete KJV for an offline application
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/kjv.json' --output kjv-v2.json

These are different views of the same translation. The book and chapter files do not represent additional corpora to append to the whole-translation file.

Path parameters#

Name	Type	Requirement
abbreviation	String	Required on translation-specific paths. Use a lowercase identifier from translations.json, such as kjv, aov or vulgate. The v2 schema uses ^[a-z0-9]+$.
book	Integer	Required on book/chapter paths. Use the translation's books.json; the v2 contract allows 1–89.
chapter	Integer	Required for a chapter document. Positive integer listed by that book's chapters.json.

There is no default translation on a static file path. To obtain a single verse, use Query v2, for example https://query.getbible.net/v2/kjv/John3:16.

Every resource#

All paths below are relative to the v2 base URL and use GET. HEAD retrieves headers; OPTIONS supports browser preflight.

Path	Result
translations.json	Object containing metadata for all translations, keyed by abbreviation
translations.txt	Tab-separated translation index
translations.sha	SHA-1 of translations.json
checksum.json	Translation abbreviations mapped to translation-file hashes
checksum.txt	Tab-separated translation checksum index
checksum.sha	SHA-1 of root checksum.json
{abbreviation}.json	Complete translation with all books and verses
{abbreviation}.sha	SHA-1 of that complete translation
{abbreviation}/books.json	Available books with metadata, URLs and hashes, keyed by book number
{abbreviation}/books.txt	Tab-separated book index
{abbreviation}/books.sha	SHA-1 of books.json
{abbreviation}/checksum.json	Book numbers mapped to book-file hashes
{abbreviation}/checksum.txt	Tab-separated book checksum index
{abbreviation}/checksum.sha	SHA-1 of that book checksum index
{abbreviation}/{book}.json	Complete book, including its chapters
{abbreviation}/{book}.sha	SHA-1 of the book document
{abbreviation}/{book}/chapters.json	Available chapters with metadata, URLs and hashes, keyed by chapter number
{abbreviation}/{book}/chapters.txt	Tab-separated chapter index
{abbreviation}/{book}/chapters.sha	SHA-1 of chapters.json
{abbreviation}/{book}/checksum.json	Chapter numbers mapped to chapter-file hashes
{abbreviation}/{book}/checksum.txt	Tab-separated chapter checksum index
{abbreviation}/{book}/checksum.sha	SHA-1 of that chapter checksum index
{abbreviation}/{book}/{chapter}.json	Complete chapter and its verses
{abbreviation}/{book}/{chapter}.sha	SHA-1 of the chapter document
openapi.json	The generated OpenAPI 3.1 contract
openapi.sha	SHA-1 of the OpenAPI document

Index .txt files start with a header line beginning with #. Their records are separated by newlines and columns by tabs. Read the header instead of assuming every index level has identical columns.

Discovery workflow#

# Find available translation identifiers and metadata
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/translations.json'

# Find the books of a selected translation
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/kjv/books.json'

# Find John's chapters
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/kjv/43/chapters.json'

Translation, book and chapter index entries include url and sha. Follow those URLs and store the matching hash. Book numbers in JSON object keys are strings, while nr, book_nr and chapter inside records are integers.

Response fields#

The six shared translation fields appear on standalone book and chapter documents:

Field	Type	Meaning
translation	String	Display name, such as King James Version
abbreviation	String	Translation identifier, such as kjv
lang	String	Source language code, such as en
language	String	Language label, such as English
direction	String	LTR or RTL
encoding	String	Source module encoding label

Do not replace an empty source language label with a guessed value. Use direction to choose the appropriate text flow.

Chapter document#

Field	Type	Meaning
Shared translation fields	Strings	The six fields above
book_nr	Integer	Stable GetBible book number
book_name	String	Book name supplied for this translation
chapter	Integer	Chapter number
name	String	Chapter display name, for example John 3
verses	Array of verse objects	Every verse in the chapter

Each v2 verse contains chapter (integer), verse (integer), name (string) and text (string). A selected verse record from the live John 3 chapter is:

{
  "chapter": 3,
  "verse": 16,
  "name": "John 3:16",
  "text": "For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life."
}

This is one record from verses; the chapter endpoint returns the complete chapter, not a one-verse response.

Book document#

The top level contains the shared translation fields, nr, name and chapters. Here nr is the book number and name is the book name. Each nested chapter contains chapter, name and verses; the enclosing book supplies its translation and book context.

Translation document and catalogue#

A whole translation has books, an array of book objects. Each book has nr, name and chapters. The document also includes these source metadata fields:

Field	Type	Meaning
description	String	Source translation description
distribution_lcsh	String	Source subject heading
distribution_version	String	Source module version
distribution_version_date	String	Source version date
distribution_abbreviation	String	Original module abbreviation
distribution_about	String	Source description of the text
distribution_license	String	Distribution terms recorded by the source
distribution_sourcetype	String	Source markup type
distribution_source	String	Source provenance
distribution_versification	String	Source versification system
distribution_history	Object of strings	Source history entries

The translation catalogue contains this metadata without the books hierarchy, adding the document url and sha. Obtain it once and join by abbreviation. Query and search results intentionally carry only the six shared translation fields.

Checksum-aware downloads#

A .sha response is a 40-character lowercase hexadecimal SHA-1 followed by a newline. It hashes the JSON file's bytes, not a parsed or reformatted object.

# Download a chapter and its corresponding change token
curl --fail-with-body --compressed \
  'https://api.getbible.net/v2/kjv/43/3.json' --output john-3-v2.json
curl --fail-with-body \
  'https://api.getbible.net/v2/kjv/43/3.sha' --output john-3-v2.sha

# Compare the advertised hash with the downloaded file on Linux
expected_hash=$(tr -d '\r\n' < john-3-v2.sha)
printf '%s  %s\n' "$expected_hash" john-3-v2.json | sha1sum --check --status

A nonzero check means the pair should not be committed to the application cache. A publication may have changed between the two downloads; retrieve a matching pair again. Store replacement payloads and hashes atomically. These hashes detect a data change; they are not authentication credentials or signatures.

For long-lived v2 Scripture caches, keep each payload's exact translation/book/chapter scope hash and the time of its last successful check. Recheck at least weekly; invalidate a changed scope and its descendants. If rechecking fails, retain the previous check time and describe the content as stale. See the complete v2 cache policy.

HTTP caching and browser use#

Respect Cache-Control on each response. Retain ETag for revalidation, and use If-None-Match to receive 304 when the representation is unchanged. The .sha resources generally have a shorter freshness lifetime than Scripture documents. Actual deployment headers are authoritative.

# Save an ETag for the catalogue
curl --fail-with-body --compressed \
  --etag-save translations-v2.etag \
  'https://api.getbible.net/v2/translations.json' \
  --output translations-v2.json

# Inspect a subsequent conditional response; 304 has no JSON body
curl --include --compressed \
  --etag-compare translations-v2.etag \
  'https://api.getbible.net/v2/translations.json'

Open CORS permits browser reads. GET, HEAD and OPTIONS are accepted; preflights return 204. Query strings are rejected, including cache-busting parameters. Use conditional headers instead.

Access and tokens#

The live service is public and metered. Anonymous budgets are per client address; a valid token exempts its holder from those public rate budgets. Token privileges do not remove input validation or guarantee service availability.

Ask through support or [email protected] for application or partner access. Specify api.getbible.net; a token for another domain is not interchangeable. Set the issued value in the GETBIBLE_API_TOKEN environment variable before running:

curl --fail-with-body --compressed \
  --header "Authorization: Bearer ${GETBIBLE_API_TOKEN:?Set GETBIBLE_API_TOKEN to your issued token}" \
  'https://api.getbible.net/v2/kjv/43/3.json'

Errors and troubleshooting#

Errors use application/problem+json, with type, title, status, code, detail and instance. Handle the status before parsing a successful Scripture response.

HTTP	Code	What to do
400	bad_request	Remove query parameters or fix the malformed request
401	unauthorized	Check token validity where token-only access is configured
404	not_found	Check the version and discover the resource through the indexes
405	method_not_allowed	Use GET, HEAD or OPTIONS
429	rate_limited	Respect Retry-After; reduce request frequency and reuse cached data
503	unavailable	Retry a temporary outage after a short delay

GET https://api.getbible.net/healthz is a liveness endpoint. When reporting a problem, include X-Request-ID, the exact resource URL and HTTP status at the single support desk.

OpenAPI and API clients#

Import the live v2 OpenAPI JSON into Postman's Import dialog to create requests from the contract. Its servers value already ends in /v2; its paths start below that base. Do not add the version twice. No API token is necessary to download the contract.

For the generation pipeline, see v2_builder. For the common deployment behavior, see the service overview and access and caching documentation.

Complete contract reference#

Open the complete endpoint and schema reference for every operation, parameter, response and component model in the published OpenAPI contract.