ScriptureFlow Developer Quickstart

Purpose

This quickstart helps developers make their first successful ScriptureFlow API request.

ScriptureFlow is a public Scripture access API designed to help developers build Bible-powered applications, automations, study tools, ministry resources, multilingual Scripture tools, and other software experiences that need structured Scripture data.

This guide focuses only on how to use the public API. It does not explain the private repository, internal build process, corpus processing, deployment pipeline, or contributor-only implementation details.

Base API URL

Use this base URL for public API requests:


https://scriptureflow-api-preview.pages.dev

All examples in this quickstart use the public preview API domain.

Your First Request

To retrieve John 3:16 from the King James Version, open this URL in your browser:


https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=John&chapter=3&verse=16

The request uses four required query parameters:

Parameter	Example	Meaning
`version`	`en-kjv`	The exact translation/version key.
`book`	`John`	The book name or supported book reference.
`chapter`	`3`	The chapter number.
`verse`	`16`	The verse number.

A successful request returns a JSON response containing the requested Scripture data.

Important: Use Exact Version Keys

The version value is not just a display name. It is an exact lookup key.

For the King James Version, use:


en-kjv

Do not use:

kjv

Do not use:


en-KJV

Version keys are case-sensitive and catalog-controlled. If a version key is wrong, the API may not find the requested translation.

To see available translations and version keys, use:


https://scriptureflow-api-preview.pages.dev/translations.json

Lookup a Single Verse

Use /api/verse with version, book, chapter, and verse.


https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=John&chapter=3&verse=16

Browser

Paste the full URL into a browser address bar.

JavaScript


const baseUrl = "https://scriptureflow-api-preview.pages.dev";

const url = `${baseUrl}/api/verse?version=en-kjv&book=John&chapter=3&verse=16`;

const response = await fetch(url);
const data = await response.json();

console.log(data);

Python


import requests

base_url = "https://scriptureflow-api-preview.pages.dev"

url = f"{base_url}/api/verse?version=en-kjv&book=John&chapter=3&verse=16"

response = requests.get(url, timeout=20)
data = response.json()

print(data)

cURL


curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=John&chapter=3&verse=16"

Lookup a Same-Chapter Passage

To request a passage range within the same chapter, add end_verse.

Example: Amos 8:4-6


https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Amos&chapter=8&verse=4&end_verse=6

This requests:


Amos 8:4-6

Use this pattern when the passage starts and ends in the same chapter.

JavaScript


const baseUrl = "https://scriptureflow-api-preview.pages.dev";

const url = `${baseUrl}/api/verse?version=en-kjv&book=Amos&chapter=8&verse=4&end_verse=6`;

const response = await fetch(url);
const data = await response.json();

console.log(data);

Python


import requests

base_url = "https://scriptureflow-api-preview.pages.dev"

url = f"{base_url}/api/verse?version=en-kjv&book=Amos&chapter=8&verse=4&end_verse=6"

response = requests.get(url, timeout=20)
data = response.json()

print(data)

cURL


curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Amos&chapter=8&verse=4&end_verse=6"

Lookup by Free-Text Reference

You can also request a verse using a reference value.

Example:


https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=John%203%3A16

The reference value must be URL encoded when used inside a URL.

Readable reference:


John 3:16

URL-encoded reference:


John%203%3A16

JavaScript


const baseUrl = "https://scriptureflow-api-preview.pages.dev";

const reference = encodeURIComponent("John 3:16");
const url = `${baseUrl}/api/verse?version=en-kjv&reference=${reference}`;

const response = await fetch(url);
const data = await response.json();

console.log(data);

Python


import requests

base_url = "https://scriptureflow-api-preview.pages.dev"

params = {
    "version": "en-kjv",
    "reference": "John 3:16",
}

response = requests.get(f"{base_url}/api/verse", params=params, timeout=20)
data = response.json()

print(data)

cURL


curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=John%203%3A16"

Same-Chapter Range by Free-Text Reference

A same-chapter range may also be requested using the reference parameter.

Example:


https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Amos%208%3A4-6

Readable reference:


Amos 8:4-6

URL-encoded reference:


Amos%208%3A4-6

Current Range Limitation

ScriptureFlow currently supports same-chapter ranges.

This works:


Amos 8:4-6

This should not be used as a single request:


John 3:16-4:2

Cross-chapter ranges are not currently supported by the public /api/verse endpoint. If your application needs a passage that crosses chapter boundaries, make separate same-chapter requests and combine the results in your application.

Find Available Translations

Use the translation catalog to find supported version keys:


https://scriptureflow-api-preview.pages.dev/translations.json

The catalog helps developers identify which translations are currently available through the public API.

A translation entry may include fields such as:

Field	Meaning
`version`	The exact version key to use in API requests.
`language_code`	The language code associated with the translation.
`translation_name`	The readable translation name.
`status`	The current public readiness status.

Use the version value exactly as listed.

Public Catalog and Status Files

ScriptureFlow also exposes public metadata files.

Translation Catalog


https://scriptureflow-api-preview.pages.dev/translations.json

Use this to find supported version keys and translation metadata.

Public Catalog


https://scriptureflow-api-preview.pages.dev/public-catalog.json

Use this for public catalog-level information about available translations.

Status Summary


https://scriptureflow-api-preview.pages.dev/status.json

Use this for a public summary of current API data readiness.

Common Mistakes

Mistake 1: Using the wrong version key

Incorrect:


version=kjv

Correct:


version=en-kjv

Mistake 2: Using the wrong casing

Incorrect:


version=en-KJV

Correct:


version=en-kjv

Mistake 3: Forgetting to URL encode free-text references

Incorrect:


/api/verse?version=en-kjv&reference=John 3:16

Correct:


/api/verse?version=en-kjv&reference=John%203%3A16

Mistake 4: Trying to request a cross-chapter passage as one range

Not currently supported:


John 3:16-4:2

Use separate requests instead.

Simple Integration Pattern

Most applications can start with this basic flow:

Load translations.json.
Let the user choose a translation.
Store the selected version key.
Send a request to /api/verse.
Display the returned Scripture text and reference.
Handle errors clearly if a version, book, chapter, or verse is unavailable.

Example:


const baseUrl = "https://scriptureflow-api-preview.pages.dev";

async function getVerse({ version, book, chapter, verse }) {
  const params = new URLSearchParams({
    version,
    book,
    chapter: String(chapter),
    verse: String(verse),
  });

  const response = await fetch(`${baseUrl}/api/verse?${params.toString()}`);

  if (!response.ok) {
    const error = await response.json().catch(() => ({
      error: `HTTP ${response.status}`,
    }));

    throw new Error(error.error || `Request failed with HTTP ${response.status}`);
  }

  return response.json();
}

const data = await getVerse({
  version: "en-kjv",
  book: "John",
  chapter: 3,
  verse: 16,
});

console.log(data);

Recommended Developer Checklist

Before building deeper integration, confirm that you can:

Open translations.json.
Identify the correct version key.
Request a single verse.
Request a same-chapter passage range.
Request a free-text reference.
Handle an error response.
Avoid hardcoding unverified version names.
Avoid assuming a translation is available without checking the catalog.

Public API Boundary

The public API gives developers access to ScriptureFlow’s published API surface.

Developers do not need access to the private repository to use ScriptureFlow.

The public documentation does not include:

Internal architecture
Corpus processing details
Build or indexing logic
Deployment workflow details

For normal API usage, developers should rely on the public API endpoints and public documentation.

Next Steps

After completing this quickstart, review:

Endpoint Specification
Example Requests
Supported Languages
API Product Overview
Terms and Attribution

These documents provide additional guidance for building with ScriptureFlow.