# Bible API

> Read and search the Bible from API.Bible, the American Bible Society's official Bible API: 350+ public-domain and Creative Commons translations, plus up to three copyrighted ones on the free plan. Ask for a passage the way you would say it ('John 3:16', 'Psalm 23', 'Romans 8:28-39'), or pick a chapter or verse from a list, and get the text back as plain words, as numbered verses, or as the publisher's own HTML. Search a whole Bible for a word or phrase, see which translations, books, chapters and verses are available, and step through the text one chapter or verse at a time for a daily reading, a devotional email or a scripture lookup in chat.

App · Misc References · 8 actions. Web page: https://docs.lodol.com/docs/integrations/bible-api

## Actions

### List books

List the books in a translation, in its own order, each with how many chapters it has. Not every Bible carries every book; this is what a translation actually contains, so it is what a reading plan should be built on.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.

**Outputs**

- `bible_id` (text): The translation these books came from.
- `books` (list): The books this translation contains.
- `count` (number): How many books came back.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "books": [
    {
      "abbreviation": "JHN",
      "bible_id": "de4e12af7f28f599-01",
      "chapter_count": 21,
      "id": "JHN",
      "long_name": "The Gospel according to John",
      "name": "John"
    }
  ],
  "count": 1
}
```

### List chapters in a book

List a book's chapters, each with the reference it is cited by. Loop over these to read a book straight through, a chapter per run.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.
- Book (`book`, text, required): Which book, from the books in the chosen translation. You can also point this at a book from an earlier step.

**Outputs**

- `bible_id` (text): The translation they came from.
- `book_id` (text): The book these chapters came from, e.g. 'JHN'.
- `book_name` (text): That book's name, e.g. 'John'.
- `chapters` (list): The chapters in that book.
- `count` (number): How many chapters came back.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "book_id": "JHN",
  "book_name": "John",
  "chapters": [
    {
      "bible_id": "de4e12af7f28f599-01",
      "book_id": "JHN",
      "id": "JHN.3",
      "number": "3",
      "reference": "John 3"
    }
  ],
  "count": 1
}
```

### List translations

List every Bible translation your API.Bible key can read, with its name, language and the copyright line it requires. Filter by language, or by part of a name, to find the one to point the other steps at.

**Inputs**

- Language (`language`, text): Only translations in this language. The list holds every language your key has a Bible in.
- Name contains (`name`, text): Only translations whose name contains this. Leave it empty for all of them.

**Outputs**

- `count` (number): How many translations came back.
- `translations` (list): The translations this key can read.

**Example output**

```json
{
  "count": 1,
  "translations": [
    {
      "abbreviation": "engKJV",
      "copyright": "Public Domain",
      "description": "Protestant Bible",
      "id": "de4e12af7f28f599-01",
      "language": "English",
      "language_code": "eng",
      "language_local_name": "English",
      "local_name": "King James (Authorised) Version",
      "name": "King James (Authorised) Version",
      "script_direction": "LTR",
      "updated_at": "2024-06-11T10:22:35.000Z"
    }
  ]
}
```

### List verses in a chapter

List a chapter's verses, each with the reference it is cited by. Loop over these to work through a chapter a verse at a time: a verse-a-day post, or a study that treats each verse on its own.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.
- Chapter (`chapter`, text, required): Which chapter, from every chapter in the chosen translation. Start typing to find it ('psalm 23', 'john 3'). You can also point this at a chapter from an earlier step, such as one from 'List chapters in a book' or the next chapter of a passage you just read.

**Outputs**

- `bible_id` (text): The translation they came from.
- `chapter_id` (text): The chapter these verses came from.
- `count` (number): How many verses came back.
- `verses` (list): The verses in that chapter.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "chapter_id": "JHN.3",
  "count": 1,
  "verses": [
    {
      "bible_id": "de4e12af7f28f599-01",
      "book_id": "JHN",
      "chapter_id": "JHN.3",
      "id": "JHN.3.16",
      "reference": "John 3:16"
    }
  ]
}
```

### Read a chapter

Get a whole chapter, picked from a list of every chapter in the translation rather than typed. Also returns the chapter before and after it, so a workflow can walk through the Bible one chapter at a time, such as a reading plan that picks up where yesterday's run left off. No API.Bible ids to look up.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.
- Chapter (`chapter`, text, required): Which chapter, from every chapter in the chosen translation. Start typing to find it ('psalm 23', 'john 3'). You can also point this at a chapter from an earlier step, such as one from 'List chapters in a book' or the next chapter of a passage you just read.
- Format (`text_format`, text): How the scripture should come back. Plain text is the one to send in an email or a message; numbered verses is the one to read a chapter in; HTML carries the publisher's own styling for a web page. The result always includes a plain-text version as well, whichever you pick. One of: `plain` (Plain text (just the words)), `numbered` (Plain text with verse numbers and headings), `html` (HTML (the publisher's own styling)). Default: `plain`.

**Outputs**

- `bible_id` (text): The translation this came from.
- `book_id` (text): The book this came from, e.g. 'JHN'.
- `chapter_id` (text): The chapter this came from, e.g. 'JHN.3'.
- `content` (text): The scripture in the format that was chosen.
- `copyright` (text): The copyright line this translation requires.
- `format` (text): The format this was returned in.
- `id` (text): API.Bible's own id for what was returned.
- `next_id` (text): The chapter or verse after this one, for stepping through the Bible. Empty at the end of the Bible, and on a passage.
- `previous_id` (text): The chapter or verse before this one.
- `reference` (text): The passage as it is cited, e.g. 'John 3:16-18'.
- `text` (text): The scripture as plain text, whatever format was chosen.
- `verse_count` (number): How many verses came back.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "book_id": "PSA",
  "chapter_id": "PSA.23",
  "content": "The LORD is my shepherd; I shall not want.",
  "copyright": "Public Domain",
  "format": "plain",
  "id": "PSA.23",
  "next_id": "PSA.24",
  "previous_id": "PSA.22",
  "reference": "Psalms 23",
  "text": "The LORD is my shepherd; I shall not want.",
  "verse_count": 6
}
```

### Read a passage

Get the text of any passage, written the way you would say it: 'John 3:16', 'Psalm 23', 'Romans 8:28-39', '1 Cor 13:4-7'. Abbreviations work, a whole chapter or a run of chapters works too, and a range can cross from one book into the next. This is the action to reach for when you already know the reference; the other two let you pick instead. Comes back as plain text, as numbered verses, or as the publisher's HTML.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.
- Passage (`reference`, text, required): The passage to read, written normally: 'John 3:16', 'Psalm 23', 'Romans 8:28-39', '1 Cor 16:1-2 Cor 1:23'. Short forms ('Jn', 'Ps', '1 Cor', 'II Kings') and one-chapter books ('Jude 3' means verse 3) work the way you would expect. API.Bible's own ids work too, so you can point this at a reference from an earlier step.
- Format (`text_format`, text): How the scripture should come back. Plain text is the one to send in an email or a message; numbered verses is the one to read a chapter in; HTML carries the publisher's own styling for a web page. The result always includes a plain-text version as well, whichever you pick. One of: `plain` (Plain text (just the words)), `numbered` (Plain text with verse numbers and headings), `html` (HTML (the publisher's own styling)). Default: `plain`.

**Outputs**

- `bible_id` (text): The translation this came from.
- `book_id` (text): The book this came from, e.g. 'JHN'.
- `chapter_id` (text): The chapter this came from, e.g. 'JHN.3'.
- `content` (text): The scripture in the format that was chosen.
- `copyright` (text): The copyright line this translation requires.
- `format` (text): The format this was returned in.
- `id` (text): API.Bible's own id for what was returned.
- `next_id` (text): The chapter or verse after this one, for stepping through the Bible. Empty at the end of the Bible, and on a passage.
- `previous_id` (text): The chapter or verse before this one.
- `reference` (text): The passage as it is cited, e.g. 'John 3:16-18'.
- `text` (text): The scripture as plain text, whatever format was chosen.
- `verse_count` (number): How many verses came back.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "book_id": "JHN",
  "chapter_id": "JHN.3",
  "content": "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 God sent not his Son into the world to condemn the world; but that the world through him might be saved.",
  "copyright": "Public Domain",
  "format": "plain",
  "id": "JHN.3.16-JHN.3.17",
  "next_id": null,
  "previous_id": null,
  "reference": "John 3:16-17",
  "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 God sent not his Son into the world to condemn the world; but that the world through him might be saved.",
  "verse_count": 2
}
```

### Read a verse

Get one verse, picked from a list of the verses in a chapter rather than typed. Also returns the verse before and after it, so a workflow can walk the text a verse at a time or quote a verse with its neighbours for context. Point it at a verse from a search result to pull that verse's full text.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.
- Chapter (`chapter`, text, required): Which chapter, from every chapter in the chosen translation. Start typing to find it ('psalm 23', 'john 3'). You can also point this at a chapter from an earlier step, such as one from 'List chapters in a book' or the next chapter of a passage you just read.
- Verse (`verse`, text, required): Which verse, from the verses in the chosen chapter. You can also point this at a verse from an earlier step, such as a search result or the next verse of one you just read.
- Format (`text_format`, text): How the scripture should come back. Plain text is the one to send in an email or a message; numbered verses is the one to read a chapter in; HTML carries the publisher's own styling for a web page. The result always includes a plain-text version as well, whichever you pick. One of: `plain` (Plain text (just the words)), `numbered` (Plain text with verse numbers and headings), `html` (HTML (the publisher's own styling)). Default: `plain`.

**Outputs**

- `bible_id` (text): The translation this came from.
- `book_id` (text): The book this came from, e.g. 'JHN'.
- `chapter_id` (text): The chapter this came from, e.g. 'JHN.3'.
- `content` (text): The scripture in the format that was chosen.
- `copyright` (text): The copyright line this translation requires.
- `format` (text): The format this was returned in.
- `id` (text): API.Bible's own id for what was returned.
- `next_id` (text): The chapter or verse after this one, for stepping through the Bible. Empty at the end of the Bible, and on a passage.
- `previous_id` (text): The chapter or verse before this one.
- `reference` (text): The passage as it is cited, e.g. 'John 3:16-18'.
- `text` (text): The scripture as plain text, whatever format was chosen.
- `verse_count` (number): How many verses came back.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "book_id": "JHN",
  "chapter_id": "JHN.3",
  "content": "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.",
  "copyright": "Public Domain",
  "format": "plain",
  "id": "JHN.3.16",
  "next_id": "JHN.3.17",
  "previous_id": "JHN.3.15",
  "reference": "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.",
  "verse_count": 1
}
```

### Search the Bible

Find every verse in a translation that carries a word or phrase. All the words you give must appear in the verse, in any order, and '*' stands in for any run of letters ('wo*d' finds word, world and worshipped). Misspellings are allowed for. Narrow it to particular books, sort by best match or by Bible order, and page through more results. Each match comes back with its reference and its text.

**Inputs**

- Translation (`bible`, text, required): Which Bible to read. The list shows every translation your API.Bible key can access: the 350+ public-domain and Creative Commons Bibles everyone gets, plus any copyrighted ones on your plan. Add more from your API.Bible dashboard, then refresh this list.
- Words to find (`query`, text, required): The words to look for. Every word must appear in a verse for it to match, and their order does not matter. Use '*' for any run of letters and '?' for a single one. Typing a reference instead of words ('John 3:16') returns that passage rather than a list of matches.
- Only these books (`within`, list): Limit the search to particular books. Leave it empty to search the whole Bible.
- Order results by (`sort`, text): Best match puts the closest matches first; Bible order runs Genesis to Revelation, and reverse runs the other way. One of: `relevance` (Best match), `canonical` (Bible order), `reverse-canonical` (Bible order, last to first). Default: `relevance`.
- How many results (`limit`, number): How many matching verses to return at a time. From 1 to 100. Default: `10`.
- Skip this many (`offset`, number): How many matches to skip, for reading past the first page. Use the 'next_offset' from the previous run. From 0 to 100000. Default: `0`.

**Outputs**

- `bible_id` (text): The translation that was searched.
- `count` (number): How many verses came back this time.
- `has_more` (true/false): Whether there are more matches to read.
- `matched_a_reference` (true/false): True when the search text was read as a reference and a passage came back instead of matches.
- `next_offset` (number): The offset that reads the next page, or empty at the end.
- `offset` (number): How many matches were skipped.
- `passages` (list): Filled in instead of 'verses' when what was searched for was a reference rather than words.
- `query` (text): The words that were searched for.
- `total_count` (number): How many verses matched in all.
- `verses` (list): The verses that matched.

**Example output**

```json
{
  "bible_id": "de4e12af7f28f599-01",
  "count": 1,
  "has_more": true,
  "matched_a_reference": false,
  "next_offset": 1,
  "offset": 0,
  "passages": [],
  "query": "so loved the world",
  "total_count": 47,
  "verses": [
    {
      "bible_id": "de4e12af7f28f599-01",
      "book_id": "JHN",
      "chapter_id": "JHN.3",
      "id": "JHN.3.16",
      "reference": "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."
    }
  ]
}
```