Passages

Overview

A Passage object represents an arbitrary range of verses from the Bible. These ranges are not predefined values, but instead depend on the given input, known as a Passage ID. A Passsage ID consists of two Verse IDs separated by a -. These Verse IDs can span chapters and books, though passages are limited to 200 verses. A few passage examples are:

Passage Data Structure

Below is the data structure for the Passage object, which is returned by all /passage API endpoints

Copy
{
    "id": "string",
    "bibleId": "string",
    "orgId": "string",
    "content": "string",
    "reference": "string",
    "verseCount": 0,
    "copyright": "string"
  },

Fetching a Passage

GET https://rest.api.bible/v1/bibles/{bibleId}/passages/{passageId}

To fetch a passage in Bible, you must send a GET request to the above API endpoint using the appropriate Bible ID and Passage ID you would like to fetch. If you are having trouble building a specific Passage ID, try fetching a single verse first to ensure the verses you are looking for exist.

While a Passage ID can span both chapters and books, the API will only return the first 200 verses of the result. In this instance, the truncated result will be reflectd in the id field, which will show the verse range actually returned. This means that large passages may need to be broken up into smaller chunks to successfully fetch them in their entirety from the API. For example, if you attempted to fetch the passage GEN.1.1-EXO.1.1 (all of Genesis), the returned id would be GEN.1.1-GEN.8.16, representing the first 200 verses of the requested passage.

In addition to information about the given passage, this endpoint will also return all verse content included in that passage within the content field. Verse content will be configured based on the given input parameters, see our Verse Content guide for more.

Parameters

You can use the following query parameters to alter the results of your request:

Response

Below is the expected output structure from a successful API request:

Copy
{
  "data": {
    "id": "string",
    "bibleId": "string",
    "orgId": "string",
    "content": "string",
    "reference": "string",
    "verseCount": 0,
    "copyright": "string"
  }
}

Code Samples

To make a simple curl request, copy the following snippet and insert your API key and Passage ID:

Copy
curl --request GET \
--url https://rest.api.bible/v1/bibles/{bibleId}/passages/{passageId} \
--header 'api-key: YOUR_API_KEY'

For a JavaScript application, copy the following function and insert your API key and Passage ID:

Copy
const fetchPassage = async (bibleId, firstVerseId, lastVerseId) => {
  const url =
    "https://rest.api.bible/v1/bibles/${bibleId}/passages/${firstVerseId}-${lastVerseId}";
  try {
    const response = await fetch(url, {
      headers: {
        "api-key": "YOUR_API_KEY",
      },
    });
    if (!response.ok) {
      throw new Error(`Response status: ${response.status}`);
    }
    const result = await response.json();
    console.log(result);
    return result;
  } catch (error) {
    console.error(error.message);
  }
};

Note: To protect your API key, it is not recommended to use your API key in a client-side JS application (i.e. React)