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

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

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=23"

View live sandbox response

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

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

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.

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

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
    }
  ]
}

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.

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 Deterministic Reference Integrity Engine interprets flexible human-written input, expands it into canonical spans, 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 ref="rom8:1-4" \
  --data version=KJV

Passage Response

{
  "status": "success",
  "type": "verse_range",
  "version": "KJV",
  "book": {
    "id": 45,
    "name": "Romans"
  },
  "chapter": 8,
  "range": "1-4",
  "results_count": 4,
  "data": [
    {
      "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."
    },
    {
      "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."
    },
    {
      "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:"
    },
    {
      "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.

Base URL

Authentication

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

Authorization: Bearer YOUR_API_KEY

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

Legacy Authentication (Deprecated)

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

Quick Start

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.

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."
    }
  ]
}

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

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

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
      }
    ]
  }'

{
  "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."
        }
      ]
    }
  ]
}

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

{
  "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."
    }
  ]
}

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

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

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

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

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

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

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