openapi: 3.0.3
info:
  title: BibleBridge API
  version: "1.3.0"
  description: > 
    Production-grade stateless JSON REST Bible API for deterministic canonical Scripture
    coordinate validation and retrieval. The /api/resolve endpoint enforces
    reference integrity by converting flexible human-readable Scripture strings
    into validated immutable canonical book IDs (1-66), chapter and verse spans,
    and OSIS identifiers before retrieval occurs. Supports structured Scripture
    retrieval, cross-translation alignment, full-text search, atomic batch
    operations, and a globally consistent Verse of the Day endpoint.

servers:
  - url: https://holybible.dev
    description: Production

security:
  - BearerAuth: []

tags:
  - name: Resolve
    description: Deterministic canonical reference validation and normalization
  - name: Scripture
    description: Structured Scripture retrieval
  - name: Search
    description: Full-text search
  - name: Batch
    description: Batch retrieval operations
  - name: VOTD
    description: Verse of the Day

paths:
  /api/resolve:
    get:
      tags: [Resolve]
      summary: Validate and normalize a flexible Bible reference string into canonical coordinates
      description: >
        Accepts flexible human-readable Scripture input (e.g., "2 sam 1:19-25",
        "rom 8:1-4, 28; 12:1-2") and returns canon-validated immutable book identifiers
        (1-66), chapter and verse spans, OSIS identifiers, and confidence scoring.
        Deterministically enforces authoritative canonical boundaries prior to retrieval
        and surfaces malformed or ambiguous input without heuristic guessing.
      parameters:
        - name: reference
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Successful resolution
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ResolveSingleResponse"
                  - $ref: "#/components/schemas/ResolveCollectionResponse"
              examples:
                single:
                  summary: Single Reference (1 Thessalonians 4:16)
                  value:
                    type: "single"
                    valid: true
                    input: "1 thess 4 16"
                    book: 
                      key: "1TH"
                      book_id: 52
                      name: "1 Thessalonians"
                      slug: "1-thessalonians"
                    spans:
                      - start: { chapter: 4, verse: 16 }
                        end: { chapter: 4, verse: 16 }
                    osis_id: "1Thess.4.16"
                    confidence: 0.9465
                collection:
                  summary: Collection Example (Romans 8 & 12)
                  value:
                    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

  /api/scripture:
    get:
      tags: [Scripture]
      summary: Retrieve Scripture content
      parameters:
        - name: book_id
          in: query
          required: true
          schema: { type: integer, minimum: 1, maximum: 66 }
        - name: chapter
          in: query
          required: true
          schema: { type: integer, minimum: 1 }
        - name: verse
          in: query
          required: false
          schema: { type: integer }
        - name: range
          in: query
          required: false
          schema: { type: string }
        - name: endChapter
          in: query
          required: false
          schema: { type: integer }
        - name: endVerse
          in: query
          required: false
          schema: { type: integer }
        - name: version
          in: query
          required: true
          schema: { $ref: "#/components/schemas/BibleVersion" }
        - name: compare
          in: query
          required: false
          schema: { $ref: "#/components/schemas/BibleVersion" }
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/SingleVerseResponse"
                  - $ref: "#/components/schemas/VerseRangeResponse"
                  - $ref: "#/components/schemas/ChapterResponse"
                  - $ref: "#/components/schemas/SpanResponse"
                  - $ref: "#/components/schemas/ComparisonRangeResponse"
              examples:
                single_verse:
                  summary: Single Verse Example
                  value:
                    status: "success"
                    type: "single_verse"
                    version: "KJV"
                    book: { id: 19, name: "Psalm" }
                    chapter: 23
                    results_count: 1
                    data: { verse: 1, text: "A Psalm of David. The LORD is my shepherd; I shall not want." }
                verse_range:
                  summary: Verse Range Example (Psalm 23:1-6)
                  value:
                    status: "success"
                    type: "verse_range"
                    version: "KJV"
                    book: { id: 19, name: "Psalm" }
                    chapter: 23
                    range: "1-6"
                    results_count: 6
                    data:
                      - { 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." }
                full_chapter:
                  summary: Full Chapter Example (Psalm 23)
                  value:
                    status: "success"
                    type: "full_chapter"
                    version: "KJV"
                    book: { id: 19, name: "Psalm" }
                    chapter: 23
                    results_count: 6
                    data:
                      - { 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." }
                cross_chapter:
                  summary: Cross Chapter (Genesis 1:1 - 2:3)
                  value:
                    status: "success"
                    type: "passage_span"
                    version: "KJV"
                    book: { id: 1, name: "Genesis" }
                    span: "1:1-2:3"
                    results_count: 34
                    data:
                      - { chapter: 1, verse: 1, text: "In the beginning God created the heaven and the earth." }
                      - { chapter: 1, verse: 2, text: "And the earth was without form, and void; and darkness was upon the face of the deep. And the Spirit of God moved upon the face of the waters." }
                      - { chapter: 1, verse: 3, text: "And God said, Let there be light: and there was light." }
                      - { chapter: 1, verse: 4, text: "And God saw the light, that it was good: and God divided the light from the darkness." }
                      - { chapter: 1, verse: 5, text: "And God called the light Day, and the darkness he called Night. And the evening and the morning were the first day." }
                      - { chapter: 1, verse: 6, text: "And God said, Let there be a firmament in the midst of the waters, and let it divide the waters from the waters." }
                      - { chapter: 1, verse: 7, text: "And God made the firmament, and divided the waters which were under the firmament from the waters which were above the firmament: and it was so." }
                      - { chapter: 1, verse: 8, text: "And God called the firmament Heaven. And the evening and the morning were the second day." }
                      - { chapter: 1, verse: 9, text: "And God said, Let the waters under the heaven be gathered together unto one place, and let the dry land appear: and it was so." }
                      - { chapter: 1, verse: 10, text: "And God called the dry land Earth; and the gathering together of the waters called he Seas: and God saw that it was good." }
                      - { chapter: 1, verse: 11, text: "And God said, Let the earth bring forth grass, the herb yielding seed, and the fruit tree yielding fruit after his kind, whose seed is in itself, upon the earth: and it was so." }
                      - { chapter: 1, verse: 12, text: "And the earth brought forth grass, and herb yielding seed after his kind, and the tree yielding fruit, whose seed was in itself, after his kind: and God saw that it was good." }
                      - { chapter: 1, verse: 13, text: "And the evening and the morning were the third day." }
                      - { chapter: 1, verse: 14, text: "And God said, Let there be lights in the firmament of the heaven to divide the day from the night; and let them be for signs, and for seasons, and for days, and years:" }
                      - { chapter: 1, verse: 15, text: "And let them be for lights in the firmament of the heaven to give light upon the earth: and it was so." }
                      - { chapter: 1, verse: 16, text: "And God made two great lights; the greater light to rule the day, and the lesser light to rule the night: he made the stars also." }
                      - { chapter: 1, verse: 17, text: "And God set them in the firmament of the heaven to give light upon the earth," }
                      - { chapter: 1, verse: 18, text: "And to rule over the day and over the night, and to divide the light from the darkness: and God saw that it was good." }
                      - { chapter: 1, verse: 19, text: "And the evening and the morning were the fourth day." }
                      - { chapter: 1, verse: 20, text: "And God said, Let the waters bring forth abundantly the moving creature that hath life, and fowl that may fly above the earth in the open firmament of heaven." }
                      - { chapter: 1, verse: 21, text: "And God created great whales, and every living creature that moveth, which the waters brought forth abundantly, after their kind, and every winged fowl after his kind: and God saw that it was good." }
                      - { chapter: 1, verse: 22, text: "And God blessed them, saying, Be fruitful, and multiply, and fill the waters in the seas, and let fowl multiply in the earth." }
                      - { chapter: 1, verse: 23, text: "And the evening and the morning were the fifth day." }
                      - { chapter: 1, verse: 24, text: "And God said, Let the earth bring forth the living creature after his kind, cattle, and creeping thing, and beast of the earth after his kind: and it was so." }
                      - { chapter: 1, verse: 25, text: "And God made the beast of the earth after his kind, and cattle after their kind, and every thing that creepeth upon the earth after his kind: and God saw that it was good." }
                      - { chapter: 1, verse: 26, text: "And God said, Let us make man in our image, after our likeness: and let them have dominion over the fish of the sea, and over the fowl of the air, and over the cattle, and over all the earth, and over every creeping thing that creepeth upon the earth." }
                      - { chapter: 1, verse: 27, text: "So God created man in his own image, in the image of God created he him; male and female created he them." }
                      - { chapter: 1, verse: 28, text: "And God blessed them, and God said unto them, Be fruitful, and multiply, and replenish the earth, and subdue it: and have dominion over the fish of the sea, and over the fowl of the air, and over every living thing that moveth upon the earth." }
                      - { chapter: 1, verse: 29, text: "And God said, Behold, I have given you every herb bearing seed, which is upon the face of all the earth, and every tree, in the which is the fruit of a tree yielding seed; to you it shall be for meat." }
                      - { chapter: 1, verse: 30, text: "And to every beast of the earth, and to every fowl of the air, and to every thing that creepeth upon the earth, wherein there is life, I have given every green herb for meat: and it was so." }
                      - { chapter: 1, verse: 31, text: "And God saw every thing that he had made, and, behold, it was very good. And the evening and the morning were the sixth day." }
                      - { chapter: 2, verse: 1, text: "Thus the heavens and the earth were finished, and all the host of them." }
                      - { chapter: 2, verse: 2, text: "And on the seventh day God ended his work which he had made; and he rested on the seventh day from all his work which he had made." }
                      - { chapter: 2, verse: 3, text: "And God blessed the seventh day, and sanctified it: because that in it he had rested from all his work which God created and made." }
                comparison:
                  summary: Translation Comparison (Psalm 23:1-3)
                  value:
                    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."

  /api/search:
    get:
      tags: [Search]
      summary: Search Scripture text
      parameters:
        - name: search
          in: query
          required: true
          schema: { type: string }
        - name: version
          in: query
          required: true
          schema: { $ref: "#/components/schemas/BibleVersion" }
      responses:
        "200":
          description: Successful search
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SearchResponse" }
              examples:
                search_result:
                  summary: Basic search query ("Jesus wept")
                  value:
                    status: "success"
                    type: "search"
                    version: "KJV"
                    query: "Jesus wept"
                    results_count: 1
                    data:
                      - chapter: 11
                        verse: 35
                        text: "Jesus wept."

  /api/batch:
    post:
      tags: [Batch]
      summary: Batch Scripture retrieval
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BatchRequest" }
            examples:
              multi_ref:
                summary: Batch Psalm 23 and Romans 8
                value:
                  version: "KJV"
                  references:
                    - { book_id: 19, chapter: 23, range: "1-6" }
                    - { book_id: 45, chapter: 8, verse: 28 }
      responses:
        "200":
          description: Successful batch response
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BatchResponse" }
              examples:
                batch_success:
                  summary: Batch Response Example
                  value:
                    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.", chapter: 23 }
                          - { verse: 2, text: "He maketh me to lie down in green pastures: he leadeth me beside the still waters.", chapter: 23 }
                          - { verse: 3, text: "He restoreth my soul: he leadeth me in the paths of righteousness for his name's sake.", chapter: 23 }
                          - { 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.", chapter: 23 }
                          - { 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.", chapter: 23 }
                          - { 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.", chapter: 23 }
                      - 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.", chapter: 8 }

  /api/votd:
    get:
      tags: [VOTD]
      summary: Get Verse of the Day
      responses:
        "200":
          description: Successful VOTD response
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VotdResponse" }
              examples:
                daily:
                  summary: Ephesians 6:10
                  value:
                    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."

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

  schemas:
    BibleVersion:
      type: string
      enum: [KJV, ASV, WEB, DRA, LSG, RVR, LUT, RST, CUV, ARA]

    VotdResponse:
      type: object
      properties:
        reference: { type: string }
        text: { type: string }
        translation: { type: string }
        permissions: { type: string }

    ResolveBook:
      type: object
      properties:
        key: { type: string }
        book_id: { type: integer }
        name: { type: string }
        slug: { type: string }

    ResolveSingleResponse:
      type: object
      properties:
        type: { type: string, enum: [single] }
        valid: { type: boolean }
        input: { type: string }
        book: { $ref: "#/components/schemas/ResolveBook" }
        spans:
          type: array
          items:
            type: object
            properties:
              start: { type: object, properties: { chapter: { type: integer }, verse: { type: integer } } }
              end: { type: object, properties: { chapter: { type: integer }, verse: { type: integer } } }
        osis_id: { type: string }
        confidence: { type: number }

    ResolveCollectionResponse:
      type: object
      properties:
        type: { type: string, enum: [collection] }
        valid: { type: boolean }
        input: { type: string }
        osis_id: { type: string }
        references: { type: array, items: { $ref: "#/components/schemas/ResolveSingleResponse" } }

    ScriptureBook:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }

    ScriptureVerse:
      type: object
      properties:
        verse: { type: integer }
        text: { type: string }
        chapter: { type: integer }

    SingleVerseResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [single_verse] }
        version: { $ref: "#/components/schemas/BibleVersion" }
        book: { $ref: "#/components/schemas/ScriptureBook" }
        chapter: { type: integer }
        results_count: { type: integer }
        data: { $ref: "#/components/schemas/ScriptureVerse" }

    VerseRangeResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [verse_range] }
        version: { $ref: "#/components/schemas/BibleVersion" }
        book: { $ref: "#/components/schemas/ScriptureBook" }
        chapter: { type: integer }
        range: { type: string }
        results_count: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/ScriptureVerse" } }

    ChapterResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [full_chapter] }
        version: { $ref: "#/components/schemas/BibleVersion" }
        book: { $ref: "#/components/schemas/ScriptureBook" }
        chapter: { type: integer }
        results_count: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/ScriptureVerse" } }

    SpanResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [passage_span] }
        version: { $ref: "#/components/schemas/BibleVersion" }
        book: { $ref: "#/components/schemas/ScriptureBook" }
        span: { type: string }
        results_count: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/ScriptureVerse" } }

    ComparisonRangeResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [comparison_range] }
        primary_version: { $ref: "#/components/schemas/BibleVersion" }
        compare_version: { $ref: "#/components/schemas/BibleVersion" }
        book: { $ref: "#/components/schemas/ScriptureBook" }
        chapter: { type: integer }
        range: { type: string }
        results_count: { type: integer }
        data: { type: array, items: { type: object, additionalProperties: { type: string } } }

    SearchResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [search] }
        version: { $ref: "#/components/schemas/BibleVersion" }
        query: { type: string }
        results_count: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/ScriptureVerse" } }

    BatchRequest:
      type: object
      required: [version, references]
      properties:
        version: { $ref: "#/components/schemas/BibleVersion" }
        references:
          type: array
          items:
            type: object
            required: [book_id, chapter]
            properties:
              book_id: { type: integer }
              chapter: { type: integer }
              verse: { type: integer }
              range: { type: string }

    BatchResponse:
      type: object
      properties:
        status: { type: string }
        type: { type: string, enum: [batch] }
        version: { $ref: "#/components/schemas/BibleVersion" }
        requested_references: { type: integer }
        results_count: { type: integer }
        data:
          type: array
          items:
            type: object
            properties:
              request: { type: object }
              verses: { type: array, items: { $ref: "#/components/schemas/ScriptureVerse" } }