{"openapi":"3.1.0","info":{"title":"Script Bible Read API","version":"0.1.0","description":"Core read-only JSON endpoints used by the public Script Bible experience. No API key is required; rate limits may apply and the preview contract may evolve.","contact":{"url":"https://script.bible/contact"}},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","servers":[{"url":"https://script.bible","description":"Production"}],"tags":[{"name":"Bible","description":"Bible book and chapter content"},{"name":"Search","description":"Scripture search"},{"name":"Operations","description":"Service status"}],"paths":{"/api/books":{"get":{"operationId":"listBooks","summary":"List Bible books","tags":["Bible"],"responses":{"200":{"description":"Book metadata and the total chapter count","content":{"application/json":{"schema":{"type":"object","required":["books","totalChapters"],"properties":{"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}},"totalChapters":{"type":"integer","minimum":1}}}}}}}}},"/api/chapters/{bookId}/{chapter}":{"get":{"operationId":"getChapter","summary":"Get one Bible chapter","tags":["Bible"],"parameters":[{"$ref":"#/components/parameters/BookId"},{"name":"chapter","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"version","in":"query","required":false,"description":"Bible version identifier, such as web or kjv","schema":{"type":"string","default":"web"}}],"responses":{"200":{"description":"Chapter metadata and verses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Chapter"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/search":{"get":{"operationId":"searchScripture","summary":"Search Scripture","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"mode","in":"query","required":false,"description":"Keyword, semantic meaning, combined hybrid, or reference search","schema":{"type":"string","enum":["keyword","semantic","hybrid","reference"],"default":"hybrid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Search results and pagination metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResults"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"description":"Rate limit exceeded; retry after the number of seconds in Retry-After"}}}},"/api/health":{"get":{"operationId":"getHealth","summary":"Check service health","tags":["Operations"],"responses":{"200":{"description":"Service and databases are healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"The service or a required database is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}},"components":{"parameters":{"BookId":{"name":"bookId","in":"path","required":true,"description":"Lowercase Script Bible book identifier, such as genesis or john","schema":{"type":"string","pattern":"^[a-z0-9]+$"}}},"responses":{"BadRequest":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested Bible content does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Book":{"type":"object","required":["id","name","shortName","chapters","testament"],"properties":{"id":{"type":"string","examples":["john"]},"name":{"type":"string","examples":["John"]},"shortName":{"type":"string","examples":["Jn"]},"chapters":{"type":"integer","minimum":1,"examples":[21]},"testament":{"type":"string","enum":["old","new"]}},"additionalProperties":true},"Chapter":{"type":"object","required":["versionId","bookId","bookName","chapter","verses","globalIndex"],"properties":{"versionId":{"type":"string","examples":["web"]},"bookId":{"type":"string","examples":["john"]},"bookName":{"type":"string","examples":["John"]},"chapter":{"type":"integer","minimum":1,"examples":[3]},"verses":{"type":"array","items":{"$ref":"#/components/schemas/Verse"}},"globalIndex":{"type":"integer"}},"additionalProperties":true},"Verse":{"type":"object","required":["verse","text"],"properties":{"verse":{"type":"integer","minimum":1,"examples":[16]},"text":{"type":"string","examples":["For God so loved the world, that he gave his one and only Son..."]},"isPoetry":{"type":"boolean"},"indentLevel":{"type":"integer","minimum":0},"startsNewParagraph":{"type":"boolean"},"stanzaBreakBefore":{"type":"boolean"},"isSuperscription":{"type":"boolean"},"superscriptionBefore":{"type":"string"}},"additionalProperties":true},"SearchResult":{"type":"object","required":["id","versionId","bookId","bookName","chapter","verse","text","matchIndices"],"properties":{"id":{"type":"string","examples":["web:john:3:16"]},"versionId":{"type":"string","examples":["web"]},"bookId":{"type":"string","examples":["john"]},"bookName":{"type":"string","examples":["John"]},"chapter":{"type":"integer","minimum":1,"examples":[3]},"verse":{"type":"integer","minimum":1,"examples":[16]},"text":{"type":"string"},"matchIndices":{"type":"array","items":{"type":"array","prefixItems":[{"type":"integer","minimum":0},{"type":"integer","minimum":0}],"minItems":2,"maxItems":2}},"score":{"type":"number","minimum":0,"maximum":1},"matchType":{"type":"string","enum":["reference","keyword","semantic","both"]}},"additionalProperties":true},"PaginatedResults":{"type":"object","required":["results","page","totalPages","totalCount"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"page":{"type":"integer","minimum":1,"maximum":10000},"totalPages":{"type":"integer","minimum":0},"totalCount":{"type":"integer","minimum":0},"semanticAvailable":{"type":"boolean"},"totalCountIsEstimate":{"type":"boolean"}},"additionalProperties":true},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}},"additionalProperties":true},"Health":{"type":"object","required":["status","timestamp"],"properties":{"status":{"type":"string","enum":["healthy","unhealthy"]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"string"}},"additionalProperties":false}}}}