@urantia/api

Typed TypeScript client for the Urantia Papers API.

Zero dependencies — uses the native fetch API.

Installation

npm install @urantia/api

Quick Start

import { UrantiaAPI } from '@urantia/api'

const api = new UrantiaAPI()

// List all papers
const { data: papers } = await api.papers.list()

// List papers with the top entities cited in each
const { data: papersWithTop } = await api.papers.list({ include: 'topEntities' })
// papersWithTop[0].topEntities → [{ id, name, type, count }, ...]

// Get a single paper with its paragraphs
const { data } = await api.papers.get('1')

// Get a paper with entity mentions per paragraph + paper-level topEntities
const { data } = await api.papers.get('1', { include: 'entities' })

// Get just the paper-level topEntities (lighter payload, no per-paragraph mentions)
const { data } = await api.papers.get('1', { include: 'topEntities' })

// Get a specific paragraph
const { data: paragraph } = await api.paragraphs.get('2:0.1')

// Search
const { data: results } = await api.search.fullText('divine love')

// Semantic search
const { data: results } = await api.search.semantic('the nature of God')

// Cross-references — all five surfaces
// 1. UB paragraph → UB paragraphs
const { data: para } = await api.paragraphs.get('1:0.1', { include: 'urantiaParallels' })
para.urantiaParallels // top-10 most-similar UB paragraphs

// 2. UB paragraph → Bible verses
const { data: para2 } = await api.paragraphs.get('1:0.1', { include: 'bibleParallels' })
para2.bibleParallels // top-10 nearest Bible chunks

// 3. Bible verse → UB paragraphs
const { data: bcv } = await api.bible.urantiaParallels('Matt', 5, 3)
bcv.urantiaParallels // top-10 UB paragraphs for Matt 5:3

// 4. Free-form Bible search (with UB paragraphs attached to each result)
const { data: hits } = await api.bible.semanticSearch({
  q: 'love your enemies',
  limit: 5,
  urantiaParallelLimit: 3,
})
hits[0].urantiaParallels // 3 UB paragraphs for the top Bible match

// Combine all three on a single round-trip
const { data: enriched } = await api.paragraphs.get('1:0.1', {
  include: 'entities,bibleParallels,urantiaParallels',
})

Authenticated Endpoints

Pass a token to access user-specific endpoints:

const api = new UrantiaAPI({ token: accessToken })

// Get user profile
const { data: user } = await api.me.get()

// Bookmarks
await api.me.bookmarks.create({ ref: '2:0.1', category: 'Favorites' })
const { data: bookmarks } = await api.me.bookmarks.list()

// Notes
await api.me.notes.create({ ref: '2:0.1', text: 'Insightful passage' })

// Reading progress
await api.me.readingProgress.mark(['2:0.1', '2:0.2', '2:0.3'])
const { data: progress } = await api.me.readingProgress.get()

// Preferences
await api.me.preferences.update({ theme: 'dark', fontSize: 16 })

All Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | api.toc.get() | GET | Full table of contents | | api.papers.list(opts?) | GET | All 197 papers. Pass { include: 'topEntities' } to attach per-paper top-entity aggregates. | | api.papers.get(id, opts?) | GET | Paper with paragraphs. Pass { include: 'entities' \| 'topEntities' \| 'entities,topEntities' }. | | api.paragraphs.get(ref) | GET | Paragraph by reference | | api.paragraphs.random() | GET | Random paragraph | | api.paragraphs.context(ref) | GET | Paragraph with surrounding context | | api.search.fullText(params) | POST | Full-text search across UB paragraphs | | api.search.semantic(params) | POST | Semantic vector search across UB paragraphs | | api.entities.list(options) | GET | List entities | | api.entities.get(id) | GET | Entity details | | api.entities.paragraphs(id) | GET | Paragraphs mentioning entity | | api.bible.books() | GET | List all 81 Bible books | | api.bible.book(code) | GET | Bible book metadata | | api.bible.chapter(code, ch) | GET | All verses in a chapter | | api.bible.verse(code, ch, v) | GET | Single verse | | api.bible.urantiaParallels(code, ch, v) | GET | Top-10 UB paragraphs for a Bible verse | | api.bible.semanticSearch(params) | POST | Bible semantic search (each result includes top-N UB paragraphs) | | api.audio.get(ref) | GET | Audio URLs for paragraph | | api.cite.get(ref, style) | GET | Generate citation | | api.embeddings.get(ref, opts?) | GET | Embedding vector ({ model: 'small' \| 'large' }, default large) | | api.embeddings.exportPaper(id, opts?) | GET | Bulk export embeddings for a paper | | api.me.get() | GET | User profile (auth) | | api.me.update(data) | PUT | Update profile (auth) | | api.me.bookmarks.* | — | Bookmark CRUD (auth) | | api.me.notes.* | — | Note CRUD (auth) | | api.me.readingProgress.* | — | Reading progress (auth) | | api.me.preferences.* | — | User preferences (auth) |

Paragraph References

The API accepts three reference formats interchangeably:

• Standard: 2:0.1 (paper:section.paragraph)
• Global: 1:2.0.1 (part:paper.section.paragraph)
• Short: 2.0.1 (paper.section.paragraph)

Options

const api = new UrantiaAPI({
  baseUrl: 'https://api.urantia.dev', // default
  token: 'your-access-token',         // for authenticated endpoints
})

License

MIT