ScriptureFlow Endpoint Specification — Public

Purpose

This document defines the public behavior of ScriptureFlow’s current API and static JSON resources. It is written for API users, app developers, automation builders, ministries, educators, and product teams.

This public version intentionally avoids private repository details, internal build logic, corpus processing details, deployment internals, and contributor-only implementation guidance.

Base URL

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

Endpoint Summary

ScriptureFlow provides both static JSON resources and function-powered runtime API endpoints.

Runtime API endpoints

Static JSON endpoints

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

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

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

Request Headers

No custom request headers are required for the current public preview.

The current public preview does not require API keys, bearer tokens, session cookies, or custom authentication headers.

/api/verse — Specific Verse or Passage Lookup

Use /api/verse to retrieve one verse or a same-chapter passage range from a selected translation.

Structured lookup

GET /api/verse?version=en-kjv&book=John&chapter=3&verse=16

Same-chapter passage range

GET /api/verse?version=en-kjv&book=Amos&chapter=8&verse=4&end_verse=6

Free-text reference lookup

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

Query parameters

Example response shape

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

/api/quick-verse — Runtime Quick Verse

Quick Verse returns a runtime-selected verse from the requested translation. Refreshing the request may return a different verse.

Request

GET /api/quick-verse?version=en-kjv

Full preview URL

https://scriptureflow-api-preview.pages.dev/api/quick-verse?version=en-kjv

Query parameters

Behavior

• Uses the requested translation’s own verse index.
• Can return a different verse when refreshed.
• Does not replace /[version]/random.json.
• Does not force one shared verse across translations.
• Returns JSON with type: "quick_verse".

Example response shape

{
  "ok": true,
  "type": "quick_verse",
  "version": "en-kjv",
  "reference": "John 3:16",
  "book": "john",
  "chapter": 3,
  "verse": 16,
  "text": "...",
  "source": {
    "method": "runtime_random",
    "index": "/en-kjv/verses-index.json",
    "api_path": "/en-kjv/books/john/chapters/3/verses/16.json"
  },
  "lookup": {
    "method": "single-index",
    "index": "/en-kjv/verses-index.json"
  }
}

/[version]/random.json — Verse of the Day

Each public translation includes a generated Verse of the Day at /[version]/random.json. This is a static generated JSON file. It updates when the ScriptureFlow generator runs. It does not return a new random verse on every refresh.

Example

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

Behavior

• Generated separately for each public translation.
• Uses that translation’s own available verse index.
• Safe for daily cards, devotional prompts, homepage widgets, or scheduled workflows.
• Not intended as a live random endpoint.

Example response shape

{
  "version": "en-kjv",
  "reference": "Ezekiel 27:35",
  "book": "ezekiel",
  "chapter": 27,
  "verse": 35,
  "text": "...",
  "book_slug": "ezekiel",
  "canonical_book": "ezekiel",
  "source_path": "bibles/en-kjv/books/ezekiel/chapters/27/verses/35.json",
  "api_path": "/en-kjv/books/ezekiel/chapters/27/verses/35.json"
}

Error Responses

Failed runtime API requests return JSON with ok: false where possible.

Missing Quick Verse version

{
  "ok": false,
  "type": "quick_verse",
  "error": "Missing required query parameter: version",
  "example": "/api/quick-verse?version=en-kjv"
}

Version not found

{
  "ok": false,
  "type": "quick_verse",
  "error": "Version index not found",
  "version": "en-nkjv",
  "index": "/en-nkjv/verses-index.json"
}

Invalid verse lookup query

{
  "ok": false,
  "error": "Invalid query. Required: version plus either reference (e.g. John 3:16) or book/chapter/verse.",
  "query": {
    "version": "en-kjv"
  }
}

Safe Builder Guidance

• Use exact version keys from /translations.json.
• Do not treat generated summaries, paraphrases, or AI explanations as Scripture text.
• Use ScriptureFlow response fields for Scripture text.
• Use Verse of the Day for stable daily display.
• Use Quick Verse for refreshable random verse experiences.