# ScriptureFlow: expanded AI and LLM integration guide

ScriptureFlow is a public developer preview API for structured multilingual Scripture data. It is infrastructure for developers, ministries, educators, creators, AI coding assistants, and agent-powered tools. The current public preview does not require an API key.

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

## Authoritative resources

- OpenAPI 3.1 contract: https://scriptureflow-api-preview.pages.dev/openapi.yaml
- Developer docs: https://scriptureflow-dev-docs.pages.dev/
- AI usage guide: https://scriptureflow-dev-docs.pages.dev/ai/using-scriptureflow-with-ai.html
- Postman collection: https://documenter.getpostman.com/view/1355224/2sBXwvJoj6
- Concise LLM guide: https://scriptureflow-api-preview.pages.dev/llms.txt
- Translations list: https://scriptureflow-api-preview.pages.dev/translations.json
- Public catalog: https://scriptureflow-api-preview.pages.dev/public-catalog.json
- Build status: https://scriptureflow-api-preview.pages.dev/status.json
- Canonical books: https://scriptureflow-api-preview.pages.dev/canonical-books.json

The OpenAPI specification is the machine-readable source of truth for the public preview API. Use the Postman collection as a runnable testing companion.

## AI usage rules

1. Fetch Scripture text from ScriptureFlow instead of inventing, reconstructing, or paraphrasing verse text.
2. Discover version keys through `/translations.json` and use them exactly as published. For example, use `en-kjv`, not `kjv` or `en-KJV`.
3. Do not silently substitute translations. If a requested translation is unavailable, tell the user and ask before using another.
4. Preserve the translation/version attribution with retrieved Scripture text.
5. Keep Scripture text visibly separate from AI-generated commentary, summaries, explanations, or devotional material.
6. Treat the API as a developer preview. Check `/status.json` and `/public-catalog.json` for current availability.
7. Do not assume every translation has the same canon or complete coverage. Translations may be partial and may vary by canon, book availability, chapter divisions, and verse numbering.

## Endpoint guide

- `GET /translations.json` — List currently published translation version keys. Start here before making translation-scoped requests.
- `GET /public-catalog.json` — Read public availability, readiness, language, and translation summary information.
- `GET /status.json` — Read current build totals, failures, and split-index status.
- `GET /canonical-books.json` — Read canonical book identifiers and accepted aliases used for lookup normalization.
- `GET /{version}/translation.json` — Read metadata and availability totals for one exact version key.
- `GET /{version}/books.json` — List books available in a translation.
- `GET /{version}/chapters.json` — List chapters available in a translation.
- `GET /{version}/verses-index.json` — Read a verse array or split-index manifest. Prefer runtime lookup endpoints for ordinary verse retrieval.
- `GET /{version}/random.json` — Read the generated, translation-scoped Verse of the Day. This is a static generated file and does not select a new random verse on every request.
- `GET /api/verse` — Retrieve a specific verse or an inclusive same-chapter passage by free-text reference or structured fields.
- `GET /api/quick-verse` — Retrieve a runtime-selected verse for a translation. Refreshing may return a different verse.

## Example requests

Specific verse by free-text reference:

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

Same-chapter passage by structured fields:

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

Runtime-selected Quick Verse:

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

Generated translation-scoped Verse of the Day:

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

## Recommended AI workflow

1. Fetch `/translations.json` to resolve the exact requested version key.
2. Optionally inspect `/public-catalog.json` and `/{version}/translation.json` for availability and translation metadata.
3. Use `/api/verse` for a requested verse or same-chapter passage.
4. Return the API's Scripture text unchanged and include the version attribution.
5. Put any generated commentary in a clearly labeled, separate section.
6. Handle JSON errors explicitly; do not fill missing text from model memory.

## Availability and attribution

ScriptureFlow separates technical availability from translation rights. Preserve translation names, version keys, copyright notices, license information, and attribution requirements when provided. API availability does not automatically grant redistribution or commercial publication rights.