# bible_api: a JSON endpoint for public domain Bible translations

> bible_api is a Ruby web application that serves Bible text as JSON for public domain and open translations, hosted publicly at bible-api.com. The response carries the translation name and its licence note alongside the verses, and the repository includes everything needed to run your own copy on MySQL and Redis.

**seven1m/bible_api** — Ruby web app that serves JSON API for open and public domain bibles

- Repository: https://github.com/seven1m/bible_api
- Website: https://bible-api.com
- Stars: 844 · Forks: 149
- Language: Ruby
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/seven1m-bible-api

## A JSON API over open translations

bible_api is a Ruby web app that serves a JSON API for public domain and open Bible translations, and the project description says the same thing in one line, with the emphasis on the JSON and on the translations being open.

The hosted instance is the product for most people. The README says the app is served from bible-api.com, which anyone can use, so the common case needs no installation at all.

What the API is not is a scraper of a website. The translations are imported into a database by a script in the repository, and the request path is a lookup, so the interesting part of the project is the data pipeline rather than the endpoint.

The repository layout supports that reading. There is a bibles/ directory that holds the translation content, an import.rb that loads it, a lib/ directory for the application code, an app.rb for the Rack entry point, config.ru as the Rack configuration, config/ for settings, views/ for the templates, and spec/ with a .rspec file for the tests.

The project is Ruby, MIT licensed, with the copyright held by Tim Morgan, the default branch on master, and the last push on 2026-08-29. There are no GitHub releases, so the code is the artefact rather than a versioned package, and the hosted service is the stable surface that people actually depend on.

## The response carries its own licence note

The example response in the README is the best description of the API, and it is a single reference:

```json
{
  "reference": "John 3:16",
  "verses": [
    {
      "book_id": "JHN",
      "book_name": "John",
      "chapter": 3,
      "verse": 16,
      "text": "\nFor God so loved the world, that he gave his one and only Son, that whoever believes in him should not perish, but have eternal life.\n\n"
    }
  ],
  "text": "\nFor God so loved the world, that he gave his one and only Son, that whoever believes in him should not perish, but have eternal life.\n\n",
  "translation_id": "web",
  "translation_name": "World English Bible",
  "translation_note": "Public Domain"
}
```

Three things are worth pulling out of that.

The first is that the response is per reference, not per book, and the URL is the reference. A caller asks for a passage, not a chapter listing or a whole book, which keeps the payload small and the semantics obvious.

The second is the verse list. Each verse carries a book_id, which is a short code such as JHN, alongside the book name, the chapter and the verse number. The identifier is the one worth keeping, because a UI that displays scripture across translations needs a stable key that does not change with the wording of a book name.

The third, and the one that makes this API unusual, is translation_note. The response states the translation name and its licence status, here Public Domain, in the payload itself. Any application that renders scripture in a product needs to know whether the text it is showing can be used and under what terms, and shipping that fact alongside the text means the caller does not have to hardcode a table of translation licences or trust a documentation page that can change.

## Two ways to call it, from a shell and from Ruby

The README gives one example per language, and both are short enough to copy.

From a shell, with curl and jq:

```sh
→ curl -s https://bible-api.com/John+3:16 | jq
```

The reference in the path is url-encoded with a plus for the space, which is the only detail a first-time caller has to notice. The pipe to jq is there to show that the endpoint returns JSON and nothing else, so the response composes with the ordinary Unix tools.

From Ruby, which is the language the app is written in, the example uses the standard library only:

```sh
→ ruby -r open-uri -r json -r pp -e "pp JSON.parse(URI.open('https://bible-api.com/John+3:16').read)"
```

open-uri to fetch, json to parse and pp to print the result. The output in the README is the same JSON, rendered in Ruby's own inspect format, which is a nice illustration of the point that the endpoint is just HTTP returning a document.

There is no client library in the repository, and no key, no registration and no rate limit mentioned anywhere in the README. For a service whose payload is a few hundred bytes of public domain text, that is a reasonable design, and it is also why the response includes the licence note: a caller can rely on the endpoint without an account, and can still tell what it is allowed to do with what it gets back.

## Hosting it yourself: Ruby, Redis and MySQL

The Hosting it Yourself section is the operational part of the README, and it starts by telling you what the machine needs: a Linux server with Ruby, Redis, and MySQL or MariaDB installed.

The first step is the clone, and it includes the submodule update, which is not optional:

```sh
git clone https://github.com/seven1m/bible_api
cd bible_api
git submodule update --init
```

The content of the translations arrives as submodules, so a checkout without that step has the application and no text in it, which is exactly the kind of failure that takes a while to diagnose.

The second step is the gems:

```sh
gem install bundler
bundle config --local deployment true # optional, but preferred on a server
bundle install
```

The third step is the database and the import, and it is the longest command in the documentation because it does three things at once:

```sh
mysql -uroot -e "create database bible_api; grant all on bible_api.* to user@localhost identified by 'password';"
export DATABASE_URL="mysql2://user:password@localhost/bible_api"
export REDIS_URL="redis://localhost:6379"
bundle exec ruby import.rb
```

The database is created and a user granted rights on it, the two connection strings are exported as environment variables, and then import.rb loads the translations into the database. Redis is configured the same way, by URL, which is what tells you it is used for caching rather than for storage.

The fourth step is serving the app with Passenger, or, if you are just testing, running bundle exec ruby app.rb.

## The deployment surface is a collection of small files

Beyond the application code, the repository carries a set of deployment artefacts that tell you how this kind of Ruby app is expected to be run.

There is a Procfile, which is the PaaS convention for declaring the process types an application exposes, and an app.json, which is the Heroku style application descriptor, and a DOKKU.md, which is the deployment guide for Dokku. Three different platforms, three different conventions, all in the same repository, and the Passenger instruction in the README is the fourth option for a plain server.

There is a config.ru for Rack, an app.rb for the application entry point, a Rakefile for tasks, a .ruby-version pinning the interpreter, and a .rspec for the test runner settings. The .streerc file configures the Stripe test mode helper, which is the convention for a file that keeps a test-mode API secret out of a repository while still allowing the test suite to run.

There is also a .gitmodules file, and the import step in the hosting instructions depends on it, which is the one detail of the setup that people tend to leave out.

Taken together, the repository is a small Sinatra or Rack style application with a data import step in front of it, and the deployment files are the price of making it runnable on whatever platform the person deploying it already has. That is a sensible trade for a project whose main output is a text API, and it is why the README can describe hosting the thing in four steps.

## What to check before you depend on it

Three practical points.

First, the translations and their terms. The API deliberately exposes translation_name and translation_note, and the note in the example is Public Domain, so the API makes the licensing question answerable per translation. Any project that renders scripture has to check that field for the translations it uses, because the set is a mixture of public domain and open translations, and a blanket assumption that all of them are the same is not safe.

Second, the stability of the hosted endpoint. The project publishes no GitHub releases, the last push was on 2026-08-29, and the public service at bible-api.com is the artefact most people consume. If your application depends on it, treat the endpoint as a dependency with a fallback, or run your own instance, which the README supports with the full recipe.

Third, the data pipeline. Because the translations come in as git submodules and are loaded by import.rb, the import step is the part that determines what your instance actually serves. If you fork the project, the upstream content is a separate repository, and updating the text means updating the submodule and re-running the import, not just pulling the application code.

For the scope of the project, it is worth being clear that this is a text service and nothing more. There is no search, no commentary, no cross-references and no metadata beyond what a verse needs, and the reference is the unit of retrieval. For a reading app, a chat interface or a dataset, that is enough to start, and for anything larger it is a starting point rather than a finished platform.

## Conclusion

Adopt the public instance if you need Bible text in JSON for a demo, a script or a small application, because the endpoint is free to use and the response includes the translation name and its licence note, which is the detail that keeps a public domain text usable in a product. Host your own copy if you need a stable contract, since the project publishes no releases and the hosted service could change, and the README covers the whole path from clone to Passenger with a MySQL database and a Redis instance. Before you rely on it, read the translation_note field for every translation you use, and remember that the upstream content arrives as git submodules, so a checkout without the submodules has no text in it.

## FAQ

### What does the bible_api endpoint return?

A JSON object for a single reference, with the reference, an array of verses each carrying a book_id, book_name, chapter, verse and text, a combined text field, and the translation details: translation_id, translation_name and translation_note, which states the licence of the translation such as Public Domain.

### How do I call bible-api.com?

With the reference in the path, for example curl -s https://bible-api.com/John+3:16 piped to jq. From Ruby the README shows a one-liner using open-uri, json and pp to fetch and pretty print the same response. No key or account is needed.

### What does it take to host bible_api myself?

A Linux server with Ruby, Redis and MySQL or MariaDB. Clone the repository and run git submodule update --init for the translation content, install the gems with bundler, create the database, export DATABASE_URL and REDIS_URL, run bundle exec ruby import.rb to load the translations, and then serve the app with Passenger or with bundle exec ruby app.rb.

### Is bible_api released as a versioned package?

No. The repository publishes no GitHub releases, and the last push was on 2026-08-29. The hosted service at bible-api.com is the artefact most consumers use, and the project is MIT licensed with the copyright held by Tim Morgan.

## Sources

- [Issues](https://github.com/seven1m/bible_api/issues)
- [License: MIT](https://github.com/seven1m/bible_api/blob/master/LICENSE)
- [Project website](https://bible-api.com)
- [README](https://github.com/seven1m/bible_api/blob/master/README.md)
- [seven1m/bible_api on GitHub](https://github.com/seven1m/bible_api)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/seven1m-bible-api