api/query

Give the Query API a Scripture reference and it returns the selected verses. It accepts familiar names and abbreviations, verse lists, ranges and multiple references in one call. The response groups verses by translation, book and chapter so the same renderer can display a single verse or a selection spanning several books.

Choose your data version#

Version	Endpoint	Guide
v2	https://query.getbible.net/v2/{translation}/{reference}	Query v2
v3	https://query.getbible.net/v3/{translation}/{reference}	Query v3

Both versions use the same route and grouping contract. Version 3 preserves the selected source verses' optional paragraph, tokens and spans. Static chapter editorial is not part of assembled query results. If the application needs complete chapter headings or paragraph ranges, fetch the chapter from the Bible API.

Request one verse#

curl --fail-with-body --compressed \
  'https://query.getbible.net/v3/kjv/John3:16'

The top-level key is kjv_43_3: KJV, book 43, chapter 3. The chapter contains compact translation metadata, book_nr, book_name, chapter, name, ref and a verses array.

Request several passages#

curl --fail-with-body --compressed \
  'https://query.getbible.net/v3/kjv/Genesis%201:1-3;John%203:16,18-21;Romans%208:1-4'

Spaces are percent-encoded. Semicolons separate references; commas select verses within a chapter; a hyphen describes a range. Quote URLs in the shell so semicolons are not interpreted as command separators. Application code should encode the entire reference as one URL path segment.

const reference = 'Genesis 1:1-3;John 3:16';
const url = `https://query.getbible.net/v3/kjv/${encodeURIComponent(reference)}`;
const response = await fetch(url);
const payload = await response.json();
if (!response.ok) {
  throw new Error(payload.detail ?? `HTTP ${response.status}`);
}
for (const chapter of Object.values(payload)) {
  for (const verse of chapter.verses) {
    console.log(verse.name, verse.text);
  }
}

Explicit references and predictable errors#

A missing reference returns 404 missing_reference. An unresolvable reference returns a 404 problem document. If one reference in a multi-reference request cannot resolve, the entire request is rejected; the response is not silently reduced to the references that happened to work.

Omitting the translation on a valid short reference uses the configured default, KJV on the public service. For example, /v3/John3:16 redirects to /v3/kjv/John3:16. Explicitly supplying an unknown translation returns 404; it does not substitute KJV. No invalid input is replaced by a default passage.

Use an explicit version in production links. Unversioned aliases follow the domain's configured default endpoint, which can change independently of the application.

Query versus search#

Your input	API
A chapter or verse reference	Query
Several known references	Query
Words, a phrase or search filters	Search
A complete chapter with editorial layout	Bible
A whole translation for offline use	Bible

Query takes no query parameters and no JSON body. A URL such as ?reference=John3:16 is not the Query API contract. Put the translation and reference in the path.

Access, caching and support#

The public service is metered without a token. Application/partner tokens provide exemption from public rate budgets and must be used on their issuing domain. Request access by email or through the shared support desk.

Respect the actual Cache-Control response and retain ETag for conditional requests. Include the API version, translation and reference in cache keys. If a v2 query result combines chapters, persistent caching needs the hashes of every participating chapter, as described in the v2 cache contract.

Contracts and upstream documentation#

Resource	Link
Service overview	query.getbible.net
Version discovery	versions.json
v2 service docs and OpenAPI	Documentation · OpenAPI JSON
v3 service docs and OpenAPI	Documentation · OpenAPI JSON
Runtime response and routing policy	Runtime endpoints
Reference grammar and grouping	Librarian usage
Compact metadata contract	Translation metadata

Quote the API's X-Request-ID when asking support about a failed request.