{"openapi":"3.0.3","info":{"title":"Logos77 Scripture API","description":"The Logos77 Scripture API serves the Word of God in 12 Bible translations across 13 language subdomains. It is a free, non-commercial, read-only API. Every response includes a deep link back to the Logos77 reader.\n\nBase URL: https://www.logos77.com/api\n\nNo authentication is required. Responses are cached at the edge; scripture does not change.","version":"1.0.0","termsOfService":"https://www.logos77.com/privacy-policy.html","contact":{"name":"Logos77","url":"https://www.logos77.com"},"license":{"name":"Scripture is public domain; API usage is free and non-commercial"}},"servers":[{"url":"https://www.logos77.com/api","description":"Production (English/KJV)"},{"url":"https://logos77.com/api","description":"Production apex (redirects to www)"}],"tags":[{"name":"Passage","description":"Look up a verse, range, or full chapter"},{"name":"Verse of the Day","description":"Deterministic daily verse"},{"name":"Random","description":"Random verse"},{"name":"Search","description":"Full-text search within a translation"},{"name":"Through","description":"Read continuously through a translation"},{"name":"Books","description":"List the book names of a translation"},{"name":"Languages","description":"List the available translations and their script properties"},{"name":"Groups","description":"Additive reading-plan groups across the canon (the Law, the Gospels, Paul's Letters, …)"}],"paths":{"/passage":{"get":{"tags":["Passage"],"summary":"Look up a verse, verse range, or full chapter","operationId":"getPassage","parameters":[{"$ref":"#/components/parameters/Lang"},{"name":"book","in":"query","required":true,"description":"Book name in the translation's native language (e.g. 'John' for KJV, 'Jean' for Martin, 'Johannes' for Luther).","schema":{"type":"string"},"example":"John"},{"name":"chapter","in":"query","required":true,"description":"Chapter number (1-based).","schema":{"type":"integer","minimum":1},"example":3},{"name":"verse","in":"query","description":"Verse or verse range. Omit to return the full chapter.","schema":{"type":"string","pattern":"^\\d+(-\\d+)?$","example":"16"}}],"responses":{"200":{"description":"Passage found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Passage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/votd":{"get":{"tags":["Verse of the Day"],"summary":"Deterministic verse of the day","description":"Returns the same verse for everyone, every day, globally. The verse advances by one per day using day-of-year modulo total-verses.","operationId":"getVotd","parameters":[{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"Verse of the day","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verse"}}}}}}},"/random":{"get":{"tags":["Random"],"summary":"Random verse","description":"Returns a random verse. Not cached (a new verse each request).","operationId":"getRandom","parameters":[{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"Random verse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verse"}}}}}}},"/search":{"get":{"tags":["Search"],"summary":"Full-text search within a translation","operationId":"searchScripture","description":"Case-insensitive substring search over verse text. Results are cached for 1 day.","parameters":[{"$ref":"#/components/parameters/Lang"},{"name":"q","in":"query","required":true,"description":"Search query text.","schema":{"type":"string"},"example":"love"},{"name":"limit","in":"query","description":"Maximum number of results (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/through":{"get":{"tags":["Through"],"summary":"Read continuously through a translation","description":"Read scripture in canonical order from \"from\" to \"to\", slicing large ranges automatically. Alternatively pass \"group\" (a group tag, label or alias — e.g. 'OT_LAW', 'Torah', 'Pauline Epistles') to read one canonical reading-plan group; group is mutually exclusive with from/from_after/to and only continuous groups are readable this way (see GET /api/groups). The canon is a loop: when from comes after to, reading continues through the end of the Bible back to Genesis (e.g. from \"Psalms 150\" to \"Psalms 1\"). \"from\" and \"to\" are whole-Bible 0-based integers or native references (book, \"Book Ch\", or \"Book Ch:V\"). Responds with next/prev integer cursors and self-contained next_url/prev_url; follow next_url (same to) to continue. A whole Bible is exactly 8 requests in every translation.","operationId":"readThrough","parameters":[{"$ref":"#/components/parameters/Lang"},{"name":"group","in":"query","description":"Read one continuous canonical group instead of a manual range: a group tag, label or alias (e.g. 'OT_LAW', 'Torah', 'Pauline Epistles'). Mutually exclusive with 'from', 'from_after' and 'to'. Non-continuous groups return an error — list them with GET /api/groups.","schema":{"type":"string"},"example":"Torah"},{"name":"from","in":"query","description":"Start bound: whole-Bible 0-based index (bare integer) or native reference (book, 'Book Ch', or 'Book Ch:V'). May come after 'to' to read through the end of the Bible back to Genesis. Omit to start at the first verse (Genesis 1:1).","schema":{"type":"string","default":"0 (first verse)"},"example":"Psalms 150"},{"name":"from_after","in":"query","description":"Resume strictly after a reference (or index) instead of starting at it — e.g. 'John 3:16'. Survives data revisions that shift integer indexes; overrides 'from'.","schema":{"type":"string"},"example":"John 3:16"},{"name":"to","in":"query","description":"End bound, same forms as 'from', or 'end'. Defaults to 'end' (last verse).","schema":{"type":"string","default":"end"},"example":"Psalms 1"},{"name":"limit","in":"query","description":"Maximum verses per slice (1-4096). Omit to return as much of the range as fits the slice caps at once.","schema":{"type":"integer","minimum":1,"maximum":4096}}],"responses":{"200":{"description":"Slice of the requested range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThroughResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/books":{"get":{"tags":["Books"],"summary":"List the books of a translation","description":"List the 66 books in canonical order for a translation, with their native names and chapter counts, plus the translation's script metadata (direction, bytes per glyph, combining, sample). Native book names are the vocabulary accepted by 'book' (/passage) and 'from'/'to' (/through), so this is how callers discover the correct referencing for any language.","operationId":"listBooks","parameters":[{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"Book list for the translation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BooksResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/languages":{"get":{"tags":["Languages"],"summary":"List the available translations and their script properties","description":"List every translation with its label, subdomain, and script metadata: writing direction (rtl/ltr), maximum UTF-8 bytes per code point, whether the script uses combining marks, and a sample verse for font/decoder verification. Lets any client — especially embedded or small-display devices — discover languages and adapt rendering before fetching text. Responses are always UTF-8 JSON.","operationId":"listLanguages","responses":{"200":{"description":"Language registry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguagesResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/groups":{"get":{"tags":["Groups"],"summary":"List canonical book groupings for reading plans","description":"List the traditional, overlapping book groupings (the Law, History, Wisdom, Major/Minor Prophets, Gospels, Paul's Letters, General Letters, Revelation, cross-cutting groups and traditional subsets) with per-translation native book names, inclusive whole-book index ranges, chapter/verse totals, contiguity, and a resolvable start/end span. Groups are non-exclusive — the same book may appear in several. Every continuous group's tag/label/aliases are accepted by GET /api/through?group=. Non-contiguous groups report contiguous=false and must be read book by book. Ranges are inclusive 0-based indexes into the canonical 66-book order; the response is additive to /api/books, not a replacement for it.","operationId":"listGroups","parameters":[{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"Group listings for the translation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupsResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"parameters":{"Lang":{"name":"lang","in":"query","required":false,"description":"Language code. Defaults to 'en' (English/KJV). Accepts the language code, the verse-data name, or a full subdomain.","schema":{"type":"string","enum":["en","en-gb","de","fr","es","ru","zh-hant","zh-hans","my","ar","ta"],"default":"en"}}},"schemas":{"VerseItem":{"type":"object","properties":{"verse":{"type":"integer","description":"1-based verse number"},"text":{"type":"string","description":"Verse text"}}},"Verse":{"type":"object","properties":{"reference":{"type":"string","example":"John 3:16","description":"Native book name, chapter and verse"},"lang":{"type":"string","example":"en"},"lang_label":{"type":"string","example":"English (KJV)"},"verses":{"type":"array","items":{"$ref":"#/components/schemas/VerseItem"}},"deep_link":{"type":"string","format":"uri","example":"https://logos77.com/#John-3-16","description":"Link back to the Logos77 reader"}}},"Passage":{"type":"object","allOf":[{"$ref":"#/components/schemas/Verse"},{"type":"object","properties":{"book":{"type":"string"},"chapter":{"type":"integer"},"total_verses_in_chapter":{"type":"integer"}}}]},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"lang":{"type":"string"},"lang_label":{"type":"string"},"count":{"type":"integer"},"limit":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string"},"verse":{"type":"integer"},"text":{"type":"string"},"deep_link":{"type":"string","format":"uri"}}}}}},"ThroughVerse":{"type":"object","properties":{"index":{"type":"integer","description":"Whole-Bible 0-based cursor index"},"reference":{"type":"string","example":"Psalm 150:1","description":"Native book name, chapter and verse"},"book":{"type":"string","example":"Psalm"},"chapter":{"type":"integer","example":150},"verse":{"type":"integer","example":1},"text":{"type":"string","description":"Verse text"},"deep_link":{"type":"string","format":"uri","example":"https://www.logos77.com/#Psalm-150-1"}}},"ThroughResult":{"type":"object","properties":{"lang":{"type":"string","example":"en"},"lang_label":{"type":"string","example":"English (KJV)"},"total_verses":{"type":"integer","example":31102},"from_index":{"type":"integer","description":"First verse of this slice (and of the requested range on the first call)"},"to_index":{"type":"integer","description":"Last verse actually returned in this slice"},"range_to_index":{"type":"integer","description":"Resolved end of the requested loop segment (less than from_index when the range wraps)"},"range_length":{"type":"integer","description":"Total verses in the requested loop segment"},"count":{"type":"integer","description":"Verses returned in this slice"},"truncated":{"type":"boolean","description":"True when more of the range remains (see next)"},"next":{"type":"integer","nullable":true,"description":"Index of the next slice, or null when the range is complete"},"next_url":{"type":"string","format":"uri","nullable":true,"description":"Self-contained URL to fetch the next slice"},"prev":{"type":"integer","nullable":true,"description":"Index of the slice preceding from_index (always present in loop semantics)"},"prev_url":{"type":"string","format":"uri","nullable":true,"description":"Self-contained URL to fetch the preceding slice"},"verses":{"type":"array","items":{"$ref":"#/components/schemas/ThroughVerse"}}}},"BookInfo":{"type":"object","properties":{"name":{"type":"string","example":"Genesis","description":"Native book name as used by /passage and /through"},"chapters":{"type":"integer","example":50,"description":"Number of chapters in the book"}}},"BooksResult":{"type":"object","properties":{"lang":{"type":"string","example":"en"},"lang_label":{"type":"string","example":"English (KJV)"},"script":{"type":"string","example":"Latin"},"direction":{"type":"string","example":"ltr"},"glyph_bytes":{"type":"integer","example":3,"description":"Maximum UTF-8 bytes per code point"},"has_combining":{"type":"boolean","example":true,"description":"Whether the script uses combining marks"},"encoding":{"type":"string","example":"UTF-8"},"sample":{"type":"string","description":"A fixed first-verse sample for font/decoder verification"},"total_books":{"type":"integer","example":66},"books":{"type":"array","items":{"$ref":"#/components/schemas/BookInfo"}}}},"LanguageEntry":{"type":"object","properties":{"lang":{"type":"string","example":"ta"},"label":{"type":"string","example":"Tamil"},"host":{"type":"string","example":"ta.logos77.com"},"script":{"type":"string","example":"Tamil"},"direction":{"type":"string","example":"ltr"},"glyph_bytes":{"type":"integer","example":3},"has_combining":{"type":"boolean","example":true},"encoding":{"type":"string","example":"UTF-8"},"sample":{"type":"string"}}},"LanguagesResult":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/LanguageEntry"}}}},"Group":{"type":"object","properties":{"tag":{"type":"string","example":"OT_LAW","description":"Stable identifier accepted by /api/through?group="},"label":{"type":"string","example":"the Law","description":"Human-friendly label"},"aliases":{"type":"array","items":{"type":"string"},"example":["Torah","Pentateuch"],"description":"Alternate names and historic spellings, also accepted by /api/through?group="},"testament":{"type":"string","enum":["ot","nt","cross"],"description":"Broad canon region the group belongs to"},"contiguous":{"type":"boolean","description":"True when the group is one continuous canonical span that /api/through?group= can read in a single loop segment"},"ranges":{"type":"array","items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"integer"}},"description":"Inclusive [first,last] 0-based book-index ranges into the canonical 66-book order; one entry for contiguous groups, several for non-contiguous ones"},"book_count":{"type":"integer","example":5},"chapter_count":{"type":"integer","example":187},"verse_count":{"type":"integer","example":5852},"books":{"type":"array","items":{"type":"string"},"description":"Native book names in canonical order"},"start":{"type":"string","example":"Genesis 1:1","nullable":true,"description":"First reference of the group's overall span"},"end":{"type":"string","example":"Deuteronomy 34:12","nullable":true,"description":"Last reference of the group's overall span"},"scope":{"type":"string","description":"Historical or membership note, present only when the group's composition is qualified"}}},"GroupsResult":{"type":"object","properties":{"lang":{"type":"string","example":"en"},"lang_label":{"type":"string","example":"English (KJV)"},"total_books":{"type":"integer","example":66},"count":{"type":"integer","example":23},"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}}},"responses":{"BadRequest":{"description":"Missing or invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"NotFound":{"description":"No passage found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}