Commentaries API v1

Read commentary as plain-text JSON at chapter, book, or whole-module scale. The document root is https://commentaries.getbible.net/v1/. All published operations are static GET requests, with no request bodies, query parameters, or authentication scheme defined by the contract.

API overview · Service documentation · OpenAPI JSON · Builder source · Public support

Quick start#

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/commentaries.json'

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/metadata.json'

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/books.json'

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/43/1.json'

The catalog supplies the commentary identifiers, names, languages, licenses, counts, and whole-document byte sizes. The book index tells you which book and chapter documents exist for that commentary.

Addressing and coverage#

Parameter	Meaning
`commentary`	Exact module ID from `commentaries.json`, such as `clarke`
`book`	GetBible integer book number, from 1 through 83
`chapter`	Chapter number, including 0 for a book introduction

Genesis is book 1, Daniel 27, Matthew 40, John 43, and Revelation 66. Deuterocanonical books continue through 83. A valid numeric range alone does not guarantee a commentary covers a book or chapter; use its books.json index.

Book introductions use chapter 0, for example clarke/27/0.json. A chapter introduction uses verse 0 inside its chapter response. Keep these in a study introduction view rather than treating them as scripture verse 0.

Read a verse correctly#

A commentary can attach one paragraph to multiple verses. The API stores that comment once, anchors it at the lowest verse it covers, and includes a verses array for its full coverage. A comment without verses covers only its verse.

This cURL and jq example returns all comments covering John 1:3:

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/43/1.json' \
  | jq '[.entries[] | select((.verses // [.verse]) | index(3))]'

Equivalent browser JavaScript:

async function getCommentsForVerse(commentary, book, chapter, verse) {
  const url = new URL(
    `v1/${encodeURIComponent(commentary)}/${book}/${chapter}.json`,
    'https://commentaries.getbible.net/'
  );
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Commentary request failed: HTTP ${response.status}`);
  }
  const document = await response.json();
  return document.entries.filter(entry =>
    (entry.verses ?? [entry.verse]).includes(verse)
  );
}

const comments = await getCommentsForVerse('clarke', 43, 1, 3);
console.log(comments);

Grouping stops at chapter boundaries. A comment that spans a chapter break can appear in both chapter documents so that each document remains usable on its own.

Three compatible response levels#

Resource	Container fields	Nested content
Chapter	`schema`, `commentary`, `language`, `book`, `name`, `chapter`	`entries`
Book	`schema`, `commentary`, `language`, `book`, `name`	`chapters`
Whole commentary	`schema`, `commentary`, `language`, `name`	`books`

Each chapter is embedded unchanged in its book document, and each book is embedded unchanged in the whole commentary. Build a chapter renderer once, then reuse it for the larger downloads.

Entries contain required book, chapter, verse, and text; osis, verses, and references are optional. When present, osis is the source module's key for the anchor verse. The book's display name belongs to the enclosing chapter rather than each entry. There is no separate entry anchor object.

Scripture references#

Commentary text is plain text, with structured citations in optional references arrays. Each citation includes ref, osis, book, and chapter; it may include text, verse, and verses.

text is the citation as printed in the commentary, when located there.
ref is its canonical reference in the module's language.
book, chapter, and optional verse coverage are GetBible coordinates.
verses takes precedence over the anchor verse.
A reference without verse covers the whole chapter.

A cross-chapter range becomes one item per chapter. Book names and verse existence are resolved against the Bible API during the build; the selected translations and naming rules are recorded in metadata. Numeric coordinates support links to the Bible API, while canonical strings support the Query API. Split long lists when they exceed the query service's reference-length limit.

Render commentary with a text-safe method such as textContent, preserving paragraph breaks. Build links from the structured citation data.

Metadata, size, and offline use#

Metadata includes the source module, human name, language, version, license, driver, source type, versification, book/chapter/entry counts, whole-commentary bytes, copyright information, source page, conversion notes, URL templates, and reference provenance.

Its storage block reports source entry and text sizes, deduplicated text size, repetition ratio, and the chapter/book/whole-commentary/published byte totals. These are build measurements, useful for understanding resource size; they do not change the reading contract.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/43.json' \
  --output clarke-john.json

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/hashes.json' \
  --output commentary-hashes.json

With jq and GNU sha256sum, verify the book file against its exact manifest path:

set -euo pipefail

expected="$(jq --raw-output --exit-status \
  '.files["clarke/43.json"]' commentary-hashes.json)"
printf '%s  %s\n' "$expected" clarke-john.json | sha256sum --check -

Fetch one chapter for normal online reading. Offer larger downloads deliberately after checking metadata size. Keep the manifest and content from a consistent build; if they disagree, refresh and retry rather than using an unverified file.

Build health and refreshes#

hashes.json lists the SHA-256 of every generated document except itself. It also provides the definitive list of published paths. Unchanged content is byte-stable across builds, while catalogs and build records may change.

build.json identifies the builder, extractor, contract, build time, source catalog, and Bible API. build-report.json records successful modules, failures, and retained previous modules. A partial report can still describe usable published data. The report is captured before publication; later deployment errors are recorded by the build workflow.

Errors and missing material#

The contract describes HTTP 200 for a JSON document and HTTP 404 when a document does not exist. It does not define an error body format. Always check status before JSON parsing.

A missing commentary chapter can mean that the source has no coverage there. An existing chapter with no entry covering a selected verse is a successful lookup with no commentary for that verse. Do not substitute an unrelated chapter.

HTTP caching, CORS, request limits, and response headers belong to the hosting deployment and are not guaranteed by the generated static-tree specification.

Import into Postman or another OpenAPI client#

Import the OpenAPI 3.1 description. Its paths already contain /v1, and it intentionally specifies no production hostname. Set the client server/base URL to https://commentaries.getbible.net.

Every response schema is embedded and also served from /v1/schema/. Keep per-module provenance and license details with redistributed commentary resources.

Complete endpoint reference#

All paths below are relative to https://commentaries.getbible.net. Every operation returns JSON for HTTP 200 and describes HTTP 404 for a missing document.

GET `/v1/commentaries.json`#

The catalog of every commentary in the tree.

Every commentary this tree holds, with its counts and sizes, and the path template of each of its documents relative to v1/.

No parameters.

Response model: commentary-catalog.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/commentaries.json'

GET `/v1/build.json`#

How and when the tree was built.

The builder and extractor versions, the build time, the module catalog the modules were selected from and the Bible API the references were resolved against.

No parameters.

Response model: build.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/build.json'

GET `/v1/build-report.json`#

The compilation outcome and module failures.

The build status, successfully rebuilt modules, failures with their stage and reason, and previously verified modules retained after a failed rebuild. This snapshot describes compilation; the workflow report also records later publication errors.

No parameters.

Response model: build-report.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/build-report.json'

GET `/v1/hashes.json`#

The SHA-256 of every other document.

The integrity manifest of the tree: a digest for every other document, which is also the complete list of the paths the tree contains.

No parameters.

Response model: hashes.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/hashes.json'

GET `/v1/openapi.json`#

This description.

The OpenAPI description of the tree, generated with it.

No parameters.

Response model: JSON object.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/openapi.json'

GET `/v1/schema/{document}.json`#

The JSON Schema of one document type.

The schemas embedded under components, served beside the data.

Parameter	Type	Required	Meaning
`document`	string	Yes	The document type. Allowed values: "commentary-catalog", "commentary-metadata", "commentary-books", "commentary-chapter", "commentary-book", "commentary", "build", "build-report", "hashes".

Response model: JSON object.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/schema/commentary-chapter.json'

GET `/v1/{commentary}/metadata.json`#

One commentary's provenance, licence, counts and sizes.

Where the module came from, under which licence, how much it holds, how large its whole-commentary document is, and which Bible its references were resolved against.

Parameter	Type	Required	Meaning
`commentary`	string	Yes	The commentary's id, as commentaries.json lists it. Minimum length: 1.

Response model: commentary-metadata.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/metadata.json'

GET `/v1/{commentary}/books.json`#

The books and chapters one commentary covers.

Every book the commentary comments on, with the chapters it has and the number of entries in each book. Chapter 0 is a book introduction.

Parameter	Type	Required	Meaning
`commentary`	string	Yes	The commentary's id, as commentaries.json lists it. Minimum length: 1.

Response model: commentary-books.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/books.json'

GET `/v1/{commentary}/{book}/{chapter}.json`#

One chapter of one commentary.

Every comment on one chapter, each published once and anchored at the lowest verse it covers. Verse 0 is the chapter introduction.

Parameter	Type	Required	Meaning
`commentary`	string	Yes	The commentary's id, as commentaries.json lists it. Minimum length: 1.
`book`	integer	Yes	GetBible book number: Genesis is 1, Matthew 40, Revelation 66, and the deuterocanonical books continue to 83. books.json lists the numbers the commentary has. Minimum: 1. Maximum: 83.
`chapter`	integer	Yes	Chapter number; 0 is the book introduction. books.json lists the chapters each book has. Minimum: 0.

Response model: commentary-chapter.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/43/1.json'

GET `/v1/{commentary}/{book}.json`#

Every chapter of one book.

The chapter documents of one book, each byte-for-byte the document served at its own path.

Parameter	Type	Required	Meaning
`commentary`	string	Yes	The commentary's id, as commentaries.json lists it. Minimum length: 1.
`book`	integer	Yes	GetBible book number: Genesis is 1, Matthew 40, Revelation 66, and the deuterocanonical books continue to 83. books.json lists the numbers the commentary has. Minimum: 1. Maximum: 83.

Response model: commentary-book.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke/43.json'

GET `/v1/{commentary}.json`#

The whole commentary.

Every book document of the commentary, each byte-for-byte the document served at its own path. A bulk document: metadata.json states its size.

Parameter	Type	Required	Meaning
`commentary`	string	Yes	The commentary's id, as commentaries.json lists it. Minimum length: 1.

Response model: commentary.

curl --fail --silent --show-error \
  'https://commentaries.getbible.net/v1/clarke.json'

Complete response field reference#

The tables preserve the generated OpenAPI field names, types, required fields, and constraints. Nested required fields are required when their containing object is present. Fields marked optional may be omitted. JSON Schemas in the linked specification provide the complete machine-readable contract.

commentary-catalog#

Every commentary in one v1 tree, with the path template of each of its documents relative to the tree root. The catalog and build.json are the only documents that carry the build time.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-commentaries-catalog-v1".
`version`	number	Yes	Constant: 1.
`generated_at`	string	Yes	Format: date-time.
`base_url`	string	Yes	Minimum length: 1.
`metadata_url_template`	string	Yes	Constant: "{commentary}/metadata.json".
`books_url_template`	string	Yes	Constant: "{commentary}/books.json".
`commentary_url_template`	string	Yes	Constant: "{commentary}.json".
`book_url_template`	string	Yes	Constant: "{commentary}/{book}.json".
`chapter_url_template`	string	Yes	Constant: "{commentary}/{book}/{chapter}.json".
`module_count`	integer	Yes	Minimum: 0.
`commentaries`	array	Yes
`commentaries[].id`	string	Yes	Minimum length: 1.
`commentaries[].name`	string	Yes	Minimum length: 1.
`commentaries[].language`	string	Yes	Minimum length: 2.
`commentaries[].license`	string	Yes
`commentaries[].book_count`	integer	Yes	Minimum: 0.
`commentaries[].chapter_count`	integer	Yes	Minimum: 0.
`commentaries[].entry_count`	integer	Yes	Minimum: 0.
`commentaries[].bytes`	integer	Yes	Minimum: 0.

commentary-metadata#

One commentary's provenance, licence, counts and sizes. bytes is the size of the whole-commentary document; storage is the build's own measurement of the module.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-commentary-metadata-v1".
`id`	string	Yes	Minimum length: 1.
`module`	string	Yes	The source module's own name. Minimum length: 1.
`name`	string	Yes	Minimum length: 1.
`language`	string	Yes	Minimum length: 2.
`version`	string	Yes
`license`	string	Yes
`driver`	string	Yes
`source_type`	string	Yes
`versification`	string	Yes	Minimum length: 1.
`book_count`	integer	Yes	Minimum: 0.
`chapter_count`	integer	Yes	Minimum: 0.
`entry_count`	integer	Yes	Minimum: 0.
`bytes`	integer	Yes	Minimum: 0.
`storage`	object	Yes	How much text the source repeated across verse ranges and what each level of the output costs on disk. No additional fields.
`storage.source_entry_count`	integer	Yes	Minimum: 0.
`storage.source_text_bytes`	integer	Yes	Minimum: 0.
`storage.text_bytes`	integer	Yes	Minimum: 0.
`storage.repetition_ratio`	number	Yes	Minimum: 0.
`storage.chapter_bytes`	integer	Yes	Minimum: 0.
`storage.book_bytes`	integer	Yes	Minimum: 0.
`storage.commentary_bytes`	integer	Yes	Minimum: 0.
`storage.published_bytes`	integer	Yes	Minimum: 0.
`books_url`	string	Yes	Constant: "books.json".
`book_url_template`	string	Yes	Constant: "{book}.json".
`chapter_url_template`	string	Yes	Constant: "{book}/{chapter}.json".
`source`	string	Yes	Constant: "CrossWire SWORD".
`source_module_url`	string	Yes	The module's own page at its source. Minimum length: 1.
`text_source`	string	Yes
`copyright`	string	Yes
`copyright_holder`	string	Yes
`copyright_contact`	object	Yes	No additional fields.
`copyright_contact.name`	string	Yes
`copyright_contact.email`	string	Yes
`copyright_contact.address`	string	Yes
`distribution_notes`	string	Yes
`about`	string	Yes
`conversion_note`	string	Yes	Minimum length: 1.
`references`	object	Yes	Which Bible the module's scripture references were resolved against: the API, the versification, the translations whose shape decided which chapters and verses exist, the translation whose book names ref uses, and the librarian and alias tables that resolved the spellings. No additional fields.
`references.api`	string	Yes	Constant: "getbible-v2".
`references.versification`	string	Yes
`references.translations`	array	Yes
`references.names`	string, null	Yes
`references.language`	string	Yes
`references.librarian`	array	Yes
`references.aliases`	array	Yes

commentary-books#

Which books and chapters one commentary covers. Chapter 0 is a book introduction.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-commentary-books-v1".
`commentary`	string	Yes	Minimum length: 1.
`language`	string	Yes	Minimum length: 2.
`name`	string	Yes	Minimum length: 1.
`book_url_template`	string	Yes	Constant: "{book}.json".
`chapter_url_template`	string	Yes	Constant: "{book}/{chapter}.json".
`book_count`	integer	Yes	Minimum: 0.
`books`	array	Yes
`books[].book`	integer	Yes	Minimum: 1. Maximum: 83.
`books[].name`	string	Yes	Minimum length: 1.
`books[].chapters`	array	Yes
`books[].entry_count`	integer	Yes	Minimum: 0.

commentary-chapter#

One chapter of one commentary. Chapter 0 carries the book introduction and verse 0 carries a chapter introduction.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-commentary-chapter-v1".
`commentary`	string	Yes	Minimum length: 1.
`language`	string	Yes	Minimum length: 2.
`book`	integer	Yes	Minimum: 1. Maximum: 83.
`name`	string	Yes	Minimum length: 1.
`chapter`	integer	Yes	Minimum: 0.
`entries`	array	Yes
`entries[]`	entry	—	See commentary-chapter/$defs/entry.

commentary-chapter: entry#

One comment. A source module attaches a comment to a verse range and repeats it for every verse in that range; it is published once here, anchored at the lowest verse it covers, with verses listing every verse it applies to when that is more than one.

Field	Type	Required	Meaning and constraints
`book`	integer	Yes	Minimum: 1. Maximum: 83.
`chapter`	integer	Yes	Minimum: 0.
`verse`	integer	Yes	The lowest verse this comment covers. Minimum: 0.
`verses`	array	No	Every verse this comment covers, including `verse`. Absent when it covers only `verse`. Minimum items: 2. Items are unique.
`osis`	string	No	The source module's own key for the anchor verse. Minimum length: 1.
`text`	string	Yes
`references`	references	No	See commentary-chapter/$defs/references.

commentary-chapter: references#

Field	Type	Required	Meaning and constraints
`text`	string	No	Minimum length: 1.
`ref`	string	Yes	Minimum length: 1.
`osis`	string	Yes	Minimum length: 1.
`book`	integer	Yes	Minimum: 1. Maximum: 83.
`chapter`	integer	Yes	Minimum: 0.
`verse`	integer	No	Minimum: 0.
`verses`	array	No	Every verse this reference covers, including verse. Absent when it covers only verse. Minimum items: 2. Items are unique.

commentary-book#

Every chapter of one book of one commentary. Each member of chapters is byte-for-byte the document served at {commentary}/{book}/{chapter}.json.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-commentary-book-v1".
`commentary`	string	Yes	Minimum length: 1.
`language`	string	Yes	Minimum length: 2.
`book`	integer	Yes	Minimum: 1. Maximum: 83.
`name`	string	Yes	Minimum length: 1.
`chapters`	array	Yes
`chapters[]`	commentary-chapter	—	See commentary-chapter.

commentary#

One complete commentary. Each member of books is byte-for-byte the document served at {commentary}/{book}.json. This is a bulk document; metadata.json publishes its size in bytes.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-commentary-v1".
`commentary`	string	Yes	Minimum length: 1.
`language`	string	Yes	Minimum length: 2.
`name`	string	Yes	Minimum length: 1.
`books`	array	Yes
`books[]`	commentary-book	—	See commentary-book.

build#

How and when one v1 tree was built: the builder and extractor, the catalog the modules were selected from and the Bible API the references were resolved against.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-build-v1".
`builder`	string	Yes	Constant: "v1_study_builder".
`builder_version`	string	Yes	Minimum length: 1.
`extractor`	string	Yes	Constant: "getbiblesword".
`extractor_version`	string	Yes	Minimum length: 1.
`extractor_contract`	string	Yes	Minimum length: 1.
`api_version`	number	Yes	Constant: 1.
`resource`	enum	Yes	Allowed values: "commentaries", "dictionaries".
`generated_at`	string	Yes	Format: date-time.
`catalog_url`	string	Yes	Minimum length: 1.
`bible_api`	string	Yes	Minimum length: 1.
`module_count`	integer	Yes	Minimum: 0.

build-report#

Compilation status and actionable diagnostics for one build. A published snapshot is captured before repository publication; the workflow report is updated with later publication errors. Successfully rebuilt modules and retained previous modules are listed separately.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-build-report-v1".
`status`	enum	Yes	Running is an in-progress checkpoint. Success means all approved modules built; partial means usable output exists with reported failures. Failed means the run could not complete safely. Publication failures are recorded in the workflow report. Allowed values: "running", "success", "partial", "failed".
`started_at`	string	Yes	Format: date-time.
`completed_at`	string, null	Yes	Format: date-time.
`requested_resource`	enum	Yes	Allowed values: "all", "commentaries", "dictionaries".
`catalog_url`	string	Yes	Minimum length: 1.
`built`	object	Yes	No additional fields.
`built.commentaries`	array	Yes
`built.dictionaries`	array	Yes
`skipped`	array	Yes
`skipped[]`	moduleIssue	—	See build-report/$defs/moduleIssue.
`failed`	array	Yes
`failed[]`	moduleFailure	—	See build-report/$defs/moduleFailure.
`retained`	array	Yes	Failed modules whose prior verified documents remain in the published tree.
`retained[]`	moduleIssue	—	See build-report/$defs/moduleIssue.
`errors`	array	Yes
`errors[].stage`	string	Yes	Minimum length: 1.
`errors[].error_type`	string	Yes	Minimum length: 1.
`errors[].reason`	string	Yes
`errors[].resource`	enum	No	Allowed values: "commentaries", "dictionaries".
`diagnostics`	object	Yes
`diagnostics.{key}`	array	—
`storage`	object	Yes
`storage.{key}`	object	—
`commits`	object	Yes
`commits.{key}`	string, null	—

build-report: moduleIssue#

Field	Type	Required	Meaning and constraints
`resource`	enum	Yes	Allowed values: "commentaries", "dictionaries".
`module`	string	Yes	Minimum length: 1.
`reason`	string	Yes

build-report: moduleFailure#

Field	Type	Required	Meaning and constraints
`resource`	enum	Yes	Allowed values: "commentaries", "dictionaries".
`module`	string	Yes	Minimum length: 1.
`reason`	string	Yes
`stage`	string	Yes	Minimum length: 1.
`error_type`	string	Yes	Minimum length: 1.

hashes#

The SHA-256 of every other document in one v1 tree, keyed by path relative to the tree root; also the complete list of the paths the tree contains.

Field	Type	Required	Meaning and constraints
`schema`	string	Yes	Constant: "getbible-hashes-v1".
`algorithm`	string	Yes	Constant: "sha256".
`files`	object	Yes
`files.{key}`	string	—	Pattern: ^[0-9a-f]{64}$.

Sources#

Complete contract reference#

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

Commentaries API v1

Quick start#

Addressing and coverage#

Read a verse correctly#

Three compatible response levels#

Scripture references#

Metadata, size, and offline use#

Build health and refreshes#

Errors and missing material#

Import into Postman or another OpenAPI client#

Complete endpoint reference#

GET /v1/commentaries.json#

GET /v1/build.json#

GET /v1/build-report.json#

GET /v1/hashes.json#

GET /v1/openapi.json#

GET /v1/schema/{document}.json#

GET /v1/{commentary}/metadata.json#

GET /v1/{commentary}/books.json#

GET /v1/{commentary}/{book}/{chapter}.json#

GET /v1/{commentary}/{book}.json#

GET /v1/{commentary}.json#

Complete response field reference#

commentary-catalog#

commentary-metadata#

commentary-books#

commentary-chapter#

commentary-chapter: entry#

commentary-chapter: references#

commentary-book#

commentary#

build#

build-report#

build-report: moduleIssue#

build-report: moduleFailure#

hashes#

Sources#

Complete contract reference#

GET `/v1/commentaries.json`#

GET `/v1/build.json`#

GET `/v1/build-report.json`#

GET `/v1/hashes.json`#

GET `/v1/openapi.json`#

GET `/v1/schema/{document}.json`#

GET `/v1/{commentary}/metadata.json`#

GET `/v1/{commentary}/books.json`#

GET `/v1/{commentary}/{book}/{chapter}.json`#

GET `/v1/{commentary}/{book}.json`#

GET `/v1/{commentary}.json`#