ScriptureFlow Example Requests — Public

ScriptureFlow Example Requests — Public

Purpose

This document gives developers copy-ready ScriptureFlow API examples they can try immediately.

The examples are written for people who may be new to ScriptureFlow. Some readers will be experienced developers. Others may be ministry leaders, automation builders, educators, or product teams who simply need to see what a working request looks like.

The goal is to make the API feel approachable.

These examples focus on public API usage only. They do not explain the private repository, internal build process, corpus processing, deployment pipeline, or contributor-only implementation details.

Base API URL

All examples in this document use the public preview API:

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

For the examples below, the version key is:

en-kjv

That is the catalog key for the King James Version in ScriptureFlow.

Use:

en-kjv

Do not use:

kjv

Do not use:

en-KJV

To check available version keys, open:

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

Start with a Simple Browser Request

The easiest way to test ScriptureFlow is to paste a full API URL into your browser.

Try Psalm 23:1:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1

This request asks ScriptureFlow for:

Psalm 23:1

It uses four main query parameters:

A successful response returns JSON.

Request a Same-Chapter Passage

Use end_verse when you want a passage range that stays inside the same chapter.

Try Proverbs 3:5-6:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Proverbs&chapter=3&verse=5&end_verse=6

This request asks ScriptureFlow for:

Proverbs 3:5-6

The starting verse is:

verse=5

The ending verse is:

end_verse=6

This is useful for devotionals, sermon tools, study resources, quotation widgets, and teaching apps that need a short passage rather than a single verse.

Use a Free-Text Reference

If your application has one field where a user types a reference, use the reference parameter.

Try Micah 6:8:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah%206%3A8

The readable reference is:

Micah 6:8

The URL-encoded reference is:

Micah%206%3A8

This style is helpful for search boxes, chat interfaces, form fields, automation workflows, and AI-assisted tools where the reference may start as plain user input.

Use a Free-Text Passage Range

A same-chapter range can also be requested with reference.

Try Matthew 5:14-16:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Matthew%205%3A14-16

The readable reference is:

Matthew 5:14-16

The URL-encoded reference is:

Matthew%205%3A14-16

This is a comfortable pattern when users type references the way they would naturally say them.

Try a Numbered Book

Numbered books are common in Scripture references, so it is helpful to test them early.

Try 1 John 4:8:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=1%20John%204%3A8

The readable reference is:

1 John 4:8

The URL-encoded reference is:

1%20John%204%3A8

This is a good example to test if your app lets people type references into a single field.

Browser Examples

Use these when you want to quickly confirm the API is responding.

Psalm 23:1

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1

Proverbs 3:5-6

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Proverbs&chapter=3&verse=5&end_verse=6

Micah 6:8

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah%206%3A8

Matthew 5:14-16

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Matthew%205%3A14-16

1 John 4:8

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=1%20John%204%3A8

JavaScript Fetch Examples

JavaScript is a natural fit for websites, browser tools, dashboards, and front-end apps.

Single Verse

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

const response = await fetch(
  `${baseUrl}/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1`
);

const data = await response.json();

console.log(data);

Same-Chapter Passage

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

const response = await fetch(
  `${baseUrl}/api/verse?version=en-kjv&book=Proverbs&chapter=3&verse=5&end_verse=6`
);

const data = await response.json();

console.log(data);

Free-Text Reference

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

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

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

console.log(data);

Reusable Helper Function

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

async function getScriptureByReference(reference, version = "en-kjv") {
  const params = new URLSearchParams({
    version,
    reference,
  });

  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 getScriptureByReference("Matthew 5:14-16");

console.log(data);

Python Examples

Python is useful for scripts, research tools, prototypes, content workflows, and backend services.

Single Verse

import requests

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

params = {
    "version": "en-kjv",
    "book": "Psalm",
    "chapter": 23,
    "verse": 1,
}

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

print(data)

Same-Chapter Passage

import requests

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

params = {
    "version": "en-kjv",
    "book": "Proverbs",
    "chapter": 3,
    "verse": 5,
    "end_verse": 6,
}

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

print(data)

Free-Text Reference

import requests

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

params = {
    "version": "en-kjv",
    "reference": "Micah 6:8",
}

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

print(data)

Reusable Python Helper

import requests

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

def get_scripture_reference(reference, version="en-kjv"):
    params = {
        "version": version,
        "reference": reference,
    }

    response = requests.get(f"{BASE_URL}/api/verse", params=params, timeout=20)
    response.raise_for_status()

    return response.json()

data = get_scripture_reference("1 John 4:8")

print(data)

cURL Examples

cURL is useful when testing from a terminal or debugging a request quickly.

Single Verse

curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1"

Same-Chapter Passage

curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Proverbs&chapter=3&verse=5&end_verse=6"

Free-Text Reference

curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah%206%3A8"

Free-Text Passage

curl "https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Matthew%205%3A14-16"

Translation Catalog Request

Before building a translation selector, request the public translation catalog.

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

JavaScript:

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

const response = await fetch(`${baseUrl}/translations.json`);
const translations = await response.json();

console.log(translations);

Python:

import requests

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

response = requests.get(f"{base_url}/translations.json", timeout=20)
translations = response.json()

print(translations)

cURL:

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

A common application pattern is:

1. Load translations.json.
2. Let the user choose a translation.
3. Store the selected version key.
4. Use that key in later /api/verse requests.

Public Catalog Request

The public catalog provides additional catalog-level information.

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

JavaScript:

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

const response = await fetch(`${baseUrl}/public-catalog.json`);
const catalog = await response.json();

console.log(catalog);

Python:

import requests

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

response = requests.get(f"{base_url}/public-catalog.json", timeout=20)
catalog = response.json()

print(catalog)

cURL:

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

Status Request

The status file gives a public summary of the current generated API output.

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

JavaScript:

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

const response = await fetch(`${baseUrl}/status.json`);
const status = await response.json();

console.log(status);

Python:

import requests

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

response = requests.get(f"{base_url}/status.json", timeout=20)
status = response.json()

print(status)

cURL:

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

n8n and Automation Tool Guidance

Automation tools usually work best with the free-text reference pattern because the reference can come from a form, spreadsheet, AI prompt, webhook, or chat message.

A simple automation flow might look like this:

1. A form submits a Bible reference such as Micah 6:8.
2. The workflow stores the selected version key, such as en-kjv.
3. An HTTP Request step calls ScriptureFlow.
4. The workflow uses the returned JSON in an email, document, devotional workflow, teaching tool, or content generator.

Example HTTP request URL:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah%206%3A8

If your automation tool provides query parameter fields, use those instead of manually building the URL:

Most automation tools will handle URL encoding when query parameters are entered separately.

Example App Ideas

These examples are small, but they can support larger products and workflows.

A developer could use these requests to build:

• A Bible verse lookup widget
• A sermon preparation helper
• A devotional content workflow
• A Scripture reference checker
• A multilingual Scripture comparison tool
• A teaching slide generator
• A Bible study form or dashboard
• A ministry chatbot that retrieves passages
• A workflow that adds Scripture passages to emails or documents

The main idea is simple: your application does not need to rebuild the Scripture data layer. It can request structured Scripture data from ScriptureFlow.

Handling Errors Comfortably

Not every request will succeed. A user may mistype a book, choose an unavailable translation, or request a passage that is not currently supported.

JavaScript example:

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

async function safeGetReference(reference, version = "en-kjv") {
  const params = new URLSearchParams({
    version,
    reference,
  });

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

  if (!response.ok) {
    return {
      ok: false,
      status: response.status,
      message: body?.error || "The passage could not be retrieved.",
      details: body,
    };
  }

  return body;
}

const result = await safeGetReference("Matthew 5:14-16");

console.log(result);

A good application should show a helpful message instead of failing silently.

Common Mistakes to Avoid

Mistake 1: Using kjv instead of en-kjv

Incorrect:

https://scriptureflow-api-preview.pages.dev/api/verse?version=kjv&book=Psalm&chapter=23&verse=1

Correct:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1

Mistake 2: Using en-KJV instead of en-kjv

Incorrect:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-KJV&book=Psalm&chapter=23&verse=1

Correct:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1

Mistake 3: Forgetting to encode a free-text reference

Risky when building URLs manually:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah 6:8

Safer URL:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah%206%3A8

Better in code:

const reference = encodeURIComponent("Micah 6:8");

Mistake 4: Requesting a cross-chapter passage as one range

Not currently supported as one request:

John 3:16-4:2

Use separate same-chapter requests and combine the results in your application.

Recommended First Five Tests

If you are testing ScriptureFlow for the first time, try these in order:

1. Open the translation catalog:

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

1. Request Psalm 23:1:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Psalm&chapter=23&verse=1

1. Request Proverbs 3:5-6:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&book=Proverbs&chapter=3&verse=5&end_verse=6

1. Request Micah 6:8 using free-text reference:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=Micah%206%3A8

1. Request 1 John 4:8 using free-text reference:

https://scriptureflow-api-preview.pages.dev/api/verse?version=en-kjv&reference=1%20John%204%3A8

If these work, you understand the core public request patterns.

Public API Boundary

These examples show how to use the public API.

They do not explain:

• Internal build process
• Corpus processing details
• Deployment workflow internals
• Contributor-only implementation rules

Developers can build useful Scripture-powered tools with the public API and public documentation alone.

Next Steps

After trying these examples, review:

• Developer Quickstart
• Endpoint Specification
• Supported Languages
• API Product Overview
• Terms and Attribution