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

## Quick start

```bash
# 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](/api/query/v3/). To find verses containing words, use [Search v3](/api/search/v3/).

## Inventory and addresses

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

```json
{
  "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](/api/dictionaries/) 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:

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

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

```json
{
  "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](https://github.com/getbible/v3_builder/tree/master/schema) and generated [OpenAPI contract](https://api.getbible.net/v3/openapi.json).

## Integrate with query and search

[Query v3](/api/query/v3/) and [Search v3](/api/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](mailto:getBible@TrueChristian.church) or contact [support](https://git.vdm.dev/getBible/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](https://git.vdm.dev/getBible/support).

## 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](https://api.getbible.net/v3/openapi.json), [live service documentation](https://api.getbible.net/v3/), [generated-output documentation](https://github.com/getbible/v3_builder/blob/master/docs/static-output.md), and [runtime response contract](https://github.com/getbible/api/blob/main/docs/RUNTIME_ENDPOINTS.md).

## Complete contract reference

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