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](https://api.getbible.net/v2/) · [OpenAPI JSON](https://api.getbible.net/v2/openapi.json) · [All Bible API versions](/api/bible/) · [Support](https://git.vdm.dev/getBible/support)

## Quick start

```bash
# 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](/api/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

```bash
# 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:

```json
{
  "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.

```bash
# 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](https://github.com/getbible/mcp/blob/main/site/v2/cache-policy.md).

## 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.

```bash
# 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](https://git.vdm.dev/getBible/support) or [getBible@TrueChristian.church](mailto:getBible@TrueChristian.church) 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:

```bash
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](https://git.vdm.dev/getBible/support).

## OpenAPI and API clients

Import [the live v2 OpenAPI JSON](https://api.getbible.net/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](https://github.com/getbible/v2_builder). For the common deployment behavior, see [the service overview](https://api.getbible.net/) and [access and caching documentation](https://github.com/getbible/api/blob/main/docs/ACCESS_MODES.md).

## Complete contract reference

Open the [complete endpoint and schema reference](/api/bible/v2/reference/) for every operation, parameter, response and component model in the published OpenAPI contract.