Verse list plus another passage

Query v2 resolves Scripture references against the Bible v2 data tree. Send the translation and reference in the path; receive the selected verses grouped by translation, book and chapter.

Data route: GET https://query.getbible.net/v2/{translation}/{reference}

Live documentation · OpenAPI JSON · Query overview · Support

Quick start#

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

This returns a JSON object with kjv_43_3 as its chapter key and John 3:16 in that chapter's verses array. No authentication is necessary for a public request within the service's anonymous budget.

Parameters and reference syntax#

Input	Location	Meaning
API version	Path	v2; select it explicitly in production integrations
translation	Path	Translation abbreviation such as kjv, resolved case-insensitively
reference	Path	Required nonempty Scripture reference, up to 512 characters in the published contract

Query accepts no URL query parameters. It does not accept a JSON search body. The route is a GET operation; HEAD can retrieve its headers and OPTIONS handles preflight.

Reference	Selection
John3:16	One verse
John 3:16	The same verse with a space in the book/chapter form
Genesis 1:1-3	An inclusive verse range
John 3:16,18-21	One verse and a second range in the same chapter
Psalm 23	A whole chapter
Genesis 1:1-3;John 3:16	Multiple references separated by semicolons
1 John 3:16	A numbered book name

Book aliases depend on the resolver and selected translation. Use the published book catalogue for names and availability; an alias that parses still must refer to Scripture available in that translation. Chapter and verse numbering follows the source's versification.

# Verse list plus another passage
curl --fail-with-body --compressed \
  'https://query.getbible.net/v2/kjv/John%203:16,18-21;Romans%208:1-4'

# A complete short chapter
curl --fail-with-body --compressed \
  'https://query.getbible.net/v2/kjv/Psalm%2023'

Percent-encode spaces as %20, quote the whole URL in the shell and encode application input as one path segment. The standard managed query service is configured for at most 8 references and 200 total verses per request; oversized selections return 400 request_limit. The version's live documentation and error response remain authoritative if deployment settings change.

Response envelope#

The top-level object has one entry per selected chapter. Its key format is {translation}_{book}_{chapter}, for example kjv_43_3.

Chapter member	Type	Description
translation	String	Translation display name
abbreviation	String	Translation identifier
lang	String	Source language code
language	String	Source language label
direction	String	Source text direction
encoding	String	Source encoding label
book_nr	Integer	GetBible book number
book_name	String	Book display name
chapter	Integer	Chapter number
name	String	Chapter display name
ref	Array of strings	Input references contributing to this group
verses	Array of objects	Ordered selected verses

The six translation metadata fields are copied as available from the validated source; optional omissions and accepted empty values remain unchanged. name belongs to the chapter, while the translation name is translation. The full translation history, description, distribution terms and source details are available separately from the v2 catalogue.

Every returned verse has verse, name and text; source verses also carry chapter. Preserve whole verse objects when storing or forwarding results rather than rebuilding them from a fixed short field list.

v2 response example#

The complete response to the single-verse quick start is:

{
  "kjv_43_3": {
    "translation": "King James Version",
    "abbreviation": "kjv",
    "lang": "en",
    "language": "English",
    "direction": "LTR",
    "encoding": "UTF-8",
    "book_nr": 43,
    "book_name": "John",
    "chapter": 3,
    "name": "John 3",
    "ref": [
      "John3:16"
    ],
    "verses": [
      {
        "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."
      }
    ]
  }
}

For source lexical annotations and paragraph-start metadata, select Query v3. The v2 route continues to read v2 source data; it does not synthesize v3 metadata.

Canonical URLs and defaults#

Request	Behavior
/v2/kjv/John3:16	Returns the requested selection
/v2/John3:16	Valid short reference; 301 to /v2/kjv/John3:16
/John3:16	Uses the domain's configured default endpoint and translation
/aov/John3:16	Retains aov, uses the default endpoint and redirects if the reference resolves
/v2/kjv	404 missing_reference
/v2/unknowntranslation/John3:16	404 translation_not_found
Invalid or unavailable reference	404 problem document

Only an omitted translation gets the configured default, KJV on the public endpoint. A supplied unknown translation does not fall back to KJV. No absent or invalid reference is replaced with Matthew or another passage.

One unresolvable reference rejects an entire multiple-reference request. Handle a failed request as a failed selection; do not assume the API returned a partial list. Short forms are resolved before redirecting, so a plausible but unavailable reference does not trigger a redirect to substitute content.

# Follow the valid default-translation redirect
curl --fail-with-body --location --compressed \
  'https://query.getbible.net/v2/John3:16'

# Inspect the documented error for a missing reference
curl --include \
  'https://query.getbible.net/v2/kjv'

The documentation page is /v2/ with its trailing slash. Use its documented URL when linking to the human guide; a scripture route without the required reference is a different request.

Complete JavaScript example#

async function getScripture(reference, translation = 'kjv') {
  const url = `https://query.getbible.net/v2/${encodeURIComponent(translation)}/${encodeURIComponent(reference)}`;
  const response = await fetch(url, { headers: { Accept: 'application/json' } });
  const body = await response.json();
  if (!response.ok) {
    const error = new Error(body.detail ?? `GetBible returned HTTP ${response.status}`);
    error.status = response.status;
    error.code = body.code;
    throw error;
  }
  return body;
}

const chapters = await getScripture('Genesis 1:1-3;John 3:16');
for (const chapter of Object.values(chapters)) {
  for (const verse of chapter.verses) {
    console.log(verse.name, verse.text);
  }
}

This works in a modern browser console or an ES module with fetch. Render verse.text using text content in a user interface and apply the returned reading direction.

Access and bearer tokens#

The public endpoint advertises metered anonymous access. Valid tokens exempt their holders from public rate budgets. Tokens are domain-scoped; request one for query.getbible.net through support or [email protected].

Set the issued value as GETBIBLE_QUERY_TOKEN before running this authenticated example:

curl --fail-with-body --compressed \
  --header "Authorization: Bearer ${GETBIBLE_QUERY_TOKEN:?Set GETBIBLE_QUERY_TOKEN to your issued token}" \
  'https://query.getbible.net/v2/kjv/John3:16'

Never place tokens in URLs or publish them in browser bundles. Documentation, OpenAPI and public health/readiness routes remain accessible without tokens. A token does not bypass reference-count or verse-count validation.

Caching and freshness#

Read Cache-Control and save the returned ETag. On later requests for the identical URL, send If-None-Match; a 304 response has no body and means the stored representation can be reused. Actual cache lifetimes are deployment settings, so use response headers instead of a hardcoded number.

Namespace application caches by API version, translation, reference and the response contract the application expects. Source hashes and response-format versions solve different invalidation problems. Persistent v2 selections spanning several chapters must retain every participating chapter hash and recheck at least weekly according to the v2 Scripture cache policy.

The service allows cross-origin browser requests. Token-only deployments use private, no-store for data and bypass shared caches. An authorized request still must pass access checks before receiving a conditional response.

Error contract#

Errors use application/problem+json. The document has type, title, status, code, detail and instance; temporary responses may add retry_after and an HTTP Retry-After header. Use code for program behavior and detail for an explanatory message.

HTTP	Code	Meaning
400	parameters_not_accepted	Remove the URL query string
400	request_limit	Reduce the number of references or selected verses
401	unauthorized	Check credentials when token-only access applies
404	missing_reference	Supply a reference after the translation
404	invalid_reference	Reference cannot resolve
404	not_found	Requested Scripture or route is unavailable
404	translation_not_found	Translation is unknown/unavailable
404	unknown_version	Requested API version is not served by this endpoint
405	method_not_allowed	Use the documented HTTP method
429	rate_limited	Wait for Retry-After and reuse cached results
503	repository_unavailable, readiness_failed	Temporary inability to read Scripture

The OpenAPI contract also covers deployment/proxy failures such as 413, 500, 502 and 504. Handle non-success statuses even when the body comes from an intermediary. Retrying malformed or missing input will not repair it; fix 400/404 requests before trying again.

Health, OpenAPI and support#

GET /healthz reports liveness. GET /readyz verifies that the configured default Scripture can actually be read; a failure returns a 503 problem document with Retry-After. The readiness passage is a service probe, never a fallback for user references.

curl --fail-with-body 'https://query.getbible.net/healthz'
curl --fail-with-body 'https://query.getbible.net/readyz'
curl --fail-with-body --compressed \
  'https://query.getbible.net/v2/openapi.json' \
  --output getbible-query-v2-openapi.json

Import the OpenAPI URL or downloaded JSON in Postman. The contract includes the host and versioned paths. Use the canonical route to avoid an extra redirect during testing.

This guide follows the live v2 contract, service documentation, runtime policy, reference examples, and query limit configuration. Report problems at GetBible support, including the request URL, HTTP status and X-Request-ID header.

Complete contract reference#

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