Bolls API Documentation

This documentation is called to provide available API for creating a functioning client.

Before fetching Bible text
Fetch a chapter
Search
Get a translation
Compare versions
Fetch a verse
Fetch any verses
Random verse
ReferenceReference Tagging Tool
Dictionary definition for Hebrew and Greek words
Notes
Contact me

Before fetching Bible text

Updated at: 17 February 2021.

First of all get a list of available translations and an object with their books. The translations list contain nodes with following properties:

The short_name field is an id of the translation in database. Use it for forming a url.
The full_name field is a full name of its translation.
The updated field is a date (milliseconds since 1970) when the translation was updated the last time.
The optional dir field may specify rtl direction translations.

API fot getting books of a specific translation:

https://bolls.life/get-books/<slug:translation>/

Where translation is an abbreviation of desired translation. Example:

https://bolls.life/get-books/YLT/

The books list contains books with the next properties:

The bookid field is the id of the book.
The chronorder field is the chronological order book number according to Robert Young. (for apocrypha it's the same as bookid)
The name field is the book name.
The chapters field is the number of chapters.

Fetch a chapter

Using that data, you can form a url to fetch a chapter. You may fetch the chapter with commentaries or without them. The url constructor:

https://bolls.life/get-text/<slug:translation>/<int:book>/<int:chapter>/ # Without commentaries

https://bolls.life/get-chapter/<slug:translation>/<int:book>/<int:chapter>/ # With commentaries

Where <slug:translation> is a translation abbreviation like YLT or UBIO or SYNOD, and <int:book> with <int:chapter> are numbers of a book and chapter. For example by the next url you will get the eight chapter of Song of Solomon in YLT or NKJV translation:

https://bolls.life/get-text/YLT/22/8/

https://bolls.life/get-chapter/NKJV/22/8/

Curl code

curl --location --request GET 'https://bolls.life/get-text/YLT/22/8/'

curl --location --request GET 'https://bolls.life/get-chapter/NKJV/22/8/'

The result of this request will be a list of verses of that chapter, with the next fields:

The pk field is an id of the verse.
The verse field is a number of the verse in the chapter.
The text field contains the text of the verse in HTML format
The optional comment field contains comments or references in HTML format.

Search

Updated at: 13 March 2025

To find verses by a slug or a string you need to form a url in the next manner:

https://bolls.life/v2/find/<slug:translation>?search=<str:piece>&match_case=<bool:match_case>&match_whole=<bool:match_whole>&page=<int:page>

Where <slug:translation> is an abbreviation of the translation in which you want to find something. The <str:piece> is a piece of text which can be a slug or a string which you look for. It is`not case sensitive, and it can be anything on any language: .../WLC?search=שָּׁמַ֖יִם וְאֵ֥ת, .../LXX?search=ὁ θεὸς τὸν, .../UBIO?search=Небо та землю, .../CUV?search=淵面黑暗.

Optional boolean parameters:

match_case (case sensitive search) and
match_whole (precise search, match whole search string) and
book (filter search results by book. Use «ot» and «nt» to filter by Old Testment and New Testament).
page pagination page
limit pagination page limit

For example the next url will returm a list of verses, where "Haggi" word is found:

https://bolls.life/v2/find/YLT?search=haggi&match_case=false&match_whole=true&limit=128&page=1

The result of this request will be an object containing the next fields:

The exact_matches contains total number of exact matches
THe total field is the number of total results
The results field is an array of the next objexts

The pk field is an id of the verse.
The translation field is the translation of search.
The book field is the book of the verse.
The chapter field is the chapter of the book in which the verse is found.
The verse field is the number of the verse in its chapter.
The text field contains html text of the verse.
The optional comment field contains HTML commentary if such exist.

Curl code

curl --location --request GET 'https://bolls.life/v2/find/YLT?search=haggi&match_case=false&match_whole=true'

Get a translation

You can get a full translation in zip or json:

https://bolls.life/static/translations/<slug:translation>.zip

https://bolls.life/static/translations/<slug:translation>.json

The result will be an array of all translation verses with comments. For example you can try the next link:

https://bolls.life/static/translations/YLT.json

The structure of nodes in this array will be like in the nodes of search query

Curl code

curl --location --request GET 'https://bolls.life/static/translations/YLT.json'

Compare versions

You can make a request for peculiar verses in peculiar translations. If you wanna see some exact verse or verses in different translation to compare them you can use this api. The request should be POST, and you should pass in the body an object with some fields. The request url -=> https://bolls.life/get-parallel-verses/, The body of the POST request must have the nest fields:

The translations field should be an array of abbreviations of translations like: ["YLT", "HOM", "WLCC"].
The verses field should be an array of numbers of verses to compare like: [1, 2, 3, 6, 45] (order does mean).
The chapter field should be a chapter of the book.
The book field should be a book of the verses.

You may request different verses in different translations only of one chapter. Imba example.

window.fetch("/get-parallel-verses/", {
	method: "POST",
	cache: "no-cache",
	headers: {
		"Content-Type": "application/json"
	},
	body: JSON.stringify({
		// Here are list of translations for comparison
		translations: ['YLT', 'WEB', 'KJV'],

		// It may be a single verse there [3], or any number of verses,
		// and if they exist they will be returned
		verses: [3, 4, 5],

		book: 43, // an id of the book
		chapter: 1, // number of chapter
	}),
})
.then((response) => response.json())
.then((result) => {
	// do something with the result
})

The result will be an array of translations with every translation being an array of requested verses, where every verse has these fields. Here is the example of the result:

[
  [
    {
      "pk": 1145257,
      "translation": "WLCC",
      "book": 18,
      "chapter": 2,
      "verse": 1,
      "text": "ויהי היום ויבאו בני האלהים להתיצב על־יהוה ויבוא גם־השטן בתכם להתיצב על־יהוה׃"
    },
    {
      "pk": 1145258,
      "translation": "WLCC",
      "book": 18,
      "chapter": 2,
      "verse": 2,
      "text": "ויאמר יהוה אל־השטן אי מזה תבא ויען השטן את־יהוה ויאמר משט בארץ ומהתהלך בה׃"
    },
    {
      "pk": 1145259,
      "translation": "WLCC",
      "book": 18,
      "chapter": 2,
      "verse": 3,
      "text": "ויאמר יהוה אל־השטן השמת לבך אל־עבדי איוב כי אין כמהו בארץ איש תם וישר ירא אלהים וסר מרע ועדנו מחזיק בתמתו ותסיתני בו לבלעו חנם׃"
    }
  ],
  [
    {
      "pk": 36107,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 1,
      "text": "And the day is, that sons of God come in to station themselves by Jehovah, and there doth come also the Adversary in their midst to station himself by Jehovah."
    },
    {
      "pk": 36108,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 2,
      "text": "And Jehovah saith unto the Adversary, 'Whence camest thou?' And the Adversary answereth Jehovah and saith, 'From going to and fro in the land, and from walking up and down in it.'"
    },
    {
      "pk": 36109,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 3,
      "text": "And Jehovah saith unto the Adversary, 'Hast thou set thy heart unto My servant Job because there is none like him in the land, a man perfect and upright, fearing God and turning aside from evil? and still he is keeping hold on his integrity, and thou dost move Me against him to swallow him up for nought!'"
    }
  ]
]

Fetch a verse

To fetch a single verse construct a link like this:

https://bolls.life/get-text/<slug:translation>/<int:book>/<int:chapter>/<int:verse>/

Where <slug:translation> is the translation abbreviation like YLT or UBIO or SYNOD, and <int:book> with <int:chapter> and <int:verse> are numbers of a book, chapter and verse. For example by the next url you will get first verse of the first chapter of Genesis in NKJV translation:

https://bolls.life/get-verse/NKJV/1/1/1/

Fetch any verses

New since 28 June 2022.

Sometimes one my need to fetch a few verses from different places of all of the Bible. This API allow to do that. In the body you should provide and array of Bible places you wanna fetch:

The translation field must contain translation code
The book field must contain book code
The chapter field must contain chapter number
The verses field must contain array of verses numbers

Here is an example:

window.fetch('/get-verses/', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify([
		{
			translation: 'YLT',
			book: 19,
			chapter: 145,
			verses: [14, 15, 16]
		},
		{
			translation: 'KJV',
			book: 19,
			chapter: 91,
			verses: [1, 2, 3]
		}
	])
}).then((response) => response.json())
.then((data) => console.log(data))
.catch(console.error)

Result example:

[
	[
		{
			"pk": 23228,
			"translation": "YLT",
			"book": 1,
			"chapter": 1,
			"verse": 14,
			"text": "And God saith, 'Let luminaries be in the expanse of the heavens, to make a separation between the day and the night, then they have been for signs, and for seasons, and for days and years,"
		},
		{
			"pk": 23229,
			"translation": "YLT",
			"book": 1,
			"chapter": 1,
			"verse": 15,
			"text": "and they have been for luminaries in the expanse of the heavens to give light upon the earth:' and it is so."
		},
		{
			"pk": 23230,
			"translation": "YLT",
			"book": 1,
			"chapter": 1,
			"verse": 16,
			"text": "And God maketh the two great luminaries, the great luminary for the rule of the day, and the small luminary -- and the stars -- for the rule of the night;"
		}
	],
	[
		{
			"pk": 2743734,
			"translation": "KJV",
			"book": 19,
			"chapter": 91,
			"verse": 1,
			"text": "He that dwelleth in the secret place of the most High shall abide under the shadow of the Almighty."
		},
		{
			"pk": 2743735,
			"translation": "KJV",
			"book": 19,
			"chapter": 91,
			"verse": 2,
			"text": "I will say of the LORD, He is my refuge and my fortress: my God; in him will I trust."
		},
		{
			"pk": 2743736,
			"translation": "KJV",
			"book": 19,
			"chapter": 91,
			"verse": 3,
			"text": "Surely he shall deliver thee from the snare of the fowler, and from the noisome pestilence."
		}
	]
]

Dictionary definition for Hebrew and Greek words

New since 23 December 2021.

This API lets you get a list of definitions for a Hebrew or Greek word, if such do exist in a dictionary. If there are no definitions for requested query -- an empty array is returned. The API looks in the next way:

https://bolls.life/dictionary-definition/<slug:dict>/<str:query>/

Where: dict is an abbreviation of dictionary that should be used. At this moment there are available only two dictionaries: BDBT - Brown-Driver-Briggs' Hebrew Definitions / Thayer's Greek Definitions and RUSD - Полный лексикон по Стронгу и Дворецкому, 2019 (https://bolls.life/static/bolls/app/views/dictionaries.json). query is a string -- anything in Greek or Hebrew. You may also search for English/russian words and it will return some relative Hebrew/Greek words and their definitions. query also may be a strong number like H125 or G523 - it will return a particular definition under that Strong number. In result you will get a JSON array - empty or with definitions XD. For example the next request will return an array of definitions for the Hebrew word אֹ֑ור (light):

https://bolls.life/dictionary-definition/BDBT/אֹ֑ור

Every definition contains next fields:

topic - a Strong number.
definition - an HTML string with the definition text.
lexeme - the found word itself.
transliteration - transliteration of the found word.
pronunciation - pronunciation of the found word
short_definition - short definition of the word, by which, between, the word can be found with English/Russian query
weight - a number indicating how close is the matched word to the query on the scale from 0 to 1

Also there is an optional flag extended which when equals to true will return results of extended search. For example try this query:

https://bolls.life/dictionary-definition/BDBT/אֹ֑ור/?extended=true

If you wish to download a whole dictionary in JSON format, you can use the next links:

https://bolls.life/static/dictionaries/<slug:dictionary>.[json|zip]

Examples:

https://bolls.life/static/dictionaries/BDBT.json

https://bolls.life/static/dictionaries/BDBT.zip

Random verse

New since 4 Feb 2024.

The url constructor:

https://bolls.life/get-random-verse/<slug:translation>/

<slug:translation> is a translation abbreviation like YLT or UBIO or SYNOD. For example by the next url you will get a random verse from the Bible in YLT translation:

https://bolls.life/get-random-verse/YLT/

Result:

{
  "pk": 31073,
  "translation": "YLT",
  "book": 9,
  "chapter": 24,
  "verse": 19,
  "text": "and that a man doth find his enemy, and hath sent him away in a good manner; and Jehovah doth repay thee good for that which thou didst to me this day."
}

Where:

The pk field is an id of the verse.
The translation field is a translation of the verse.
The book field is a book of the verse.
The chapter field is a chapter of the book in which the verse is found.
The verse field is a number of the verse in its chapter.
The text field contains html text of the verse.

Reference Tagging Tool

New since 28 March 2025.

GitHub issue

This API allows you to automatically tag references in your text. All you need to do is to include js script + css, then call the function like this:

<head>
  <script type="text/javascript" src="https://bolls.life/reference-tool/tool.js"></script>
  <link rel="stylesheet" type="text/css" href="https://bolls.life/reference-tool/popover.css" />
</head>
<body>
  <div id="text">
    <p>Some text with references to the Bible: John 3:16</p>
    <p>Another text with references to the Bible: Genesis 1:1</p>
  </div>
  <script type="text/javascript">
    ReferenceTagging.init()
    // set defaults. Full list of public options look at the source code.
    ReferenceTagging.translation = "KJV"
    ReferenceTagging.theme = 'dark' // or 'light' which is default
    ReferenceTagging.linkVerses()
  </script>
</body>

You may find an example here.

Reverse engineered from Bible Gateway tool 🥰.

Notes

Every verse text should be interpreted as an html string. There may appear some tags like </br> or <i></i>. Either display the text as HTML or clean up the text.

Table of contents

Before fetching Bible text

Fetch a chapter

Search

Get a translation

Compare versions

Fetch a verse

Fetch any verses

Dictionary definition for Hebrew and Greek words

Random verse

Reference Tagging Tool

Notes