{"openapi":"3.1.0","info":{"title":"Urantia Papers API","version":"1.0.0","description":"A developer and AI-agent friendly API for the Urantia Papers. Provides full-text search, structured content access, and audio URLs for all 17,000+ paragraphs across 197 papers."},"servers":[{"url":"https://api.urantia.dev","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"components":{"schemas":{},"parameters":{}},"paths":{"/me":{"get":{"operationId":"getProfile","tags":["User"],"summary":"Get authenticated user profile","responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}},"required":["id","email","name","avatarUrl"]}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"put":{"operationId":"updateProfile","tags":["User"],"summary":"Update user profile","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"avatarUrl":{"type":"string","maxLength":2000,"format":"uri"}}}}}},"responses":{"200":{"description":"Updated profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}},"required":["id","email","name","avatarUrl"]}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/bookmarks":{"get":{"operationId":"listBookmarks","tags":["Bookmarks"],"summary":"List bookmarks","parameters":[{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"paperId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"category","in":"query"}],"responses":{"200":{"description":"Bookmark list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paragraph":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"required":["id","category","createdAt","updatedAt","paragraph"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"post":{"operationId":"createBookmark","tags":["Bookmarks"],"summary":"Create a bookmark (idempotent)","description":"Pass any paragraph reference format. If already bookmarked, updates the category and returns 200.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","description":"Paragraph reference in any format: globalId (1:2.0.1), standardReferenceId (2:0.1), or paperSectionParagraphId (2.0.1)"},"category":{"type":"string","maxLength":100}},"required":["ref"]}}}},"responses":{"200":{"description":"Bookmark already exists (updated category if provided)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paragraph":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"required":["id","category","createdAt","updatedAt","paragraph"]}},"required":["data"]}}}},"201":{"description":"Bookmark created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paragraph":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"required":["id","category","createdAt","updatedAt","paragraph"]}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/bookmarks/categories":{"get":{"operationId":"listBookmarkCategories","tags":["Bookmarks"],"summary":"List bookmark categories with counts and refs","responses":{"200":{"description":"Category list with counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","nullable":true},"count":{"type":"number"},"refs":{"type":"array","items":{"type":"string"}}},"required":["category","count","refs"]}}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/bookmarks/{ref}":{"delete":{"operationId":"deleteBookmark","tags":["Bookmarks"],"summary":"Delete a bookmark by paragraph reference","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"}],"responses":{"204":{"description":"Bookmark deleted"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Paragraph or bookmark not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/notes":{"get":{"operationId":"listNotes","tags":["Notes"],"summary":"List notes","parameters":[{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"paperId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"ref","in":"query"}],"responses":{"200":{"description":"Note list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"format":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paragraph":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"required":["id","text","format","createdAt","updatedAt","paragraph"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"post":{"operationId":"createNote","tags":["Notes"],"summary":"Create a note","description":"Pass any paragraph reference format. Multiple notes per paragraph are allowed. Format: 'plain' (default) or 'markdown'.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","description":"Paragraph reference in any format"},"text":{"type":"string","minLength":1,"maxLength":100000},"format":{"type":"string","enum":["plain","markdown"],"default":"plain"}},"required":["ref","text"]}}}},"responses":{"201":{"description":"Note created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"format":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paragraph":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"required":["id","text","format","createdAt","updatedAt","paragraph"]}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/notes/{id}":{"put":{"operationId":"updateNote","tags":["Notes"],"summary":"Update a note","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000},"format":{"type":"string","enum":["plain","markdown"]}}}}}},"responses":{"200":{"description":"Note updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"format":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paragraph":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"required":["id","text","format","createdAt","updatedAt","paragraph"]}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Note not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"delete":{"operationId":"deleteNoteById","tags":["Notes"],"summary":"Delete a note by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Note deleted"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Note not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/reading-progress":{"get":{"operationId":"getReadingProgress","tags":["Reading Progress"],"summary":"Get reading progress summary per paper with refs and completion","responses":{"200":{"description":"Reading progress per paper","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"paperId":{"type":"string"},"paperTitle":{"type":"string"},"readCount":{"type":"integer"},"totalParagraphs":{"type":"integer"},"percentage":{"type":"number"},"readRefs":{"type":"array","items":{"type":"string"}}},"required":["paperId","paperTitle","readCount","totalParagraphs","percentage","readRefs"]}}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"post":{"operationId":"markRead","tags":["Reading Progress"],"summary":"Mark paragraphs as read (batch, idempotent)","description":"Pass an array of paragraph references in any format. Already-read paragraphs are silently skipped.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refs":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"Paragraph references in any format"}},"required":["refs"]}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"marked":{"type":"number"},"alreadyRead":{"type":"number"},"total":{"type":"number"}},"required":["marked","alreadyRead","total"]}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/reading-progress/{ref}":{"delete":{"operationId":"deleteReadingProgress","tags":["Reading Progress"],"summary":"Unmark a paragraph as read (idempotent)","description":"Returns 204 whether or not progress existed. Returns 404 only if the paragraph ref is invalid.","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"}],"responses":{"204":{"description":"Reading progress deleted (or didn't exist)"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/me/preferences":{"get":{"operationId":"getPreferences","tags":["Preferences"],"summary":"Get user preferences","responses":{"200":{"description":"User preferences","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"put":{"operationId":"updatePreferences","tags":["Preferences"],"summary":"Update user preferences (shallow merge)","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Updated preferences","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/apps/{id}":{"get":{"operationId":"getApp","tags":["Auth"],"summary":"Get public app info","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"App public info","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true}},"required":["id","name","scopes","logoUrl","primaryColor","accentColor"]}},"required":["data"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"delete":{"operationId":"deleteApp","tags":["Auth"],"summary":"Delete an OAuth app (owner-only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"App deleted"},"403":{"description":"Not the app owner","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"patch":{"operationId":"updateApp","tags":["Auth"],"summary":"Update an OAuth app (owner-only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"redirectUris":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"scopes":{"type":"array","items":{"type":"string","enum":["profile","bookmarks","notes","reading-progress","preferences","app-data"]},"minItems":1},"primaryColor":{"type":"string","nullable":true,"pattern":"^#[0-9a-fA-F]{6}$"},"accentColor":{"type":"string","nullable":true,"pattern":"^#[0-9a-fA-F]{6}$"}}}}}},"responses":{"200":{"description":"App updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"ownerId":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","name","redirectUris","scopes","logoUrl","primaryColor","accentColor","ownerId","createdAt"]}},"required":["data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Not the app owner","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/apps":{"post":{"operationId":"createApp","tags":["Auth"],"summary":"Register a new OAuth app","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":3,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"name":{"type":"string","minLength":1},"redirectUris":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"scopes":{"type":"array","items":{"type":"string"},"minItems":1},"primaryColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accentColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"required":["id","name","redirectUris","scopes"]}}}},"responses":{"201":{"description":"App created (secret shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"secret":{"type":"string"}},"required":["id","name","redirectUris","scopes","secret"]}},"required":["data"]}}}},"400":{"description":"Validation error or duplicate ID","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"get":{"operationId":"listMyApps","tags":["Auth"],"summary":"List OAuth apps owned by the authenticated user","responses":{"200":{"description":"List of apps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","name","redirectUris","scopes","logoUrl","primaryColor","accentColor","createdAt"]}}},"required":["data"]}}}}}}},"/auth/consent":{"get":{"operationId":"checkConsent","tags":["Auth"],"summary":"Check if the user has already consented to an app's scopes","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"scopes","in":"query"}],"responses":{"200":{"description":"Consent status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"consented":{"type":"boolean"},"grantedScopes":{"type":"array","items":{"type":"string"}}},"required":["consented","grantedScopes"]}},"required":["data"]}}}}}}},"/auth/authorize":{"post":{"operationId":"authorize","tags":["Auth"],"summary":"Create an authorization code (authenticated user)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":1},"redirectUri":{"type":"string","minLength":1},"scopes":{"type":"array","items":{"type":"string"},"minItems":1},"codeChallenge":{"type":"string"},"state":{"type":"string"}},"required":["appId","redirectUri","scopes"]}}}},"responses":{"200":{"description":"Authorization code created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string"},"state":{"type":"string"}},"required":["code"]}},"required":["data"]}}}},"400":{"description":"Invalid redirect URI or scopes","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/token":{"post":{"operationId":"exchangeToken","tags":["Auth"],"summary":"Exchange authorization code for tokens","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1},"appId":{"type":"string","minLength":1},"appSecret":{"type":"string","minLength":1},"codeVerifier":{"type":"string"},"redirectUri":{"type":"string"}},"required":["code","appId"]}}}},"responses":{"200":{"description":"Token response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"userId":{"type":"string"},"email":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string"}},"required":["accessToken","refreshToken","userId","email","scopes","expiresAt"]}},"required":["data"]}}}},"400":{"description":"Invalid, expired, or already-used code","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"401":{"description":"Invalid app secret","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/refresh":{"post":{"operationId":"refreshToken","tags":["Auth"],"summary":"Exchange a refresh token for a new access token + refresh token","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","minLength":1},"appId":{"type":"string","minLength":1}},"required":["refreshToken","appId"]}}}},"responses":{"200":{"description":"New token pair","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"userId":{"type":"string"},"email":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string"}},"required":["accessToken","refreshToken","userId","email","scopes","expiresAt"]}},"required":["data"]}}}},"400":{"description":"Invalid or expired refresh token","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"401":{"description":"Refresh token reused (theft detected) — all tokens revoked","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/apps/{id}/rotate-secret":{"post":{"operationId":"rotateAppSecret","tags":["Auth"],"summary":"Rotate the app secret (owner-only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"New secret (shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"secret":{"type":"string"}},"required":["secret"]}},"required":["data"]}}}},"403":{"description":"Not the app owner","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/apps/{id}/logo":{"post":{"operationId":"uploadAppLogo","tags":["Auth"],"summary":"Upload an app logo (owner-only, max 2MB, PNG/JPEG/WebP)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logo":{"nullable":true}}}}}},"responses":{"200":{"description":"Logo uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"logoUrl":{"type":"string"}},"required":["logoUrl"]}},"required":["data"]}}}},"400":{"description":"Invalid file","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Not the app owner","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"delete":{"operationId":"deleteAppLogo","tags":["Auth"],"summary":"Remove an app logo (owner-only)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Logo removed"},"403":{"description":"Not the app owner","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"get":{"operationId":"getAppLogo","tags":["Auth"],"summary":"Get app logo image (public)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Logo image"},"404":{"description":"No logo found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/auth/admin/check":{"get":{"operationId":"adminCheck","tags":["Admin"],"summary":"Check if the authenticated user is an admin","responses":{"200":{"description":"Admin status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"isAdmin":{"type":"boolean"}},"required":["isAdmin"]}},"required":["data"]}}}}}}},"/auth/admin/apps":{"get":{"operationId":"adminListApps","tags":["Admin"],"summary":"List all OAuth apps (admin-only)","responses":{"200":{"description":"All apps with owner info","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":"string","nullable":true},"primaryColor":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"ownerId":{"type":"string","nullable":true},"ownerEmail":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","name","redirectUris","scopes","logoUrl","primaryColor","accentColor","ownerId","ownerEmail","createdAt"]}}},"required":["data"]}}}},"403":{"description":"Not an admin","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/toc":{"get":{"operationId":"getToc","tags":["Table of Contents"],"summary":"Get the full table of contents","description":"Returns the complete table of contents with parts and their papers. This is typically the first endpoint an AI agent should call to understand the book structure.","responses":{"200":{"description":"Table of contents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"parts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"sponsorship":{"type":"string","nullable":true},"papers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}}},"required":["id","title","labels"]}}},"required":["id","title","sponsorship","papers"]}}},"required":["parts"]}},"required":["data"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/papers":{"get":{"operationId":"listPapers","tags":["Papers"],"summary":"List all 197 papers","description":"Returns metadata for all papers in the Urantia Book, ordered by paper number.\n\nUse `?include=topEntities` to attach a per-paper aggregate of the most-referenced named entities (beings, places, concepts, etc.) sorted by citation frequency.","parameters":[{"schema":{"type":"string"},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["default","rag"],"default":"default"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"List of all papers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"partId":{"type":"string"},"title":{"type":"string"},"sortId":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"video":{"type":"object","nullable":true,"additionalProperties":{"type":"object","properties":{"mp4":{"type":"string"},"thumbnail":{"type":"string"},"duration":{"type":"number"}},"required":["mp4","thumbnail","duration"]}},"topEntities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["id","name","type","count"]}}},"required":["id","partId","title","sortId","labels","video"]}}},"required":["data"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/papers/{id}":{"get":{"operationId":"getPaper","tags":["Papers"],"summary":"Get a paper with all its paragraphs","description":"Returns a single paper's metadata along with all its paragraphs in order. Paper IDs range from 0 (Foreword) to 196.\n\nUse `?include=entities` to include typed entity mentions in each paragraph.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["default","rag"],"default":"default"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"Paper with paragraphs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"paper":{"type":"object","properties":{"id":{"type":"string"},"partId":{"type":"string"},"title":{"type":"string"},"sortId":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"video":{"type":"object","nullable":true,"additionalProperties":{"type":"object","properties":{"mp4":{"type":"string"},"thumbnail":{"type":"string"},"duration":{"type":"number"}},"required":["mp4","thumbnail","duration"]}},"topEntities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["id","name","type","count"]}}},"required":["id","partId","title","sortId","labels","video"]},"paragraphs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}}},"required":["paper","paragraphs"]}},"required":["data"]}}}},"404":{"description":"Paper not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/papers/{id}/sections":{"get":{"operationId":"getPaperSections","tags":["Papers"],"summary":"Get sections within a paper","description":"Returns all sections for a given paper, ordered by section number.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of sections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string"},"title":{"type":"string","nullable":true},"globalId":{"type":"string"},"sortId":{"type":"string"}},"required":["id","paperId","sectionId","title","globalId","sortId"]}}},"required":["data"]}}}},"404":{"description":"Paper not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/paragraphs/random":{"get":{"operationId":"getRandomParagraph","tags":["Paragraphs"],"summary":"Get a random paragraph","description":"Returns a single random paragraph from the Urantia Book. Useful for daily quotes or exploration.\n\nResponse includes a `navigation` envelope with the previous and next paragraph refs (within the same paper, ordered by sortId). Refs are `null` at paper boundaries.\n\nUse `?include=entities` to include typed entity mentions in the response.\n\nUse `?minLength=N` and/or `?maxLength=N` to filter by character count of the paragraph text.","parameters":[{"schema":{"type":"string"},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["default","rag"],"default":"default"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"minLength","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"maxLength","in":"query"}],"responses":{"200":{"description":"A random paragraph","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]},"navigation":{"type":"object","properties":{"prev":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}},"required":["prev","next"]}},"required":["data"]}}}},"400":{"description":"Invalid filter criteria","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/paragraphs/{ref}":{"get":{"operationId":"getParagraph","tags":["Paragraphs"],"summary":"Get a paragraph by reference","description":"Look up a paragraph using any of three ID formats:\n- **globalId**: \"1:2.0.1\" (partId:paperId.sectionId.paragraphId)\n- **standardReferenceId**: \"2:0.1\" (paperId:sectionId.paragraphId)\n- **paperSectionParagraphId**: \"2.0.1\" (paperId.sectionId.paragraphId)\n\nThe format is auto-detected from the reference string.\n\nResponse includes a `navigation` envelope with the previous and next paragraph refs (within the same paper, ordered by sortId). Refs are `null` at paper boundaries.\n\nUse `?include=entities` to include typed entity mentions in the response.","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"},{"schema":{"type":"string"},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["default","rag"],"default":"default"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"The paragraph","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]},"navigation":{"type":"object","properties":{"prev":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}},"required":["prev","next"]}},"required":["data"]}}}},"400":{"description":"Invalid reference format","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/paragraphs/{ref}/context":{"get":{"operationId":"getParagraphContext","tags":["Paragraphs"],"summary":"Get a paragraph with surrounding context","description":"Returns the target paragraph along with N paragraphs before and after it (ordered by sort_id).\nUseful for AI agents doing RAG that need surrounding context for better understanding.\nThe `window` query parameter controls how many paragraphs before/after to include (default: 2, max: 10).\n\nUse `?include=entities` to include typed entity mentions in the response.","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":2},"required":false,"name":"window","in":"query"},{"schema":{"type":"string"},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["default","rag"],"default":"default"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"Paragraph with context","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"target":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]},"before":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"after":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}}},"required":["target","before","after"]}},"required":["data"]}}}},"400":{"description":"Invalid reference format","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/search":{"post":{"operationId":"search","tags":["Search"],"summary":"Full-text search across all paragraphs","description":"Search the Urantia Papers using full-text search. Supports three search modes:\n- **and**: All words must appear (default)\n- **or**: Any word can appear\n- **phrase**: Exact phrase match\n\nResults are ranked by relevance. Optional filters: paperId, partId.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":500},"page":{"type":"integer","minimum":0,"default":0},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"paperId":{"type":"string"},"partId":{"type":"string"},"type":{"type":"string","enum":["phrase","and","or"],"default":"and"},"include":{"type":"string"}},"required":["q"]}}}},"responses":{"200":{"description":"Search results with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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"]}},"rank":{"type":"number"}},"required":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio","rank"]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["data","meta"]}}}},"400":{"description":"Invalid search query","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"get":{"operationId":"searchGet","tags":["Search"],"summary":"Full-text search across all paragraphs (GET)","description":"Search the Urantia Papers using full-text search. Supports three search modes:\n- **and**: All words must appear (default)\n- **or**: Any word can appear\n- **phrase**: Exact phrase match\n\nResults are ranked by relevance. Optional filters: paperId, partId.\n\nAccepts query parameters instead of a JSON body. Designed for AI agents and browser-based access.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":500},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"paperId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"partId","in":"query"},{"schema":{"type":"string","enum":["phrase","and","or"],"default":"and"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"Search results with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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"]}},"rank":{"type":"number"}},"required":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio","rank"]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["data","meta"]}}}},"400":{"description":"Invalid search query","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/search/semantic":{"post":{"operationId":"semanticSearch","tags":["Search"],"summary":"Semantic similarity search across all paragraphs","description":"Search the Urantia Papers using semantic similarity (vector embeddings).\nReturns conceptually related results even without exact keyword matches.\nOptional filters: paperId, partId.","requestBody":{"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},"paperId":{"type":"string"},"partId":{"type":"string"},"include":{"type":"string"}},"required":["q"]}}}},"responses":{"200":{"description":"Semantic search results with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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"]}},"similarity":{"type":"number"}},"required":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio","similarity"]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["data","meta"]}}}},"400":{"description":"Invalid search query","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"get":{"operationId":"semanticSearchGet","tags":["Search"],"summary":"Semantic similarity search across all paragraphs (GET)","description":"Search the Urantia Papers using semantic similarity (vector embeddings).\nReturns conceptually related results even without exact keyword matches.\nOptional filters: paperId, partId.\n\nAccepts query parameters instead of a JSON body. Designed for AI agents and browser-based access.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":2000},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"paperId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"partId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"Semantic search results with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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"]}},"similarity":{"type":"number"}},"required":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio","similarity"]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["data","meta"]}}}},"400":{"description":"Invalid search query","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/entities":{"get":{"operationId":"listEntities","tags":["Entities"],"summary":"List entities","description":"Browse the entity catalog (beings, places, orders, races, religions, concepts). Supports filtering by type and searching by name.","parameters":[{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["being","place","order","race","religion","concept"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"Paginated list of entities","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]},"aliases":{"type":"array","nullable":true,"items":{"type":"string"}},"description":{"type":"string","nullable":true},"seeAlso":{"type":"array","nullable":true,"items":{"type":"string"}},"citationCount":{"type":"integer"},"language":{"type":"string"}},"required":["id","name","type","aliases","description","seeAlso","citationCount"]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["data","meta"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/entities/{id}":{"get":{"operationId":"getEntity","tags":["Entities"],"summary":"Get an entity by ID","description":"Returns a single entity by its slug ID.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The entity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]},"aliases":{"type":"array","nullable":true,"items":{"type":"string"}},"description":{"type":"string","nullable":true},"seeAlso":{"type":"array","nullable":true,"items":{"type":"string"}},"citationCount":{"type":"integer"},"language":{"type":"string"}},"required":["id","name","type","aliases","description","seeAlso","citationCount"]}},"required":["data"]}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/entities/{id}/paragraphs":{"get":{"operationId":"getEntityParagraphs","tags":["Entities"],"summary":"Get paragraphs mentioning an entity","description":"Returns all paragraphs that mention a given entity, ordered by position in the text.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["eng","es","fr","pt","de","ko"],"default":"eng"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"Paginated paragraphs mentioning the entity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"sortId":{"type":"string"},"paperId":{"type":"string"},"sectionId":{"type":"string","nullable":true},"partId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"paragraphId":{"type":"string"},"text":{"type":"string"},"htmlText":{"type":"string"},"language":{"type":"string"},"labels":{"type":"array","nullable":true,"items":{"type":"string"}},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["being","place","order","race","religion","concept"]}},"required":["id","name","type"]}},"bibleParallels":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"reference":{"type":"string"},"bookCode":{"type":"string"},"chapter":{"type":"integer"},"verseStart":{"type":"integer"},"verseEnd":{"type":"integer"},"text":{"type":"string"},"similarity":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"embeddingModel":{"type":"string"}},"required":["chunkId","reference","bookCode","chapter","verseStart","verseEnd","text","similarity","rank","source","embeddingModel"]}},"urantiaParallels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"standardReferenceId":{"type":"string"},"paperId":{"type":"string"},"paperTitle":{"type":"string"},"sectionTitle":{"type":"string","nullable":true},"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":["id","standardReferenceId","sortId","paperId","sectionId","partId","paperTitle","sectionTitle","paragraphId","text","htmlText","labels","audio"]}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["page","limit","total","totalPages"]}},"required":["data","meta"]}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/languages":{"get":{"operationId":"listLanguages","tags":["Languages"],"summary":"List available languages","description":"Returns available languages with translation progress (entity and paragraph counts).","responses":{"200":{"description":"Available languages with translation counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"entityCount":{"type":"integer"},"paragraphCount":{"type":"integer"}},"required":["code","name","entityCount","paragraphCount"]}}},"required":["data"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/audio/{ref}":{"get":{"operationId":"getAudio","tags":["Audio"],"summary":"Get audio URL for a paragraph","description":"Returns the audio file URL for a given paragraph. Accepts any paragraph reference format (globalId, standardReferenceId, or paperSectionParagraphId).","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"}],"responses":{"200":{"description":"Audio information","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"audio":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"format":{"type":"string"},"url":{"type":"string"},"duration":{"type":"number"},"bitrate":{"type":"number"},"fileSize":{"type":"number"}},"required":["format","url"]}}}},"required":["id","audio"]}},"required":["data"]}}}},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/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"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/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"}],"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"]}}}},"404":{"description":"Book not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/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"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"chapter","in":"path"}],"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"]}}}},"404":{"description":"Book or chapter not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/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"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"chapter","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"verse","in":"path"}],"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"]}}}},"404":{"description":"Verse not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/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).\n\n**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"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"chapter","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"verse","in":"path"}],"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","nullable":true},"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"]}}}},"404":{"description":"Verse not found or no parallels computed","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/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.\n\nQuery 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.\n\nOptional 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":{"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"]}}}},"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","nullable":true},"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"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/cite":{"get":{"operationId":"getCitation","tags":["Citation"],"summary":"Format a citation for a passage","description":"Generate a formatted citation for any Urantia Book passage. Supports APA, MLA, Chicago, and BibTeX styles.\n\nReference formats accepted:\n- **standardReferenceId**: \"196:2.1\" (paperId:sectionId.paragraphId)\n- **globalId**: \"1:196.2.1\" (partId:paperId.sectionId.paragraphId)\n- **paperSectionParagraphId**: \"196.2.1\" (paperId.sectionId.paragraphId)","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ref","in":"query"},{"schema":{"type":"string","enum":["apa","mla","chicago","bibtex"],"default":"apa"},"required":false,"name":"style","in":"query"}],"responses":{"200":{"description":"Formatted citation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ref":{"type":"string"},"style":{"type":"string","enum":["apa","mla","chicago","bibtex"]},"citation":{"type":"string"}},"required":["ref","style","citation"]}},"required":["data"]}}}},"400":{"description":"Invalid reference format","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/og/{ref}":{"get":{"operationId":"getOgImage","tags":["OG Images"],"summary":"Generate a dynamic Open Graph image for a passage","description":"Returns a 1200×630 PNG Open Graph image for a Urantia Book passage. Designed for social media previews.\n\nOptional `?theme=` parameter: `default` (blue), `warm` (amber), `purple`, `minimal` (no glow).\n\nImages are cached permanently (`Cache-Control: immutable`).","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"},{"schema":{"type":"string","enum":["default","warm","purple","minimal"],"default":"default"},"required":false,"name":"theme","in":"query"}],"responses":{"200":{"description":"PNG image"},"404":{"description":"Paragraph not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/embeddings/export":{"get":{"operationId":"exportEmbeddings","tags":["Embeddings"],"summary":"Bulk export embedding vectors","description":"Export embedding vectors for all paragraphs in a paper. The `paperId` query parameter is required.\n\nReturns JSONL (default) or JSON. Each line/item contains `{ ref, embedding }`. A typical paper is 50-200 paragraphs (~1-5 MB).","parameters":[{"schema":{"type":"string","enum":["jsonl","json"],"default":"jsonl"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string"},"required":true,"name":"paperId","in":"query"},{"schema":{"type":"string","enum":["small","large"],"default":"large"},"required":false,"name":"model","in":"query"}],"responses":{"200":{"description":"Embedding vectors (JSONL or JSON)"}}}},"/embeddings/{ref}":{"get":{"operationId":"getEmbedding","tags":["Embeddings"],"summary":"Get the embedding vector for a paragraph","description":"Returns the embedding vector for a single paragraph.\n\nUse `?model=large` (default) for the 3072-dimensional `text-embedding-3-large` vector — the canonical embedding used by the cross-references feature. Use `?model=small` for the 1536-dimensional `text-embedding-3-small` vector that powers `/search/semantic`.\n\nThe response includes `model` and `dimensions` fields so consumers can detect mismatches if they store vectors locally and compare against new responses. The `X-Embedding-Model` response header carries the same signal for byte-streaming clients.","parameters":[{"schema":{"type":"string"},"required":true,"name":"ref","in":"path"},{"schema":{"type":"string","enum":["small","large"],"default":"large"},"required":false,"name":"model","in":"query"}],"responses":{"200":{"description":"Embedding vector","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"standardReferenceId":{"type":"string"},"model":{"type":"string"},"dimensions":{"type":"integer"},"embedding":{"type":"array","items":{"type":"number"}}},"required":["standardReferenceId","model","dimensions","embedding"]}},"required":["data"]}}}},"404":{"description":"Paragraph or embedding not found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}},"required":["type","title","status","detail"]}}}}}}},"/tools/openai":{"get":{"operationId":"getOpenAITools","tags":["Tools"],"summary":"Function-calling schemas for OpenAI","description":"Returns the full Urantia Papers API tool catalog as ready-to-use OpenAI function-calling schemas.\n\nDrop into any OpenAI Chat Completions or Assistants call:\n\n```ts\nconst { tools } = await fetch(\"https://api.urantia.dev/tools/openai\").then(r => r.json());\nconst completion = await openai.chat.completions.create({\n  model: \"gpt-5\",\n  messages,\n  tools, // ready to go\n});\n```\n\nEach tool corresponds 1:1 with an MCP tool exposed at /mcp; you can run the call yourself against the relevant REST endpoint or use the published `@urantia/api` SDK to dispatch.","responses":{"200":{"description":"OpenAI tool definitions","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"object","properties":{"name":{"type":"string"},"base_url":{"type":"string"}},"required":["name","base_url"]},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","properties":{"type":{"type":"string"},"properties":{"type":"object","additionalProperties":{"nullable":true}},"required":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}},"required":["type"]}},"required":["name","description","parameters"]}},"required":["type","function"]}}},"required":["server","tools"]}}}}}}},"/tools/anthropic":{"get":{"operationId":"getAnthropicTools","tags":["Tools"],"summary":"Function-calling schemas for Anthropic","description":"Returns the full Urantia Papers API tool catalog as ready-to-use Anthropic Messages `tools` definitions.\n\nDrop into any Anthropic Messages call:\n\n```ts\nconst { tools } = await fetch(\"https://api.urantia.dev/tools/anthropic\").then(r => r.json());\nconst message = await anthropic.messages.create({\n  model: \"claude-opus-4-7\",\n  max_tokens: 1024,\n  tools, // ready to go\n  messages,\n});\n```\n\nEach tool corresponds 1:1 with an MCP tool exposed at /mcp.","responses":{"200":{"description":"Anthropic tool definitions","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"object","properties":{"name":{"type":"string"},"base_url":{"type":"string"}},"required":["name","base_url"]},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"input_schema":{"type":"object","properties":{"type":{"type":"string"},"properties":{"type":"object","additionalProperties":{"nullable":true}},"required":{"type":"array","items":{"type":"string"}},"description":{"type":"string"}},"required":["type"]}},"required":["name","description","input_schema"]}}},"required":["server","tools"]}}}}}}}}}