openapi: 3.2.0 info: title: Urantia Papers Bible API version: 1.0.0 contact: name: urantia.dev url: https://docs.urantia.dev/help email: kelson@urantia.dev license: name: MIT url: https://github.com/urantia-hub/urantia-dev-api/blob/main/LICENSE termsOfService: https://docs.urantia.dev/terms-of-service description: 'Operations tagged Bible across 2 of this provider''s published API definitions: urantia-papers-openapi.json, urantia-papers-openapi.json. Each path carries the servers of the definition it was published in.' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: Bible paths: /bible/books: get: operationId: listBibleBooks tags: - Bible summary: List all 81 Bible books description: 'Returns metadata for every book in the World English Bible (eng-web), including chapter and verse counts. Books are returned in canonical ecumenical order: 39 Old Testament, 15 deuterocanonical, 27 New Testament.' responses: '200': description: List of all Bible books content: application/json: schema: type: object properties: data: type: array items: type: object properties: bookCode: type: string bookName: type: string fullName: type: string abbr: type: string bookOrder: type: integer canon: type: string enum: - ot - deuterocanon - nt chapterCount: type: integer verseCount: type: integer required: - bookCode - bookName - fullName - abbr - bookOrder - canon - chapterCount - verseCount required: - data example: data: - bookCode: Gen bookName: Genesis fullName: The First Book of Moses, Commonly Called Genesis abbr: Gen bookOrder: 1 canon: ot chapterCount: 50 verseCount: 1533 - bookCode: Exod bookName: Exodus fullName: The Second Book of Moses, Commonly Called Exodus abbr: Exod bookOrder: 2 canon: ot chapterCount: 40 verseCount: 1213 headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Too many requests headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development /bible/{bookCode}: get: operationId: getBibleBook tags: - Bible summary: Get a Bible book's metadata description: Returns metadata for a single book including chapter and verse counts. Accepts OSIS codes (e.g., `Gen`), USFM codes (`GEN`), full names (`Genesis`), and common aliases (`genesis`, `1-maccabees`). parameters: - schema: type: string minLength: 1 required: true name: bookCode in: path example: MAT responses: '200': description: Book metadata content: application/json: schema: type: object properties: data: type: object properties: bookCode: type: string bookName: type: string fullName: type: string abbr: type: string bookOrder: type: integer canon: type: string enum: - ot - deuterocanon - nt chapterCount: type: integer verseCount: type: integer required: - bookCode - bookName - fullName - abbr - bookOrder - canon - chapterCount - verseCount required: - data example: data: bookCode: Matt bookName: Matthew fullName: The Gospel According to Matthew abbr: Matt bookOrder: 55 canon: nt chapterCount: 28 verseCount: 1071 headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '404': description: Book not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Too many requests headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development /bible/{bookCode}/{chapter}: get: operationId: getBibleChapter tags: - Bible summary: Get all verses in a Bible chapter description: Returns every verse in the requested chapter, ordered by verse number. Accepts OSIS, USFM, full name, or alias for `bookCode`. parameters: - schema: type: string minLength: 1 required: true name: bookCode in: path example: MAT - schema: type: integer minimum: 1 required: true name: chapter in: path example: 5 responses: '200': description: Chapter with all verses content: application/json: schema: type: object properties: data: type: object properties: bookCode: type: string bookName: type: string canon: type: string enum: - ot - deuterocanon - nt chapter: type: integer verses: type: array items: type: object properties: id: type: string reference: type: string bookCode: type: string bookName: type: string bookOrder: type: integer canon: type: string enum: - ot - deuterocanon - nt chapter: type: integer verse: type: integer text: type: string translation: type: string required: - id - reference - bookCode - bookName - bookOrder - canon - chapter - verse - text - translation required: - bookCode - bookName - canon - chapter - verses required: - data example: data: bookCode: Matt bookName: Matthew canon: nt chapter: 5 verses: - id: Matt.5.1 reference: Matthew 5:1 bookCode: Matt bookName: Matthew bookOrder: 55 canon: nt chapter: 5 verse: 1 text: Seeing the multitudes, he went up onto the mountain. When he had sat down, his disciples came to him. translation: web - id: Matt.5.2 reference: Matthew 5:2 bookCode: Matt bookName: Matthew bookOrder: 55 canon: nt chapter: 5 verse: 2 text: He opened his mouth and taught them, saying, translation: web headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '404': description: Book or chapter not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Too many requests headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development /bible/{bookCode}/{chapter}/{verse}: get: operationId: getBibleVerse tags: - Bible summary: Get a single Bible verse description: Returns one verse from the World English Bible (eng-web). Accepts OSIS, USFM, full name, or alias for `bookCode`. parameters: - schema: type: string minLength: 1 required: true name: bookCode in: path example: MAT - schema: type: integer minimum: 1 required: true name: chapter in: path example: 5 - schema: type: integer minimum: 1 required: true name: verse in: path example: 3 responses: '200': description: Single verse content: application/json: schema: type: object properties: data: type: object properties: id: type: string reference: type: string bookCode: type: string bookName: type: string bookOrder: type: integer canon: type: string enum: - ot - deuterocanon - nt chapter: type: integer verse: type: integer text: type: string translation: type: string required: - id - reference - bookCode - bookName - bookOrder - canon - chapter - verse - text - translation required: - data example: data: id: Matt.5.3 reference: Matthew 5:3 bookCode: Matt bookName: Matthew bookOrder: 55 canon: nt chapter: 5 verse: 3 text: “Blessed are the poor in spirit, for theirs is the Kingdom of Heaven. translation: web headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '404': description: Verse not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Too many requests headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development /bible/{bookCode}/{chapter}/{verse}/urantia-parallels: get: operationId: getBibleVerseUrantiaParallels tags: - Bible summary: Top-10 Urantia paragraphs for a Bible verse description: 'Returns the top 10 Urantia paragraphs whose embeddings are nearest to the Bible chunk containing this verse — the reverse of `?include=bibleParallels` on the UB side. Pre-computed at seed time using `text-embedding-3-large` (3072-d) cosine similarity across the entire UB corpus. Each result includes a similarity score (0..1) and rank (1..10). **These are *semantic* parallels, not curated.** Some matches will be subtly wrong — the embedding model treats surface-level vocabulary as meaning, but the UB uses standard religious terms in nonstandard ways. Treat results as starting points for further reading, not as authoritative parallels.' parameters: - schema: type: string minLength: 1 required: true name: bookCode in: path example: MAT - schema: type: integer minimum: 1 required: true name: chapter in: path example: 5 - schema: type: integer minimum: 1 required: true name: verse in: path example: 3 responses: '200': description: Bible verse with top-10 UB paragraphs content: application/json: schema: type: object properties: data: type: object properties: verse: type: object properties: id: type: string reference: type: string bookCode: type: string bookName: type: string bookOrder: type: integer canon: type: string enum: - ot - deuterocanon - nt chapter: type: integer verse: type: integer text: type: string translation: type: string required: - id - reference - bookCode - bookName - bookOrder - canon - chapter - verse - text - translation chunk: type: object properties: id: type: string reference: type: string verseStart: type: integer verseEnd: type: integer text: type: string required: - id - reference - verseStart - verseEnd - text urantiaParallels: type: array items: type: object properties: id: type: string standardReferenceId: type: string paperId: type: string paperTitle: type: string sectionTitle: type: - string - 'null' text: type: string similarity: type: number rank: type: integer source: type: string embeddingModel: type: string required: - id - standardReferenceId - paperId - paperTitle - sectionTitle - text - similarity - rank - source - embeddingModel required: - verse - chunk - urantiaParallels required: - data example: data: verse: id: Matt.5.3 reference: Matthew 5:3 bookCode: Matt bookName: Matthew bookOrder: 55 canon: nt chapter: 5 verse: 3 text: “Blessed are the poor in spirit, for theirs is the Kingdom of Heaven. translation: web chunk: id: Matt.5.3 reference: Matthew 5:3 verseStart: 3 verseEnd: 3 text: “Blessed are the poor in spirit, for theirs is the Kingdom of Heaven. urantiaParallels: - id: 4:140.3.3 standardReferenceId: '140:3.3' paperId: '140' paperTitle: The Ordination of the Twelve sectionTitle: The Ordination Sermon text: “Happy are the poor in spirit, the humble, for theirs are the treasures of the kingdom of heaven. similarity: 0.853767 rank: 1 source: semantic embeddingModel: text-embedding-3-large - id: 4:140.5.7 standardReferenceId: '140:5.7' paperId: '140' paperTitle: The Ordination of the Twelve sectionTitle: Fatherly and Brotherly Love text: 1. “Happy are the poor in spirit—the humble.” To a child, happiness is the satisfaction of immediate pleasure craving. The adult is willing to sow seeds of self-denial in order to reap subsequent harvests of augmented happiness. In Jesus’ times and since, happiness has all too often been associated with the idea of the possession of wealth. In the story of the Pharisee and the publican praying in the temple, the one felt rich in spirit—egotistical; the other felt “poor in spirit”—humble. One was self-sufficient; the other was teachable and truth-seeking. The poor in spirit seek for goals of spiritual wealth—for God. And such seekers after truth do not have to wait for rewards in a distant future; they are rewarded now. They find the kingdom of heaven within their own hearts, and they experience such happiness now. similarity: 0.644358 rank: 2 source: semantic embeddingModel: text-embedding-3-large headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '404': description: Verse not found or no parallels computed content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Too many requests headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development /bible/search/semantic: post: operationId: bibleSemanticSearch tags: - Bible summary: Semantic search across the Bible (with UB paragraphs) description: 'Free-form natural-language search across all 17,641 Bible chunks. Each result includes the top-N pre-computed Urantia paragraphs related to that chunk via the existing cross-reference data, so a single query surfaces both the Bible matches and the relevant UB content. Query is embedded via `text-embedding-3-small` (1536-d) and matched against `bible_chunks.embedding_small` with a pgvector HNSW index. Latency is ~50-100ms on cache miss for the embedding call, ~30ms cached. Optional filters: `canon` (`ot`, `deuterocanon`, `nt`), `bookCode` (any OSIS/USFM/full-name/alias). `urantiaParallelLimit` controls how many UB paragraphs to attach per result (0-10, default 3). Set to 0 to suppress.' requestBody: required: true content: application/json: schema: type: object properties: q: type: string minLength: 1 maxLength: 2000 page: type: integer minimum: 0 default: 0 limit: type: integer minimum: 1 maximum: 100 default: 20 canon: type: string enum: - ot - deuterocanon - nt bookCode: type: string minLength: 1 urantiaParallelLimit: type: integer minimum: 0 maximum: 10 default: 3 required: - q example: q: blessed are the poor in spirit limit: 2 urantiaParallelLimit: 1 responses: '200': description: Bible semantic search results content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string reference: type: string bookCode: type: string bookName: type: string canon: type: string enum: - ot - deuterocanon - nt chapter: type: integer verseStart: type: integer verseEnd: type: integer text: type: string similarity: type: number urantiaParallels: type: array items: type: object properties: id: type: string standardReferenceId: type: string paperId: type: string paperTitle: type: string sectionTitle: type: - string - 'null' text: type: string similarity: type: number rank: type: integer required: - id - standardReferenceId - paperId - paperTitle - sectionTitle - text - similarity - rank required: - id - reference - bookCode - bookName - canon - chapter - verseStart - verseEnd - text - similarity - urantiaParallels meta: type: object properties: page: type: integer limit: type: integer total: type: integer totalPages: type: integer required: - page - limit - total - totalPages required: - data - meta example: data: - id: Matt.5.3 reference: Matthew 5:3 bookCode: Matt bookName: Matthew canon: nt chapter: 5 verseStart: 3 verseEnd: 3 text: “Blessed are the poor in spirit, for theirs is the Kingdom of Heaven. similarity: 0.840739 urantiaParallels: - id: 4:140.3.3 standardReferenceId: '140:3.3' paperId: '140' paperTitle: The Ordination of the Twelve sectionTitle: The Ordination Sermon text: “Happy are the poor in spirit, the humble, for theirs are the treasures of the kingdom of heaven. similarity: 0.853767 rank: 1 - id: Ps.41.1 reference: Psalms 41:1 bookCode: Ps bookName: Psalms canon: ot chapter: 41 verseStart: 1 verseEnd: 1 text: Blessed is he who considers the poor. Yahweh will deliver him in the day of evil. similarity: 0.642851 urantiaParallels: - id: 4:131.2.8 standardReferenceId: '131:2.8' paperId: '131' paperTitle: The World’s Religions sectionTitle: Judaism text: “Yahweh is the God of my salvation; therefore in the divine name will I put my trust. I will trust in the Lord with all my heart; I will lean not upon my own understanding. In all my ways I will acknowledge him, and he shall direct my paths. The Lord is faithful; he keeps his word with those who serve him; the just shall live by his faith. If you do not well, it is because sin lies at the door; men reap the evil they plough and the sin they sow. Fret not yourself because of evildoers. If you regard iniquity in your heart, the Lord will not hear you; if you sin against God, you also wrong your own soul. God will bring every man’s work to judgment with every secret thing, whether it be good or evil. As a man thinks in his heart, so is he. similarity: 0.512232 rank: 1 meta: page: 0 limit: 2 total: 17641 totalPages: 8821 headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': description: Invalid request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '429': description: Too many requests headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' servers: - url: https://api.urantia.dev description: Production - url: http://localhost:3000 description: Local development components: headers: X-RateLimit-Reset: description: The time the window resets, in Unix seconds. schema: type: integer example: 1791152213 X-RateLimit-Remaining: description: The number of requests left in the current window. schema: type: integer example: 199 X-RateLimit-Limit: description: The number of requests allowed in the current window. schema: type: integer example: 200 schemas: ProblemDetails: type: object description: An RFC 9457 problem details object. Every error response uses it. properties: type: type: string format: uri description: A URI that names the error type. title: type: string description: The short name of the status. status: type: integer description: The HTTP status code. detail: type: string description: What went wrong in this request. required: - type - title - status - detail example: type: https://urantia.dev/errors/not-found title: Not Found status: 404 detail: Paragraph not found x-refined-from: - urantia-papers-openapi.json - urantia-papers-openapi.json