{ "openapi": "3.1.1", "info": { "title": "粵讀聖經 · Public read-only data", "version": "1.0.0", "description": "Anonymous HTTPS GET access to existing published data. No Poppy Session, OAuth, write operations, or remote MCP service. Availability and licenses are edition-specific; preserve verse labels/ranges and OCR uncertainty. Prefer catalog-provided chapter URLs for Yue." }, "servers": [ { "url": "https://canread.bible" } ], "security": [], "externalDocs": { "description": "公開資料與自訂探索擴充指南", "url": "https://canread.bible/ai/" }, "paths": { "/data/catalog.json": { "get": { "operationId": "getPublicCatalog", "summary": "取得主要及靜態參考譯本目錄", "security": [], "responses": { "200": { "description": "公開 JSON；可選欄位按版本而異。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } } } } }, "/data/licenses.json": { "get": { "operationId": "getOriginalContentLicense", "summary": "取得本站原創內容授權；第三方版本條款另列", "security": [], "responses": { "200": { "description": "公開 JSON；可選欄位按版本而異。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/License" } } } } } } }, "/api/reading-catalog.php": { "get": { "operationId": "getReadingCatalog", "summary": "取得目前公開歷史譯本及來源閱讀入口", "security": [], "responses": { "200": { "description": "公開章節及來源閱讀入口；兩個陣列可以為空。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadingCatalog" } } } }, "503": { "description": "暫時不可用；unavailable 為 true。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadingCatalog" } } } } } } }, "/api/editions.php": { "get": { "operationId": "listChapterEditions", "summary": "查詢指定章節嘅公開版本及 jsonURL", "security": [], "responses": { "200": { "description": "公開版本選項。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditionChoices" } } } }, "400": { "description": "無效章節查詢；editions 為空。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditionChoices" } } } }, "503": { "description": "暫時不可用；unavailable 為 true。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditionChoices" } } } } }, "description": "Supply book and chapter together to obtain usable chapter jsonURL values. Omitting book returns public edition metadata; its jsonURL is not a valid chapter URL.", "parameters": [ { "name": "book", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z0-9]{2,8}$", "example": "MRK" } }, { "name": "chapter", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "example": 1 } } ] } }, "/api/chapter.php": { "get": { "operationId": "getPublishedChapter", "summary": "取得指定公開版本嘅章節", "security": [], "responses": { "200": { "description": "公開章節；OCR 疑點及可選來源欄位按版本保留。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chapter" } } } }, "401": { "description": "版本需要登入；不可繞過存取控制。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "版本、章節或查詢未提供。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "暫時不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Use edition IDs and available chapters from public catalogs. Historical verse identifiers may represent ranges or paragraph anchors; do not fabricate individual verses.", "parameters": [ { "name": "edition", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,100}$", "example": "yue" } }, { "name": "book", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9]{2,8}$", "example": "MRK" } }, { "name": "chapter", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "example": 1 } } ] } }, "/data/yue/{bookSlug}/{chapter}.json": { "get": { "operationId": "getYueChapter", "summary": "取得目錄列出嘅粵讀聖經章節 JSON", "security": [], "responses": { "200": { "description": "目錄列出嘅粵語章節。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chapter" } } } }, "404": { "description": "未發布路徑；伺服器可能回傳 HTML 錯誤頁。" } }, "description": "Follow the exact json URL in /data/catalog.json; not every book/chapter exists.", "parameters": [ { "name": "bookSlug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "example": "mark" } }, { "name": "chapter", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "example": 1 } } ] } } }, "components": { "schemas": { "Verse": { "type": "object", "properties": { "verse": { "type": "string" }, "text": { "type": "string" }, "verseRange": { "type": "string" }, "sourceVerseId": { "type": "string" } }, "additionalProperties": true, "required": [ "verse", "text" ] }, "Chapter": { "type": "object", "properties": { "edition": { "type": "string" }, "book": { "type": "string" }, "bookName": { "type": "string" }, "chapter": { "type": "integer", "minimum": 1 }, "language": { "type": "string" }, "verses": { "type": "array", "items": { "$ref": "#/components/schemas/Verse" } }, "notes": { "type": "string" }, "notesMarkdown": { "type": "string" }, "sectionHeadings": { "type": "array", "items": {} }, "license": { "type": "string" }, "licenseURL": { "type": "string" }, "attribution": { "type": "string" } }, "additionalProperties": true, "required": [ "edition", "book", "chapter", "language", "verses" ] }, "CatalogChapter": { "type": "object", "properties": { "book": { "type": "string" }, "name": { "type": "string" }, "chapter": { "type": "integer" }, "url": { "type": "string" }, "json": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": true, "required": [ "book", "chapter", "url", "json", "text" ] }, "CatalogEdition": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "chapters": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogChapter" } }, "books": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "chapters": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } } ] }, "available": { "type": "array", "items": { "type": "integer" } }, "jsonTemplate": { "type": "string" } }, "additionalProperties": true } }, "license": { "type": "string" }, "licenseURL": { "type": "string" } }, "additionalProperties": true, "required": [ "id", "name", "language" ] }, "Catalog": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "const": 1 }, "site": { "type": "string" }, "updated": { "type": "string" }, "primaryEdition": { "type": "string" }, "supplementaryEditions": { "type": "string" }, "editions": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEdition" } }, "lectionary": {} }, "additionalProperties": true, "required": [ "schemaVersion", "site", "primaryEdition", "editions" ] }, "License": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "effectiveDate": { "type": "string" }, "attributionName": { "type": "string" }, "scope": { "type": "string" }, "excluded": { "type": "string" } }, "additionalProperties": true, "required": [ "id", "name", "url", "scope" ] }, "ReadingBook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "chapterCount": { "type": "integer" }, "available": { "type": "array", "items": { "type": "integer" } } }, "additionalProperties": true, "required": [ "id", "name" ] }, "ReadingEdition": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "groupId": { "type": "string" }, "displayRank": { "type": "integer" }, "reviewStage": { "type": [ "string", "null" ] }, "books": { "type": "array", "items": { "$ref": "#/components/schemas/ReadingBook" } } }, "additionalProperties": true, "required": [ "id", "name", "language", "books" ] }, "SourceEdition": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "groupId": { "type": "string" }, "displayRank": { "type": "integer" }, "sourceUrl": { "type": "string" } }, "additionalProperties": true, "required": [ "id", "name", "sourceUrl" ] }, "ReadingCatalog": { "type": "object", "properties": { "editions": { "type": "array", "items": { "$ref": "#/components/schemas/ReadingEdition" } }, "sourceEditions": { "type": "array", "items": { "$ref": "#/components/schemas/SourceEdition" } }, "unavailable": { "type": "boolean" } }, "additionalProperties": true, "required": [ "editions", "sourceEditions" ] }, "EditionChoice": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "shortName": { "type": "string" }, "language": { "type": "string" }, "groupId": { "type": "string" }, "reviewStage": { "type": [ "string", "null" ] }, "jsonURL": { "type": "string" } }, "additionalProperties": true, "required": [ "id", "name", "language", "jsonURL" ] }, "EditionChoices": { "type": "object", "properties": { "editions": { "type": "array", "items": { "$ref": "#/components/schemas/EditionChoice" } }, "unavailable": { "type": "boolean" } }, "additionalProperties": true, "required": [ "editions" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": true } } } }