ScriptureFlow Endpoint Specification — Public

ScriptureFlow Endpoint Specification — Public

Purpose

This document defines the public behavior of ScriptureFlow’s current scripture lookup endpoint.

It explains how client applications call the API, which query parameters are supported, how version identifiers must be formatted, what successful and failed responses look like, and which limitations developers should understand before building on ScriptureFlow.

This public version is written for API users, app developers, automation builders, ministries, educators, and product teams. It intentionally avoids private repository details, internal build logic, corpus processing details, deployment internals, and contributor-only implementation guidance.

Endpoint Summary

ScriptureFlow currently provides a public scripture lookup endpoint for retrieving one verse or a same-chapter verse range.

Current public preview base URL:

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

Primary lookup endpoint:

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

HTTP method:

GET

Response format:

JSON

Primary use:

Retrieve a Bible verse or same-chapter verse range from a selected Bible version or translation.

The endpoint supports two lookup styles:

Public API Boundary

The public endpoint is designed for using ScriptureFlow, not reproducing ScriptureFlow.

This public specification does not document:

• Deployment workflow details
• Contributor-only implementation rules
• Private roadmap or business strategy

Developers do not need access to the private repository to use the public API.

Version Identifier Rule

The version parameter is an exact machine-readable key. It is not a display label.

For the King James Version, use:

en-kjv

Do not use:

kjv

Do not use:

en-KJV

Correct request:

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

Incorrect request:

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

Incorrect request:

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

Client applications should confirm supported version keys from the translation catalog:

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

Use the version key exactly as listed.

Request Headers

No custom request headers are required for the current public lookup behavior.

Recommended client header:

The current public preview does not require:

• API keys
• Bearer tokens
• Session cookies
• Custom authentication headers

If authentication, API keys, or rate limits are added later, this section should be updated.

Query Parameters

Common Parameter

Structured Lookup Parameters

Free-Text Lookup Parameter

Lookup Mode Rules

The endpoint supports two request modes.

Mode 1: Structured Lookup

Structured lookup uses separate book, chapter, and verse parameters.

Example:

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

Structured lookup is useful for apps, forms, automations, and workflows where the scripture reference is already divided into separate fields.

Mode 2: Free-Text Reference Lookup

Free-text lookup uses a non-empty reference parameter.

Example:

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

Free-text lookup is useful when a user types a reference naturally into one field.

Lookup Priority

If a request includes a non-empty reference parameter, the API treats the request as a free-text reference lookup.

If no reference parameter is provided, the API uses structured lookup fields.

Structured Lookup Examples

Single Verse

Request:

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

Expected behavior:

The API returns John 3:16 from the King James Version.

Same-Chapter Verse Range

Request:

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

Expected behavior:

The API returns Amos 8:4 through Amos 8:6 from the King James Version.

Using start_verse

The endpoint also supports start_verse as an alternate starting verse parameter.

Request:

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

Recommended public usage:

Use verse unless your application specifically needs start_verse for clarity.

Lowercase Book Slug

Request:

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

Expected behavior:

The API normalizes the book input and returns John 3:16 if the selected version contains the requested passage.

Book Alias

Request:

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

Expected behavior:

If the alias is supported by the public canonical book mapping used by the API, the API resolves it to John and returns John 3:16.

If the alias is not supported, the API returns an error instead of silently returning the wrong passage.

Free-Text Reference Lookup Examples

Single Verse Reference

Request:

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

Human-readable reference:

John 3:16

Expected behavior:

The API parses the reference and returns John 3:16 from the King James Version.

Same-Chapter Range Reference

Request:

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

Human-readable reference:

Amos 8:4-6

Expected behavior:

The API parses the reference and returns Amos 8:4 through Amos 8:6 from the King James Version.

Numbered Book Reference

Request:

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

Human-readable reference:

1 John 4:8

Expected behavior:

The API parses the numbered book name and returns the requested verse if the passage exists in the selected version.

URL Encoding Requirements

Clients should URL-encode references when sending them as query parameter values.

Common encoded characters:

Human-readable reference:

John 3:16

Encoded query value:

John%203%3A16

Full request:

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

Most browsers and HTTP libraries handle encoding automatically. Manually built URLs and automation tools should encode references correctly.

Successful Response Structure

A successful response returns JSON.

The current response structure includes:

Example Single-Verse Response Shape

{
  "ok": true,
  "query": {
    "version": "en-kjv",
    "book": "John",
    "canonical_book": "john",
    "chapter": 3,
    "verse": 16
  },
  "reference": "John 3:16",
  "result": {
    "id": "en-kjv:john:3:16",
    "version": "en-kjv",
    "book": "John",
    "book_slug": "john",
    "canonical_book": "john",
    "chapter": 3,
    "verse": 16,
    "reference": "John 3:16",
    "text": "..."
  },
  "lookup": {
    "method": "single-index"
  }
}

Example Same-Chapter Range Response Shape

{
  "ok": true,
  "query": {
    "version": "en-kjv",
    "book": "Amos",
    "canonical_book": "amos",
    "chapter": 8,
    "verse": 4,
    "end_verse": 6
  },
  "reference": "Amos 8:4-6",
  "result": [
    {
      "id": "en-kjv:amos:8:4",
      "version": "en-kjv",
      "book": "Amos",
      "book_slug": "amos",
      "canonical_book": "amos",
      "chapter": 8,
      "verse": 4,
      "reference": "Amos 8:4",
      "text": "..."
    },
    {
      "id": "en-kjv:amos:8:5",
      "version": "en-kjv",
      "book": "Amos",
      "book_slug": "amos",
      "canonical_book": "amos",
      "chapter": 8,
      "verse": 5,
      "reference": "Amos 8:5",
      "text": "..."
    },
    {
      "id": "en-kjv:amos:8:6",
      "version": "en-kjv",
      "book": "Amos",
      "book_slug": "amos",
      "canonical_book": "amos",
      "chapter": 8,
      "verse": 6,
      "reference": "Amos 8:6",
      "text": "..."
    }
  ],
  "lookup": {
    "method": "single-index"
  }
}

The scripture text is represented with an ellipsis in this document to keep the specification focused on structure.

Result Object Guidance

A result object normally includes fields that identify the version, book, chapter, verse, reference, and scripture text.

Public consumers should rely primarily on these fields:

Additional fields may appear in some responses. Unless a field is documented as part of the public contract, client applications should avoid depending on it for core functionality.

HTTP Status Codes

The endpoint uses clear HTTP status codes.

The API should not return a successful 200 response for failed lookups.

Error Response Structure

Error responses return JSON.

Current error responses generally include:

Invalid Query Example

{
  "ok": false,
  "error": "Invalid query. Required: version plus either reference (e.g. John 3:16) or book/chapter/verse. Optional: end_verse (positive integer and >= start verse).",
  "query": {
    "version": "en-kjv",
    "book": "John",
    "chapter": 3,
    "verse": null
  }
}

Version Not Found Example

{
  "ok": false,
  "error": "Version index not found",
  "query": {
    "version": "kjv",
    "book": "John",
    "canonical_book": "john",
    "chapter": 3,
    "verse": 16
  }
}

Missing Verse Example

{
  "ok": false,
  "error": "One or more requested verses were not found",
  "query": {
    "version": "en-kjv",
    "book": "Amos",
    "canonical_book": "amos",
    "chapter": 8,
    "verse": 4,
    "end_verse": 99
  },
  "missing_verses": [99]
}

Error responses should not expose stack traces, secrets, or unnecessary deployment details.

Required Parameter Rules

Structured Lookup

A structured lookup request must include:

• version
• book
• chapter
• verse or start_verse

Optional:

• end_verse

Valid structured request:

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

Invalid structured request:

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

Reason invalid:

The starting verse parameter is missing.

Free-Text Reference Lookup

A free-text lookup request must include:

• version
• reference

Valid free-text request:

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

Invalid free-text request:

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

Reason invalid:

The version parameter is missing.

Book Matching Behavior

The API resolves book input using normalized matching and canonical book identity where available.

Current lookup behavior may match against:

• Canonical book values
• Normalized book slug values
• Normalized book names
• Supported aliases
• Localized aliases where available

This behavior helps ScriptureFlow support multilingual and cross-language lookup patterns over time.

Developers should still test the book names, aliases, and references they plan to support in their own applications.

Verse Range Behavior

The current endpoint supports same-chapter verse ranges.

Supported human-readable example:

Amos 8:4-6

Structured request:

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

Free-text request:

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

Expected behavior:

The API returns Amos 8:4, Amos 8:5, and Amos 8:6 in verse order.

Current limitation:

Cross-chapter ranges are not supported yet.

Unsupported example:

John 3:16-4:2

Expected current behavior:

The API returns a clear error indicating that cross-chapter ranges are not supported yet.

Version Handling

The version parameter identifies which Bible version or translation should be searched.

Correct KJV example:

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

The API should:

• Accept exact supported version identifiers.
• Reject unsupported version identifiers clearly.
• Search only the requested version.
• Avoid silently falling back to a different version.

The supported version list should be read from:

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

A client should not assume that a short abbreviation such as kjv, lsv, or web will work unless that exact identifier appears in the translation catalog.

Static JSON Resources

In addition to the function-powered verse lookup endpoint, ScriptureFlow exposes public static JSON resources.

Catalog and Status Files

Per-Translation Files

Per-translation file paths follow this pattern:

Example using en-kjv:

https://scriptureflow-api-preview.pages.dev/en-kjv/translation.json

https://scriptureflow-api-preview.pages.dev/en-kjv/books.json

https://scriptureflow-api-preview.pages.dev/en-kjv/chapters.json

https://scriptureflow-api-preview.pages.dev/en-kjv/verses-index.json

https://scriptureflow-api-preview.pages.dev/en-kjv/random.json

Some large translations may use a split-index manifest instead of a single large verse array. The /api/verse endpoint is designed to hide that complexity from normal lookup clients.

Split-Index Lookup Behavior

Some translation indexes may be split into multiple part files.

When the API detects a split-index manifest, it searches the part files and returns the requested verse or range.

The lookup response may include:

{
  "lookup": {
    "method": "split-index"
  }
}

Client applications generally do not need to handle split-index logic directly when using /api/verse.

Multilingual Considerations

Multilingual support is a central part of ScriptureFlow’s direction.

The current endpoint uses canonical book matching and normalized matching to help connect user input to the selected translation’s data. This is especially important when a user enters a familiar book name while requesting a translation in another language.

Developers should understand the current boundary:

• Canonical book identity provides a stronger foundation for multilingual lookup.
• Supported aliases and localized aliases may improve lookup behavior.
• Full language-aware reference parsing is still an area for future improvement.
• Applications should test the reference styles they plan to support.

Response Headers

The public lookup endpoint currently returns browser-friendly response headers.

Client applications should still design their own error handling and caching strategy.

Current Public Limitations

The current public endpoint has several known limitations:

• Cross-chapter ranges are not supported as a single request.
• Version identifiers must exactly match the catalog key.
• Free-text parsing supports common reference patterns, but not every possible citation style.
• Some aliases or localized book names may not resolve unless they are present in the current canonical book mapping.
• Public preview behavior may change as ScriptureFlow matures toward formal versioned releases.

Recommended Client Behavior

Client applications should:

• Read translations.json before assuming a version is available.
• Use exact version keys from the catalog.
• Use verse as the preferred starting verse parameter.
• Use end_verse only for same-chapter ranges.
• URL-encode free-text references.
• Treat text, reference, book, chapter, verse, and version as the primary display fields.
• Handle 400, 404, and 500 responses gracefully.
• Avoid silently falling back to another translation when a requested version is unavailable.
• Avoid depending on undocumented extra fields.

Quick Test URLs

Single verse:

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

Same-chapter range:

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

Free-text single verse:

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

Free-text same-chapter range:

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

Translation catalog:

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

Next Steps

After reviewing this endpoint specification, developers should review:

• Developer Quickstart
• Example Requests
• Supported Languages
• Terms and Attribution

Together, these public documents explain how to build with ScriptureFlow while keeping the private implementation and internal repository materials protected.