Quickstart

1. Get an API key

Request one from the API key request form. Requests are reviewed by hand, and you will get an email once yours is approved.

Keys are prefixed by environment: bql_live_ for production and bql_test_ for development. A key only works in the environment it was issued for.

2. Put it in your environment

Never paste a key into source control.

export BIBLEQL_API_KEY="bql_live_your_key_here"

3. Make a request

GraphQL

query {
  passage(translation: "eng-web", reference: "John 3:16") {
    reference
    text
    translationName
  }
}

cURL

curl https://bibleql.org/graphql \
  -H "Authorization: Bearer $BIBLEQL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { passage(translation: \"eng-web\", reference: \"John 3:16\") { reference text translationName } }"}'

Ruby

require "bibleql"

client = BibleQL::Client.new(
  api_key: ENV.fetch("BIBLEQL_API_KEY"),
  api_url: "https://bibleql.org/graphql"
)

passage = client.passage("John 3:16", translation: "eng-web")

puts passage.reference
puts passage.text

Node.js

import { BibleQLClient } from "bibleql-js";

const client = new BibleQLClient({
  apiKey: process.env.BIBLEQL_API_KEY!,
  apiUrl: "https://bibleql.org/graphql",
});

const passage = await client.passage("John 3:16", {
  translation: "eng-web",
});

console.log(passage.reference, passage.text);

Python

import os

import bibleql

client = bibleql.Client(
    api_key=os.environ["BIBLEQL_API_KEY"],
    api_url="https://bibleql.org/graphql",
)

passage = client.passage("John 3:16", translation="eng-web")

print(passage.reference)
print(passage.text)

Response

{
  "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"
    }
  }
}

You should get back:

{
  "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"
    }
  }
}

4. Understand what came back

GraphQL returns exactly the fields you asked for, wrapped in a top-level data object.

• reference is the parsed reference, normalized.
• text is every matched verse joined with newlines — handy for display.
• translationName is the human-readable translation name.

Had you asked for verses { verse text } instead of text, you would have received each verse separately. Nothing is returned unless you name it.

Errors arrive in a top-level errors array rather than as an HTTP error status — see Errors.

Next steps

• Explore interactively in the playground
• Learn the reference formats — ranges, whole chapters, multi-ranges
• Browse the available translations
• Install an SDK if you would rather not write GraphQL by hand

Endpoint

Every example on this site posts to https://bibleql.org/graphql. There is no GET variant.