Bible
=====

Retrieve verses and search across 30+ translations of the Bible.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-get-bible-verse
------------------------

Retrieve a Bible verse or verse range by human-readable reference. Accepts
standard references like ``John 3:16`` or ranges like ``Romans 8:28-30``.
Uses the King James Version by default.

**Credit cost:** 1 credit per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``reference``
     - str
     - yes
     - Bible reference in ``Book Chapter:Verse`` or ``Book Chapter:Verse-EndVerse``
       format (e.g. ``John 3:16``, ``Genesis 1:1-3``, ``1 Corinthians 13:4-7``).
   * - ``translation``
     - str
     - no
     - Translation identifier (e.g. ``kjv``, ``web``, ``lut1912``). Defaults to
       ``kjv`` (King James Version).

Example
^^^^^^^

Single verse -- request:

.. code-block:: json

   {
     "name": "apicrate-get-bible-verse",
     "arguments": {
       "reference": "John 3:16"
     }
   }

Returns the full text of John 3:16 in the KJV translation.

Verse range -- request:

.. code-block:: json

   {
     "name": "apicrate-get-bible-verse",
     "arguments": {
       "reference": "Genesis 1:1-3",
       "translation": "web"
     }
   }

Returns an array of verses (Genesis 1:1, 1:2, and 1:3) from the World English
Bible translation.

Errors
^^^^^^

- **Could not parse reference** -- the ``reference`` string does not match the
  expected ``Book Chapter:Verse`` format.
- **Book not found** -- the book name in the reference could not be matched to
  any known book.
- **Verse not found** -- the chapter or verse number does not exist in the
  specified book.


apicrate-search-bible
---------------------

Search the Bible for verses matching a query. Supports keywords, quoted
phrases, and wildcards (``lo*``). Returns up to 20 matching verses.

**Credit cost:** 3 credits per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``query``
     - str
     - yes
     - Search query -- keywords, a phrase in quotes, or a wildcard with ``*``.
   * - ``translation``
     - str
     - no
     - Translation identifier to search within (e.g. ``kjv``, ``web``). Omit
       to search across all available translations.
   * - ``book``
     - str
     - no
     - Limit search to a specific book (e.g. ``john``, ``genesis``,
       ``1 corinthians``). Accepts book names, abbreviations, or slugs.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-search-bible",
     "arguments": {
       "query": "love",
       "translation": "kjv"
     }
   }

Returns up to 20 verses from the KJV that contain the word "love".

Errors
^^^^^^

- **Unknown translation** -- the ``translation`` identifier does not match any
  available translation.
- **Book not found** -- the ``book`` value could not be matched to any known
  book.