{"openapi":"3.0.2","info":{"title":"Bible API - Open Source","description":"\nAn open-source REST API for accessing the Holy Bible. It provides multiple translations, fast full-text search, verse-level retrieval, and cross-references.\n\nUse structured endpoints to explore translations, genres, books, chapters, and verses, or discover related passages.\n\nPublic usage is free; authenticate to obtain a token and include it with requests. Reauthenticate once the token expires.\n\nAn example application: <a title=\"Bible UI\" target=\"_blank\" href=\"https://bible-ui.rkeplin.com/book/kjv/1/1\">Bible UI</a>.\n\nIf you found this project useful and would like to make a donation, they are welcomed <a href=\"https://commerce.coinbase.com/checkout/4fe7dc66-e2c6-48d2-b00e-9e550e646d1c\" target=\"_blank\" rel=\"noopener noreferrer\">here</a>.\n","contact":{"name":"Rob Keplin","url":"https://www.rkeplin.com"},"version":"1.0.0"},"paths":{"/v2/auth":{"post":{"tags":["authorization"],"summary":"Auth","description":"Obtain an access token.\n\nRequest body:\n  - email (string, required): Your organization's contact email address.\n  - domain (string, required): Your organization or application domain.\n\nResponses:\n  - 200: { \"token\": string } — Access token to use in the X-Authorization header.\n  - 400: Invalid email or domain.\n\nNotes:\n  - Include the returned token in the X-Authorization header for subsequent requests.","operationId":"auth_v2_auth_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/translations":{"get":{"tags":["translations"],"summary":"Read Translations","description":"List all available Bible translations.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Array of Translation objects.\n  - 401: Unauthorized if the token is missing or invalid.","operationId":"read_translations_v2_translations_get","parameters":[{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Read Translations V2 Translations Get","type":"array","items":{"$ref":"#/components/schemas/Translation"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/translations/{translation_id}":{"get":{"tags":["translations"],"summary":"Read Translation","description":"Get details for a specific translation by ID.\n\nPath parameters:\n  - translation_id (integer): Identifier of the translation.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Translation object.\n  - 401: Unauthorized.\n  - 404: Translation not found.","operationId":"read_translation_v2_translations__translation_id__get","parameters":[{"required":true,"schema":{"title":"Id","type":"integer"},"name":"id","in":"query"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Translation"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/genres":{"get":{"tags":["genres"],"summary":"Read Genres","description":"List all Bible genres (e.g., Law, Prophets, Gospels).\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Array of Genre objects.\n  - 401: Unauthorized.","operationId":"read_genres_v2_genres_get","parameters":[{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Read Genres V2 Genres Get","type":"array","items":{"$ref":"#/components/schemas/Genre"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/genres/{id}":{"get":{"tags":["genres"],"summary":"Read Genre","description":"Get a single genre by ID.\n\nPath parameters:\n  - id (integer): Identifier of the genre.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Genre object.\n  - 401: Unauthorized.\n  - 404: Genre not found.","operationId":"read_genre_v2_genres__id__get","parameters":[{"required":true,"schema":{"title":"Id","type":"integer"},"name":"id","in":"path"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Genre"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/books":{"get":{"tags":["books"],"summary":"Read Books","description":"List all books of the Bible (metadata only).\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Array of Book objects.\n  - 401: Unauthorized.","operationId":"read_books_v2_books_get","parameters":[{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Read Books V2 Books Get","type":"array","items":{"$ref":"#/components/schemas/Book"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/books/{id}":{"get":{"tags":["books"],"summary":"Read Book","description":"Get a single book by ID.\n\nPath parameters:\n  - id (integer): Identifier of the book.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Book object.\n  - 401: Unauthorized.\n  - 404: Book not found.","operationId":"read_book_v2_books__id__get","parameters":[{"required":true,"schema":{"title":"Id","type":"integer"},"name":"id","in":"path"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Book"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/books/{book_id}/chapters":{"get":{"tags":["books"],"summary":"Read Book Chapters","description":"List chapters for a given book.\n\nPath parameters:\n  - book_id (integer): Identifier of the book.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Array of Chapter objects.\n  - 401: Unauthorized.","operationId":"read_book_chapters_v2_books__book_id__chapters_get","parameters":[{"required":true,"schema":{"title":"Book Id","type":"integer"},"name":"book_id","in":"path"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Read Book Chapters V2 Books  Book Id  Chapters Get","type":"array","items":{"$ref":"#/components/schemas/Chapter"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/books/{book_id}/chapters/{chapter_id}":{"get":{"tags":["books"],"summary":"Read Book Chapter","description":"Retrieve the full text of a chapter (returned verse-by-verse).\n\nPath parameters:\n  - book_id (integer): Identifier of the book.\n  - chapter_id (integer): Identifier of the chapter.\n\nQuery parameters:\n  - translation (string, optional): Limit the response to a specific translation code.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Array of ChapterVerse objects.\n  - 401: Unauthorized.\n  - 404: Chapter not found.","operationId":"read_book_chapter_v2_books__book_id__chapters__chapter_id__get","parameters":[{"required":true,"schema":{"title":"Book Id","type":"integer"},"name":"book_id","in":"path"},{"required":true,"schema":{"title":"Chapter Id","type":"integer"},"name":"chapter_id","in":"path"},{"required":false,"schema":{"title":"Translation","type":"string"},"name":"translation","in":"query"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Read Book Chapter V2 Books  Book Id  Chapters  Chapter Id  Get","type":"array","items":{"$ref":"#/components/schemas/ChapterVerse"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/books/{book_id}/chapters/{chapter_id}/{verse_id}":{"get":{"tags":["books"],"summary":"Read Verse","description":"Retrieve a single verse.\n\nPath parameters:\n  - book_id (integer): Identifier of the book.\n  - chapter_id (integer): Identifier of the chapter.\n  - verse_id (integer): Identifier of the verse (within the chapter).\n\nQuery parameters:\n  - translation (string, optional): Translation code to use for the verse text.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: ChapterVerse object.\n  - 401: Unauthorized.\n  - 404: Verse not found.","operationId":"read_verse_v2_books__book_id__chapters__chapter_id___verse_id__get","parameters":[{"required":true,"schema":{"title":"Book Id","type":"integer"},"name":"book_id","in":"path"},{"required":true,"schema":{"title":"Chapter Id","type":"integer"},"name":"chapter_id","in":"path"},{"required":true,"schema":{"title":"Verse Id","type":"integer"},"name":"verse_id","in":"path"},{"required":false,"schema":{"title":"Translation","type":"string"},"name":"translation","in":"query"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChapterVerse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/verse/{verse_id}/relations":{"get":{"tags":["text"],"summary":"Cross Reference","description":"Fetch cross-references for a verse (related verses grouped by relation set).\n\nPath parameters:\n  - verse_id (integer): Identifier of the source verse.\n\nQuery parameters:\n  - translation (string, optional): Translation code to format related verse text.\n\nAuthentication:\n  - Requires X-Authorization header with a valid token.\n\nResponses:\n  - 200: Array of groups, each a list of RelatedVerse objects.","operationId":"cross_reference_v2_verse__verse_id__relations_get","parameters":[{"required":true,"schema":{"title":"Verse Id","type":"integer"},"name":"verse_id","in":"path"},{"required":false,"schema":{"title":"Translation","type":"string"},"name":"translation","in":"query"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Cross Reference V2 Verse  Verse Id  Relations Get","type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/RelatedVerse"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/search":{"get":{"tags":["search"],"summary":"Search","description":"Full-text search across scripture.\n\nQuery:\n  - query (string, optional): Search phrase or keywords.\n  - translation (string, optional): Restrict results to a translation.\n\nAuth:\n  - Requires X-Authorization header with a valid token.\n\nResponse:\n  - 200: SearchResult object with matches and metadata","operationId":"search_v2_search_get","parameters":[{"required":false,"schema":{"title":"Query","type":"string"},"name":"query","in":"query"},{"required":false,"schema":{"title":"Translation","type":"string"},"name":"translation","in":"query"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/searchAggregator":{"get":{"tags":["search"],"summary":"Search Aggregation","description":"Aggregated search overview for a query (e.g., counts by book or other facets).\n\nQuery:\n  - query (string, optional)\n  - translation (string, optional)\n\nAuth:\n  - Requires X-Authorization header with a valid token.\n\nResponse:\n  - 200: Array of SearchAggregation objects","operationId":"search_aggregation_v2_searchAggregator_get","parameters":[{"required":false,"schema":{"title":"Query","type":"string"},"name":"query","in":"query"},{"required":false,"schema":{"title":"Translation","type":"string"},"name":"translation","in":"query"},{"required":false,"schema":{"title":"X-Authorization","type":"string"},"name":"x-authorization","in":"header"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Search Aggregation V2 Searchaggregator Get","type":"array","items":{"$ref":"#/components/schemas/SearchAggregation"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v2/health":{"get":{"tags":["health"],"summary":"Health","description":"Health check for the API and its upstream dependency.\n\nAuth:\n  - Not required.\n\nResponse:\n  - 200: { status, uptime_years, uptime_days, uptime_hours, uptime_minutes, uptime_seconds, uptime_seconds_total, checks: { upstream: { ok, latency_ms, error? } }, env }","operationId":"health_v2_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Book":{"title":"Book","required":["id","name","testament"],"type":"object","properties":{"id":{"title":"Id","type":"integer"},"name":{"title":"Name","type":"string"},"testament":{"title":"Testament","type":"string"},"genre":{"$ref":"#/components/schemas/Genre"}}},"Chapter":{"title":"Chapter","required":["id"],"type":"object","properties":{"id":{"title":"Id","type":"integer"}}},"ChapterVerse":{"title":"ChapterVerse","required":["book","chapterId","id","verse","verseId"],"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"},"chapterId":{"title":"Chapterid","type":"integer"},"id":{"title":"Id","type":"integer"},"verse":{"title":"Verse","type":"string"},"verseId":{"title":"Verseid","type":"integer"}}},"Genre":{"title":"Genre","required":["id","name"],"type":"object","properties":{"id":{"title":"Id","type":"integer"},"name":{"title":"Name","type":"string"}}},"HTTPValidationError":{"title":"HTTPValidationError","type":"object","properties":{"detail":{"title":"Detail","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"RelatedVerse":{"title":"RelatedVerse","required":["id","book","chapterId","verseId","verse","relationStartVerse","relationEndVerse","rank"],"type":"object","properties":{"id":{"title":"Id","type":"integer"},"book":{"$ref":"#/components/schemas/Book"},"chapterId":{"title":"Chapterid","type":"integer"},"verseId":{"title":"Verseid","type":"integer"},"verse":{"title":"Verse","type":"string"},"relationStartVerse":{"title":"Relationstartverse","type":"integer"},"relationEndVerse":{"title":"Relationendverse","type":"integer"},"rank":{"title":"Rank","type":"integer"}}},"SearchAggregation":{"title":"SearchAggregation","required":["book","hits"],"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"},"hits":{"title":"Hits","type":"integer"}}},"SearchResult":{"title":"SearchResult","required":["total"],"type":"object","properties":{"total":{"title":"Total","type":"integer"},"items":{"title":"Items","type":"array","items":{"$ref":"#/components/schemas/ChapterVerse"}}}},"Token":{"title":"Token","required":["token"],"type":"object","properties":{"token":{"title":"Token","type":"string"}}},"Translation":{"title":"Translation","required":["id","table","language","abbreviation","version","infoUrl"],"type":"object","properties":{"id":{"title":"Id","type":"integer"},"table":{"title":"Table","type":"string"},"language":{"title":"Language","type":"string"},"abbreviation":{"title":"Abbreviation","type":"string"},"version":{"title":"Version","type":"string"},"infoUrl":{"title":"Infourl","type":"string"}}},"User":{"title":"User","required":["email","domain"],"type":"object","properties":{"email":{"title":"Email","type":"string"},"domain":{"title":"Domain","type":"string"}}},"ValidationError":{"title":"ValidationError","required":["loc","msg","type"],"type":"object","properties":{"loc":{"title":"Location","type":"array","items":{"type":"string"}},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}}}}}}