@urantia/api - Typed API Client

npm install @urantia/api

import { UrantiaAPI } from '@urantia/api'

const api = new UrantiaAPI()

// List all 197 papers
const { data: papers } = await api.papers.list()
console.log(papers[0].title) // "Foreword"

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

// Full-text search
const results = await api.search.fullText('divine love')
console.log(results.meta.total)

// Semantic search
const similar = await api.search.semantic('the nature of God')

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

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

// Table of contents
const { data } = await api.toc.get()

// Papers
const { data: papers } = await api.papers.list()
const { data: paper } = await api.papers.get('2', { include: 'entities' })

// Paragraphs
const { data: p } = await api.paragraphs.get('2:0.1')
const { data: random } = await api.paragraphs.random()
const { data: ctx } = await api.paragraphs.context('2:0.1', { window: 3 })

// Entities
const { data: entities } = await api.entities.list({ type: 'being', limit: 20 })
const { data: entity } = await api.entities.get('jesus')
const { data: mentions } = await api.entities.paragraphs('jesus')

// Full-text (AND, OR, phrase modes)
const results = await api.search.fullText({ q: 'divine love', type: 'phrase', limit: 10 })

// Semantic (vector similarity)
const results = await api.search.semantic({ q: 'what happens after death', limit: 5 })

// Audio URLs
const { data: audio } = await api.audio.get('2:0.1')

// Citations (APA, MLA, Chicago, BibTeX)
const { data: cite } = await api.cite.get('2:0.1', 'apa')

// Vector embeddings (default: text-embedding-3-large 3072-d)
const { data: vec } = await api.embeddings.get('2:0.1')
const { data: vecSmall } = await api.embeddings.get('2:0.1', { model: 'small' })

// Bible — UB↔Bible cross-references
const { data: bibleHits } = await api.bible.semanticSearch({
  q: 'love your enemies',
  limit: 5,
  urantiaParallelLimit: 3,
})
const { data: para } = await api.paragraphs.get('1:0.1', {
  include: 'entities,bibleParallels,urantiaParallels',
})

const { data } = await api.feedback.submit({
  category: 'bug', // 'bug' | 'docs' | 'api' | 'product' | 'other'
  message: 'Phrase search returns 500 for a query with a quote mark.',
  endpoint: '/search',
  client: 'my-app',
})
// data.id, data.receivedAt

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

// Profile
const { data: user } = await api.me.get()
await api.me.update({ name: 'My Name' })

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

// Notes
await api.me.notes.create({ ref: '2:0.1', text: 'Insightful passage' })
const { data: notes } = await api.me.notes.list()
await api.me.notes.update(noteId, { text: 'Updated text' })
await api.me.notes.delete(noteId)

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

// Preferences
await api.me.preferences.update({ theme: 'dark', fontSize: 18 })
const { data: prefs } = await api.me.preferences.get()

// List available languages with translation progress
const { data: languages } = await api.languages.list()
// [{ code: "eng", name: "English", entityCount: 4456, paragraphCount: 16570 }, ...]

// Get an entity in Spanish
const { data: entity } = await api.entities.get('machiventa-melchizedek', { lang: 'es' })
console.log(entity.name)        // "Machiventa Melchizedek"
console.log(entity.description) // Spanish description
console.log(entity.language)    // "es"

// List entities in French
const { data: entities } = await api.entities.list({ type: 'being', lang: 'fr' })

// Entity paragraphs in Portuguese
const { data: mentions } = await api.entities.paragraphs('jesus', { lang: 'pt' })

// Paragraphs in German
const { data: p } = await api.paragraphs.get('2:0.1', { lang: 'de' })

// Random paragraph in Korean
const { data: random } = await api.paragraphs.random({ lang: 'ko' })

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

try {
  const { data } = await api.paragraphs.get('999:999.999')
} catch (err) {
  console.error(err.message) // "404: Paragraph not found"
}