Bible API Documentation — Canonical Scripture Infrastructure

Technical documentation for the BibleBridge Production-Grade Bible API and Deterministic Reference Integrity Engine.

Canonical identifiers are immutable by design.

API Overview

Base URL

Authentication

All authenticated requests require an API key passed in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Legacy Authentication (Deprecated)

Passing API keys via query parameters is supported for legacy clients only using the key parameter:

Quick Start

Retrieve Scripture instantly using natural human-written references.

curl --get https://holybible.dev/api/passage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode reference="jer29:11" \
  --data version=KJV

Note (Windows PowerShell): PowerShell aliases curl to Invoke-WebRequest. If the command fails, run curl.exe instead.

Quick Start Response

{
  "status": "success",
  "type": "single",
  "version": "KJV",
  "osis_id": "Jer.29.11",
  "results_count": 1,
  "verse_units": 1,
  "data": [
    {
      "book": "Jeremiah",
      "chapter": 29,
      "verse": 11,
      "text": "For I know the thoughts that I think toward you, saith the LORD, thoughts of peace, and not of evil, to give you an expected end."
    }
  ]
}

Response Guarantees

• All endpoints return JSON with a status field.
• Successful responses include status: "success".
• Error responses include status: "error" and a descriptive message.
• Canonical identifiers (book_id, verse_id, osis_id) are stable and immutable.
• Fields are never removed without versioning.

Building something more structured?

The same Reference Integrity Engine that powers /passage also exposes canonical Scripture coordinates directly through the /resolve endpoint. These coordinates allow applications to store normalized references, expand ranges, traverse context, and retrieve Scripture text across translations.

Typical Scripture Retrieval Workflows

BibleBridge supports two approaches.
The /passage resolves and retrieves in a single call.
The canonical workflow begins with /resolve and exposes structured canonical verse coordinates for traversal, indexing, comparison, and AI processing.

Human reference
      ↓
/passage
      ↓
Verse text returned

Human reference
      ↓
/resolve
      ↓
Canonical verse coordinates
      ├─ /expand
      ├─ /context
      ├─ /lookup
      ├─ /diff
      ├─ /range
      ├─ /distance
      └─ /slice

Live Sandbox (No API Key Required)

Try the BibleBridge API instantly using the sandbox endpoint. This sandbox returns a real, live response using the same schema as the production API.

Sandbox request

curl "https://holybible.dev/api/sandbox?book_id=19&chapter=117"

View live sandbox response

Sandbox limitations: KJV only, full chapters only, evaluation use.

Rate limit: 10 requests per 5 seconds (shared, unauthenticated)

Passage Retrieval (Reference-Based Endpoint)

The /passage endpoint allows applications to resolve and retrieve complex Scripture references in a single request. Compound references can traverse chapters, carry context forward, and even span multiple books while remaining structurally validated and canon-aware.

The same Reference Integrity Engine that powers /resolve runs inside every /passage request.

The Deterministic Reference Integrity Engine interprets flexible human-written input, expands it into canonical spans, assigns a canonical OSIS identifier, and retrieves the corresponding verse text — allowing developers to safely accept real-world Scripture references without implementing their own parsing, validation, or cross-book resolution logic.

Passage Request

curl --get https://holybible.dev/api/passage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode reference="rom8:1-4" \
  --data version=KJV

Passage Response

{
    "status": "success",
    "type": "single",
    "version": "KJV",
    "osis_id": "Rom.8.1-Rom.8.4",
    "results_count": 4,
    "verse_units": 4,
    "data": [
        {
            "book": "Romans",
            "chapter": 8,
            "verse": 1,
            "text": "There is therefore now no condemnation to them which are in Christ Jesus, who walk not after the flesh, but after the Spirit."
        },
        {
            "book": "Romans",
            "chapter": 8,
            "verse": 2,
            "text": "For the law of the Spirit of life in Christ Jesus hath made me free from the law of sin and death."
        },
        {
            "book": "Romans",
            "chapter": 8,
            "verse": 3,
            "text": "For what the law could not do, in that it was weak through the flesh, God sending his own Son in the likeness of sinful flesh, and for sin, condemned sin in the flesh:"
        },
        {
            "book": "Romans",
            "chapter": 8,
            "verse": 4,
            "text": "That the righteousness of the law might be fulfilled in us, who walk not after the flesh, but after the Spirit."
        }
    ]
}

Supported Reference Formats

The endpoint accepts flexible human-written references including:

• john3:16
• rom 8:1-4
• ps 23
• 1 cor 13:4-8,13
• jn316

All references are validated against canonical chapter and verse boundaries before Scripture retrieval.

Ambiguous Reference Handling

When a reference cannot be deterministically resolved to a single canonical book, the engine surfaces ranked candidate matches instead of guessing. This allows client applications to present "Did you mean?" suggestions or request clarification from the user before retrieving Scripture text.

For example, the input "Samuel" could correspond to multiple books. The API returns structured candidate matches ranked by semantic weighting and resolution confidence.

{
  "status": "error",
  "error": "ambiguous_reference",
  "input": "Samuel",
  "candidates": [
    {
      "key": "1SA",
      "id": 9,
      "name": "1 Samuel",
      "osis": "1Sam",
      "weight": 70,
      "score": 0.8275
    },
    {
      "key": "2SA",
      "id": 10,
      "name": "2 Samuel",
      "osis": "2Sam",
      "weight": 70,
      "score": 0.8275
    }
  ]
}

BibleBridge Deterministic Reference Integrity Engine

BibleBridge provides production-grade Scripture reference normalization and validation infrastructure. It converts flexible, human-readable Scripture input into validated, immutable canonical coordinates that applications can trust.

The engine operates on canonical structure and requires no Bible version — version is only selected at text retrieval.

Try the live reference resolver (no signup required):

Scripture Reference Resolver

Enter any human-written Bible reference and see how it resolves into canonical coordinates.

Developers can add reliable Scripture reference handling to applications with a single API call, eliminating the need to build and maintain complex parsing logic.

Real-world user input is inconsistent — abbreviations, ordinals, partial book names, punctuation variants, malformed ranges, and compound references. The Reference Integrity Engine interprets these variations deterministically and returns canon-aware, structurally validated outputs.

Applications can safely accept user-generated Scripture references without risking silent ambiguity, invalid chapter or verse spans, or canonical drift.

Why this matters in production: Why Regex Fails for Scripture Input

Deterministic System Design

BibleBridge is deterministic by design. Identical inputs always produce identical canonical outputs. The API does not rely on probabilistic matching or heuristic guessing when resolving Scripture references.

Applications can safely cache results, persist canonical identifiers, and build long-lived data structures without risk of canonical drift.

Core Capabilities

• Deterministic canonical normalization: Converts flexible human input into stable, verse-addressable canonical structures.
• Multi-segment passage resolution: Parses compound expressions (commas, semicolons, implicit chapter carry-forward) into ordered canonical segments.
• Structural coordinate output: Returns canonical span coordinates suitable for direct database indexing and internal system lookup.
• Canon-aware validation: Enforces authoritative chapter and verse boundaries for every book.
• Ambiguity surfacing: Returns ordered candidate matches rather than silently guessing.
• Weighted semantic matching: Resolves abbreviations, aliases, ordinals, and partial names using ranked scoring with confidence reporting.
• Malformed input recovery: Corrects structurally invalid or partially corrupted references using rule-based reinterpretation, reporting adjustments when applied.
• OSIS-compatible output: Generates official OSIS identifiers (e.g., 2Sam.1.19-25) for interoperability with scholarly and XML-based tooling.

Reference Transformation

Ps.23, vv.1—3

ps 23:1-3

Ps.23.1-Ps.23.3

Example Request

curl --get https://holybible.dev/api/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode reference="rom 8:1-4, 28; 12:1-2"

Example Output

{
  "type": "collection",
  "valid": true,
  "input": "rom 8:1-4, 28; 12:1-2",
  "osis_id": "Rom.8.1-Rom.8.4,Rom.8.28,Rom.12.1-Rom.12.2",
  "references": [
    {
      "type": "single",
      "valid": true,
      "input": "rom 8:1-4, 28",
      "book": {
        "key": "ROM",
        "book_id": 45,
        "name": "Romans",
        "slug": "romans"
      },
      "spans": [
        {
          "start": {
            "chapter": 8,
            "verse": 1
          },
          "end": {
            "chapter": 8,
            "verse": 4
          }
        },
        {
          "start": {
            "chapter": 8,
            "verse": 28
          },
          "end": {
            "chapter": 8,
            "verse": 28
          }
        }
      ],
      "osis_id": "Rom.8.1-Rom.8.4,Rom.8.28",
      "confidence": 0.9765
    },
    {
      "type": "single",
      "valid": true,
      "input": "Romans 12:1-2",
      "book": {
        "key": "ROM",
        "book_id": 45,
        "name": "Romans",
        "slug": "romans"
      },
      "spans": [
        {
          "start": {
            "chapter": 12,
            "verse": 1
          },
          "end": {
            "chapter": 12,
            "verse": 2
          }
        }
      ],
      "osis_id": "Rom.12.1-Rom.12.2",
      "confidence": 0.985
    }
  ]
}

The Reference Integrity Engine returns a confidence score between 0 and 1 indicating how clearly the input reference maps to a canonical Scripture structure.

Advanced Resolution Example

Input
1 cor 13:4-8,13;14:1-3,12-15;15:3-4,20-22

Canonical OSIS
1Cor.13.4-1Cor.13.8,1Cor.13.13,
1Cor.14.1-1Cor.14.3,1Cor.14.12-1Cor.14.15,
1Cor.15.3-1Cor.15.4,1Cor.15.20-1Cor.15.22

Every resolved reference conforms to authoritative canonical boundaries and returns validated structural coordinates. Downstream systems can operate exclusively on normalized reference data, eliminating ambiguity and preventing structurally invalid Scripture lookups.

Production or long-term usage may require production or enterprise access.

Span Expansion (Canonical Verse Coordinates)

The /expand endpoint converts canonical span coordinates into atomic verse units. It expands chapter ranges, cross-chapter spans, and compound references into ordered verse coordinates that downstream systems can process deterministically.

This endpoint is useful for applications that need to inspect or index individual verses before retrieving text, such as search systems, analytics pipelines, or AI retrieval workflows.

Expand Request

curl --get https://holybible.dev/api/expand \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode reference="rom 8:1-4, 28"

Expand Response

{
    "status": "success",
    "reference": "rom 8:1-4, 28",
    "osis_id": "Rom.8.1-Rom.8.4,Rom.8.28",
    "verse_count": 5,
    "ranges": [
        {
            "range_start": 45008001,
            "range_end": 45008004
        },
        {
            "range_start": 45008028,
            "range_end": 45008028
        }
    ],
    "verse_ids": [
        45008001,
        45008002,
        45008003,
        45008004,
        45008028
    ],
    "verse_indexes": [
        28118,
        28119,
        28120,
        28121,
        28145
    ],
    "data": [
        {
            "verse_id": 45008001,
            "verse_index": 28118,
            "book": {
                "id": 45,
                "name": "Romans"
            },
            "chapter": 8,
            "verse": 1
        },
        {
            "verse_id": 45008002,
            "verse_index": 28119,
            "book": {
                "id": 45,
                "name": "Romans"
            },
            "chapter": 8,
            "verse": 2
        },
        {
            "verse_id": 45008003,
            "verse_index": 28120,
            "book": {
                "id": 45,
                "name": "Romans"
            },
            "chapter": 8,
            "verse": 3
        },
        {
            "verse_id": 45008004,
            "verse_index": 28121,
            "book": {
                "id": 45,
                "name": "Romans"
            },
            "chapter": 8,
            "verse": 4
        },
        {
            "verse_id": 45008028,
            "verse_index": 28145,
            "book": {
                "id": 45,
                "name": "Romans"
            },
            "chapter": 8,
            "verse": 28
        }
    ]
}

Scripture Retrieval (Coordinate-Based Endpoint)

The /scripture endpoint retrieves verses using canonical coordinates (book ID, chapter, verse, or verse range). Unlike the /passage endpoint, which resolves human-written references, the scripture endpoint operates directly on structured canonical identifiers.

Fetch a Single Verse

curl --get https://holybible.dev/api/scripture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data book_id=19 \
  --data chapter=23 \
  --data verse=1 \
  --data version=KJV

Fetch a Verse Range

curl --get https://holybible.dev/api/scripture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data book_id=19 \
  --data chapter=23 \
  --data range=1-6 \
  --data version=KJV

Each plan includes a maximum number of verse units per request.

Fetch a Full Chapter

curl --get https://holybible.dev/api/scripture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data book_id=19 \
  --data chapter=23 \
  --data version=KJV

Full-chapter retrieval is available on all plans. Daily quotas and rate limits apply.

Fetch a Cross-Chapter Span

curl --get https://holybible.dev/api/scripture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data book_id=1 \
  --data chapter=1 \
  --data verse=1 \
  --data endChapter=2 \
  --data endVerse=3 \
  --data version=KJV

Useful for retrieving passages that span multiple chapters, such as the full Creation account (Genesis 1:1–2:3).

Cross-chapter spans also support cross-translation comparison using the compare parameter (Production + Enterprise plans).

Cross-Translation Comparison

BibleBridge supports server-side verse alignment across two Bible translations. This allows accurate comparison without client-side joins or schema assumptions.

curl --get https://holybible.dev/api/scripture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data book_id=19 \
  --data chapter=23 \
  --data range=1-3 \
  --data version=KJV \
  --data compare=ASV

Comparison behavior: When using the compare parameter, results are returned at the chapter level by default. The verse parameter is ignored unless a range is explicitly specified.

Cross-Translation Response

{
  "status": "success",
  "type": "comparison_range",
  "primary_version": "KJV",
  "compare_version": "ASV",
  "book": {
    "id": 19,
    "name": "Psalm"
  },
  "chapter": 23,
  "range": "1-3",
  "results_count": 3,
  "data": [
    {
      "verse": 1,
      "KJV": "A Psalm of David. The LORD is my shepherd; I shall not want.",
      "ASV": "A Psalm of David. Jehovah is my shepherd; I shall not want."
    },
    {
      "verse": 2,
      "KJV": "He maketh me to lie down in green pastures: he leadeth me beside the still waters.",
      "ASV": "He maketh me to lie down in green pastures; He leadeth me beside still waters."
    },
    {
      "verse": 3,
      "KJV": "He restoreth my soul: he leadeth me in the paths of righteousness for his name's sake.",
      "ASV": "He restoreth my soul: He guideth me in the paths of righteousness for his name's sake."
    }
  ]
}

Comparison responses are generated server-side using canonical verse alignment, eliminating the need for client-side joins or translation-specific indexing. Comparison availability depends on plan level.

Request Parameters (Scripture Retrieval)

Context Retrieval (Surrounding Verses)

The /context endpoint retrieves verses surrounding a specific canonical verse coordinate. It returns a deterministic context window centered on the requested verse, making it useful for AI retrieval systems, study tools, and applications that require nearby Scripture for interpretation or display.

Context windows are calculated using the canonical verse index, allowing the API to traverse chapter and book boundaries without requiring client-side logic.

Context Request

curl --get https://holybible.dev/api/context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data verse_id=45008028 \
  --data window=2

Context Response

{
  "status": "success",
  "center": {
    "verse_id": 45008028,
    "verse_index": 28145,
    "reference": "Romans 8:28",
    "osis_id": "Rom.8.28"
  },
  "window": 2,
  "results_count": 5,
  "data": [
    {
      "verse_id": 45008026,
      "verse_index": 28143,
      "reference": "Romans 8:26",
      "osis_id": "Rom.8.26",
      "offset": -2
    },
    {
      "verse_id": 45008027,
      "verse_index": 28144,
      "reference": "Romans 8:27",
      "osis_id": "Rom.8.27",
      "offset": -1
    },
    {
      "verse_id": 45008028,
      "verse_index": 28145,
      "reference": "Romans 8:28",
      "osis_id": "Rom.8.28",
      "offset": 0
    },
    {
      "verse_id": 45008029,
      "verse_index": 28146,
      "reference": "Romans 8:29",
      "osis_id": "Rom.8.29",
      "offset": 1
    },
    {
      "verse_id": 45008030,
      "verse_index": 28147,
      "reference": "Romans 8:30",
      "osis_id": "Rom.8.30",
      "offset": 2
    }
  ]
}

Canonical Lookup (Verse Coordinate Resolution)

The /lookup endpoint resolves canonical verse coordinates back into structured Scripture references. It converts verse IDs or global verse indexes into human-readable references and canonical OSIS identifiers.

This endpoint is useful for systems that store or exchange canonical verse coordinates internally and later need to reconstruct the corresponding Scripture reference for display, indexing, or downstream retrieval.

Lookup Request

curl --get https://holybible.dev/api/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "verse_id=45008001,45008002,45008003"

Lookup Response

{
  "status": "success",
  "results_count": 3,
  "data": [
    {
      "verse_id": 45008001,
      "verse_index": 28118,
      "book": {
        "id": 45,
        "name": "Romans"
      },
      "chapter": 8,
      "verse": 1,
      "reference": "Romans 8:1",
      "osis_id": "Rom.8.1"
    },
    {
      "verse_id": 45008002,
      "verse_index": 28119,
      "book": {
        "id": 45,
        "name": "Romans"
      },
      "chapter": 8,
      "verse": 2,
      "reference": "Romans 8:2",
      "osis_id": "Rom.8.2"
    },
    {
      "verse_id": 45008003,
      "verse_index": 28120,
      "book": {
        "id": 45,
        "name": "Romans"
      },
      "chapter": 8,
      "verse": 3,
      "reference": "Romans 8:3",
      "osis_id": "Rom.8.3"
    }
  ]
}

Verse of the Day

The Verse of the Day endpoint delivers a curated Scripture passage that refreshes automatically each day. Every user receives the same daily verse, ensuring consistency across applications and devices.

curl https://holybible.dev/api/votd \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "reference": "Ephesians 6:10",
  "text": "Finally, my brethren, be strong in the Lord, and in the power of his might.",
  "translation": "KJV",
  "permissions": "King James Version - Public Domain."
}

The daily verse is identical for all authenticated users and automatically cycles across the curated verse set throughout the calendar year.

For production details, reset timing (00:00 UTC), caching strategy, and usage guidance, see the Free Verse of the Day API overview.

Full-Text Search

BibleBridge supports full-text Scripture search using MySQL boolean mode. Searches are performed against the selected translation only.

Search Request

curl --get https://holybible.dev/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "search=love" \
  --data version=KJV

Search Response

{
  "status": "success",
  "type": "search",
  "version": "KJV",
  "query": "love",
  "results_count": 25,
  "page": 1,
  "limit": 25,
  "data": [
    {
      "book": {
        "id": 43,
        "name": "John"
      },
      "chapter": 13,
      "verse": 34,
      "text": "A new commandment I give unto you, That ye love one another; as I have loved you, that ye also love one another."
    }
  ]
}

Search results are returned in relevance order. Pagination limits and availability may vary by plan level.

Full-Text Search Parameters

Exact Phrase

curl --get https://holybible.dev/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "search=love one another" \
  --data version=KJV

Required and Excluded Terms

curl --get https://holybible.dev/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "search=+love -world" \
  --data version=KJV

Multiple Words (Implicit OR)

curl --get https://holybible.dev/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "search=faith hope love" \
  --data version=KJV

Batch Retrieval (Bulk Scripture Requests)

BibleBridge supports structured batch retrieval, allowing multiple canonical Scripture references to be retrieved in a single atomic request.

The batch endpoint is designed for production systems requiring deterministic ordering, reduced network overhead, and schema-stable multi-reference retrieval.

Endpoint

POST https://holybible.dev/api/batch

The batch endpoint accepts JSON POST requests only. Query parameters are not supported for batch retrieval.

Required Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Batch Requests

curl -X POST https://holybible.dev/api/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "KJV",
    "references": [
      {
        "book_id": 19,
        "chapter": 23,
        "range": "1-6"
      },
      {
        "book_id": 45,
        "chapter": 8,
        "verse": 28
      }
    ]
  }'

Batch response

{
  "status": "success",
  "type": "batch",
  "version": "KJV",
  "requested_references": 2,
  "results_count": 7,
  "data": [
    {
      "request": {
        "book_id": 19,
        "chapter": 23,
        "range": "1-6"
      },
      "verses": [
        { "verse": 1, "text": "A Psalm of David. The LORD is my shepherd; I shall not want." },
        { "verse": 2, "text": "He maketh me to lie down in green pastures: he leadeth me beside the still waters." },
        { "verse": 3, "text": "He restoreth my soul: he leadeth me in the paths of righteousness for his name's sake." },
        { "verse": 4, "text": "Yea, though I walk through the valley of the shadow of death, I will fear no evil: for thou art with me; thy rod and thy staff they comfort me." },
        { "verse": 5, "text": "Thou preparest a table before me in the presence of mine enemies: thou anointest my head with oil; my cup runneth over." },
        { "verse": 6, "text": "Surely goodness and mercy shall follow me all the days of my life: and I will dwell in the house of the LORD for ever." }
      ]
    },
    {
      "request": {
        "book_id": 45,
        "chapter": 8,
        "verse": 28
      },
      "verses": [
        {
          "verse": 28,
          "text": "And we know that all things work together for good to them that love God, to them who are the called according to his purpose."
        }
      ]
    }
  ]
}

Batch Guarantees

• Atomic processing: If any reference fails validation, the entire request fails.
• Deterministic ordering: Results are returned in the same order as requested.
• Single-version consistency: All references share the same version.
• Quota accounting: A batch request counts as a single API request.

Batch Limits by Plan

Standard range limits and rate limits apply according to plan level.

Reference Difference (Canonical Span Comparison)

The /diff endpoint compares two Scripture references and returns their canonical overlap and differences. Both references are first normalized using the BibleBridge Reference Integrity Engine, allowing the endpoint to safely compare flexible human-written inputs.

This endpoint operates purely on canonical verse coordinates and does not require a Bible version. It is useful for identifying overlapping passages, deduplicating references, or comparing Scripture ranges in structured applications and AI pipelines.

Difference Request

curl --get https://holybible.dev/api/diff \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode a="rom 8:1-10" \
  --data-urlencode b="rom 8:5-15"

Difference Response

{
  "status": "success",
  "a": "Rom.8.1-Rom.8.10",
  "b": "Rom.8.5-Rom.8.15",
  "overlap": true,
  "intersection": {
    "osis_id": "Rom.8.5-Rom.8.10",
    "verse_count": 6
  },
  "only_in_a": {
    "osis_id": "Rom.8.1-Rom.8.4",
    "verse_count": 4
  },
  "only_in_b": {
    "osis_id": "Rom.8.11-Rom.8.15",
    "verse_count": 5
  }
}

Because both inputs are normalized before comparison, the endpoint can safely evaluate messy references such as abbreviations, punctuation variants, or compound references without requiring client-side parsing.

Reference Range (Canonical Span Construction)

The /range endpoint constructs a canonical Scripture span between two references. Both inputs are normalized using the BibleBridge Reference Integrity Engine and converted into canonical verse coordinates before the span is calculated.

This endpoint operates on canonical verse indexes, allowing ranges to span chapters or even cross book boundaries without requiring client-side logic. Because the operation is version-agnostic, no Bible translation is required.

Range Request

curl --get https://holybible.dev/api/range \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode a="john 3:16" \
  --data-urlencode b="john 3:18"

Range Response

{
  "status": "success",
  "start": "John.3.16",
  "end": "John.3.18",
  "osis_id": "John.3.16-John.3.18",
  "start_index": 26137,
  "end_index": 26139,
  "verse_count": 3
}

Because the span is calculated using the canonical verse index, ranges can cross chapters or books while remaining structurally valid. For example, the range between Mal 4:6 and Matt 1:1 spans the Old and New Testament boundary.

Verse Distance (Canonical Position Measurement)

The /distance endpoint measures the canonical distance between two Scripture references. Both inputs are normalized using the BibleBridge Reference Integrity Engine and converted into canonical verse coordinates before the distance is calculated.

Distance is computed using the global canonical verse index, which represents the sequential position of every verse in the Bible (1 through 31,102). This allows the API to measure distance across chapters and books without requiring client-side boundary logic.

Distance Request

curl --get https://holybible.dev/api/distance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode a="john 3:16" \
  --data-urlencode b="rom 8:1"

Distance Response

{
  "status": "success",
  "a": "John.3.16",
  "b": "Rom.8.1",
  "distance": 1981
}

Because the distance calculation is based on the global canonical verse index, the endpoint works across chapters, books, and Testament boundaries while remaining deterministic and version-agnostic.

Verse Slice (Canonical Index Traversal)

The /slice endpoint retrieves a contiguous span of Scripture using canonical verse indexes. Unlike reference-based endpoints, slice operates directly on the global verse index, allowing applications to traverse Scripture deterministically without needing to resolve human-readable references first.

Every verse in the Bible has a unique canonical index from 1 through 31,102. By specifying a starting and ending index, applications can retrieve any segment of Scripture across chapters or books using a single request.

Index 15551 is the canonical midpoint of the Bible — Psalm 103:1.

Slice Request

curl --get https://holybible.dev/api/slice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data start_index=15551 \
  --data end_index=15551

Slice Response

{
    "status": "success",
    "osis_id": "Psalm.103.1",
    "start_index": 15551,
    "end_index": 15551,
    "verse_count": 1,
    "data": [
        {
            "verse_id": 19103001,
            "verse_index": 15551,
            "book": {
                "id": 19,
                "name": "Psalm"
            },
            "chapter": 103,
            "verse": 1
        }
    ]
}

Because slice operates on the canonical verse index, it allows applications to traverse Scripture deterministically across chapter and book boundaries without client-side logic.

For example, requesting indexes 1 through 31102 returns the entire canonical Bible structure in order.

Licensing & Compliance

BibleBridge serves exclusively public-domain Scripture texts with no downstream licensing or attribution requirements.

• No attribution required
• No link-back requirements
• Permitted for commercial, institutional, and ministry use
• Version identifiers are technical selectors only and do not impose licensing obligations

View legal & provenance documentation

Book ID Reference

Supported Bible Versions

* DRA follows the Latin Vulgate tradition (LXX Psalm numbering).
* RST follows the Septuagint (LXX Psalm numbering).

All other versions follow the Masoretic Text (MT) tradition.

For details specific to the King James Version (KJV), see the KJV Bible API page.

Examples

The following examples demonstrate how BibleBridge retrieves Scripture, processes flexible references using the Reference Integrity Engine, and powers AI-assisted systems and production-grade Scripture applications.

• Scripture Retrieval
• Reference Integrity Engine
• Architecture
• AI Integration

API Stability Guarantees

BibleBridge is designed for long-lived production systems that depend on stable canonical Scripture identifiers and predictable API behavior.

• Stable canonical coordinates: Book IDs, chapter numbers, and verse identifiers are immutable across versions and translations.
• No silent breaking changes: Existing response fields and structures are never removed or changed without versioning.
• Backward compatibility: New features are introduced as additive fields or parameters whenever possible.
• Deterministic reference resolution: Identical inputs always produce identical canonical coordinates.
• Schema stability: JSON response structures remain stable across API updates.

Applications can safely build persistent data structures and caches using canonical identifiers returned by the API.

Error Responses

All errors are returned as JSON with an appropriate HTTP status code. Error responses are explicit and never return partial data.

At minimum, an error response includes a status field and a human-readable message. Some errors also include a machine-readable error code and an optional upgrade_url.

Missing API Key (401)

{
  "status": "error",
  "message": "API key required."
}

Invalid Parameter Combination (400)

The verse and range parameters are mutually exclusive.

{
  "status": "error",
  "message": "Cannot use verse and range together."
}

Verse Limit Exceeded (403)

{
  "status": "error",
  "error": "verse_limit_exceeded",
  "message": "Request exceeds plan limit of 200 verse units."
}

Comparison Restricted to Production Tier (403)

{
  "status": "error",
  "error": "compare_restricted",
  "message": "Cross-version comparison is available on Production + Enterprise plans.",
  "upgrade_url": "https://holybible.dev/signup"
}