Luis Porras

Posted on Apr 6

BibleQL: A GraphQL API for the Bible

#bible #opensource #graphql

Why I Built BibleQL

I've always wanted a simple, developer-friendly way to access Bible text programmatically. Most existing APIs are either proprietary, limited in translations, or use REST endpoints that make it hard to fetch exactly the data you need.

That's why I created BibleQL — a GraphQL API that lets you query Bible verses and passages across 43 public domain translations in 31 languages.

What Is BibleQL?

BibleQL is an open-source GraphQL API built with Ruby on Rails 8.1 and PostgreSQL. It provides a single flexible endpoint where you can query exactly the Bible data you need — no more, no less.

Here's what a query looks like:

{
  passage(translation: "eng-web", reference: "John 3:16") {
    reference
    text
    translationName
    verses {
      bookName
      chapter
      verse
      text
    }
  }
}

And you get back exactly what you asked for:

{
  "data": {
    "passage": {
      "reference": "John 3:16",
      "text": "For 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.",
      "translationName": "World English Bible",
      "verses": [
        {
          "bookName": "John",
          "chapter": 3,
          "verse": 16,
          "text": "For 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."
        }
      ]
    }
  }
}

Key Features

43 Bible translations in 31 languages (all public domain)
Flexible passage lookup — single verses, ranges, and multi-ranges (e.g., "Matthew 25:31-33,46")
Localized book names — query using book names in the translation's language (e.g., "Mateo 28:18-20" for Spanish, "Lucas 3:1-10")
Full-text search across all verses
Verse of the Day — a curated daily verse for any translation
Random verse — get a random verse filtered by testament or specific books
Bible index — browse the full structural hierarchy of any translation
Language discovery — list all available languages with their translations
Interactive Playground — try the API right in your browser at /playground

Supported Reference Formats

The passage query understands many reference formats:

Format	Example
Single verse	`"John 3:16"`
Verse range	`"John 3:16-18"`
Multiple ranges	`"Matthew 25:31-33,46"`
Full chapter	`"Genesis 1"`
Cross-chapter	`"Romans 12:1,3-4 & 13:2-4"`
Localized names	`"Mateo 28:18-20"`, `"Lucas 3:1-10"`

Client Libraries

To make it even easier to get started, I've built client SDKs:

Ruby: bibleql-ruby
Node.js: bibleql-js
Examples: bibleql-example

The Tech Stack

Ruby 4.0 / Rails 8.1 — the latest and greatest
PostgreSQL — reliable and performant
graphql-ruby — mature GraphQL implementation for Ruby
API Key authentication with environment-aware prefixes (bql_live_ / bql_test_)
Rate limiting via Rack::Attack (100 req/min per IP, 1,000 req/day per API key)
Docker + Kamal for deployment
GitHub Actions CI/CD — security scans, linting, and tests on every PR

Try It Out

The API is live at bibleql-rails.onrender.com. You can explore it interactively using the Playground.

To get an API key, visit the API Key Request page and submit a request.

Looking for Contributors!

This is where I need your help. BibleQL is fully open source and I'd love for this to be a community-driven project. Whether you're a seasoned Rails developer or just getting started with open source, there's room for you.

Here are some areas where contributions would be especially welcome:

More Bible versions — this is a big one! Currently all 43 translations are public domain, but I'd love to expand the API with widely-used copyrighted versions like NVI (Nueva Version Internacional), RVR1960 (Reina-Valera 1960), NIV, ESV, and others. If you have experience navigating Bible text licensing — working with publishers, understanding API usage rights, or securing distribution agreements — I'd really appreciate your guidance. This is uncharted territory for me and any help figuring out the licensing path would be invaluable.
New query types — ideas for useful queries the API doesn't support yet
Client libraries — SDKs for Python, Go, Java, or any other language
Documentation — improve guides, add tutorials, or write usage examples
Bug fixes and improvements — check the issues tab for open tasks
Frontend apps — build something cool on top of the API!

Check out the GitHub repository and the Contributing Guide to get started.

Get in Touch

If you have questions, ideas, or just want to chat about the project, feel free to:

Open an issue on GitHub
Star the repo if you find it useful

I believe technology can be a powerful tool for making Scripture more accessible to everyone. Let's build this together.

BibleQL is open source. Bible translations included via open-bibles are Public Domain or Creative Commons licensed.

DEV Community