Urantia Papers API

![smithery badge](https://smithery.ai/servers/urantiahub/urantia-papers)

A developer and AI-agent friendly API for the Urantia Papers. Provides full-text search, structured content access, and audio URLs for all 14,500+ paragraphs across 197 papers.

API Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /toc | Table of contents (parts → papers) | | GET | /papers | List all 197 papers | | GET | /papers/:id | Single paper with all paragraphs | | GET | /papers/:id/sections | Sections within a paper | | GET | /paragraphs/random | Random paragraph | | GET | /paragraphs/:ref | Paragraph by any ID format | | GET | /paragraphs/:ref/context | Paragraph with surrounding context | | POST | /search | Full-text search with pagination | | GET | /audio/:paragraphId | Audio info for a paragraph | | POST | /search/semantic | Semantic (vector) search | | GET | /entities | List entities (beings, places, concepts, etc.) | | GET | /entities/:id | Entity details | | GET | /entities/:id/paragraphs | Paragraphs mentioning an entity | | GET | /cite | Generate citation (APA, MLA, Chicago, BibTeX) | | GET | /og/:ref | Dynamic Open Graph image | | POST | /embeddings | Vector embeddings for paragraphs | | GET | /me | User profile (auth required) | | POST | /me/bookmarks | Create bookmark (auth required) | | GET | /me/bookmarks | List bookmarks (auth required) | | GET | /me/notes | List notes (auth required) | | POST | /me/notes | Create note (auth required) | | GET | /me/reading-progress | Reading progress (auth required) | | GET | /me/preferences | User preferences (auth required) | | POST | /auth/authorize | Get authorization code (auth required) | | POST | /auth/token | Exchange code for token | | GET | /auth/apps/:id | Get OAuth app info |

Interactive docs available at /docs (Swagger UI). OpenAPI spec at /openapi.json.

SDKs

Official TypeScript SDKs are available on npm:

npm install @urantia/api    # Typed client for all endpoints
npm install @urantia/auth   # OAuth client for accounts.urantiahub.com

See urantia.dev/sdks for documentation.

Paragraph ID Formats

The API accepts three reference formats — auto-detected from the string:

| Format | Example | Structure | |--------|---------|-----------| | globalId | 1:2.0.1 | partId:paperId.sectionId.paragraphId | | standardReferenceId | 2:0.1 | paperId:sectionId.paragraphId | | paperSectionParagraphId | 2.0.1 | paperId.sectionId.paragraphId |

Search

curl -X POST https://api.urantia.dev/search \
  -H "Content-Type: application/json" \
  -d '{"q": "Universal Father", "limit": 10, "type": "and"}'

Search modes: and (all words, default), or (any word), phrase (exact match). Optional filters: paperId, partId.

Audio

Paragraphs include an audio field — a nested object keyed by model and voice, or null if no audio exists:

{
  "audio": {
    "tts-1-hd": {
      "nova": { "format": "mp3", "url": "https://audio.urantia.dev/tts-1-hd-nova-3:119.1.5.mp3" },
      "echo": { "format": "mp3", "url": "https://audio.urantia.dev/tts-1-hd-echo-3:119.1.5.mp3" }
    }
  }
}

Available models and voices vary per paragraph. The dedicated /audio/:paragraphId endpoint returns just the audio data for a given paragraph.

Caching

Responses include Cache-Control headers. Cloudflare's CDN caches at the edge via s-maxage:

| Route | CDN (s-maxage) | Browser (max-age) | |-------|---------------|-------------------| | /toc, /papers/, /paragraphs/:ref, /audio/ | 24 hours | 1 hour | | /search | 1 hour | 5 minutes | | /paragraphs/random | no-store | no-store | | /, /docs, /openapi.json | 1 hour | 5 minutes |

For AI Agents

Recommended flow:

GET /toc — understand the book structure
POST /search — find relevant passages
GET /paragraphs/:ref/context?window=3 — get surrounding context
GET /papers/:id — read a full paper

MCP Server

The API includes a built-in MCP server at https://api.urantia.dev/mcp — connect Claude Desktop, Cursor, or any MCP client to access:

19 tools — search, paragraph lookup, paper navigation, entity browsing, audio, Bible (WEB) lookup + semantic search, and UB↔Bible / UB↔UB cross-reference enrichment
2 resource templates — urantia://paper/{id} (markdown) and urantia://entity/{id}
2 prompt templates — study_assistant, comparative_theology

One-click install via Smithery.

Authentication

Public endpoints require no auth. User endpoints (/me/*) require a JWT. OAuth flow:

Register an app via POST /auth/apps (admin) or self-service at accounts.urantiahub.com/developer
User signs in at accounts.urantiahub.com
Exchange authorization code for access token via POST /auth/token
Pass token as Authorization: Bearer <token>

Access tokens are HS256 JWTs with 7-day expiry. PKCE is supported for browser-based apps.

Observability

Logging: BetterStack via @logtail/edge — structured JSON logs with request metadata
Error tracking: Global error handler sends stack traces to BetterStack
Health check: GET /health — verifies DB connectivity
Uptime: BetterStack uptime monitor

Tech Stack

Runtime: Bun (dev) / Cloudflare Workers (production)
Framework: Hono + @hono/zod-openapi
Database: Supabase (PostgreSQL + pgvector)
ORM: Drizzle
Observability: BetterStack (logging, uptime)

Development

# Install dependencies
bun install

# Set up environment
cp .env.example .env
# Edit .env with your Supabase DATABASE_URL

# Push schema to database
bun run db:push

# Set up full-text search (run after db:push)
bun scripts/run-fts-setup.ts

# Generate audio manifest (requires ../urantia-hub-api)
bun run generate-manifest

# Seed database from urantia-papers-json
bun run seed

# Start dev server (hot reload)
bun run dev

The server runs at http://localhost:3000 by default.

Deployment

Deployed to Cloudflare Workers. First-time setup:

npx wrangler login
npx wrangler secret put DATABASE_URL
# paste your Supabase connection string (use pooler port 6543)

npx wrangler secret put APP_JWT_SECRET
# paste a 64-byte hex secret: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

npx wrangler secret put ADMIN_USER_IDS
# comma-separated Supabase user UUIDs for admin access

Deploy:

bun run deploy

Data

Content sourced from urantia-papers-json — 197 papers, 1,626 sections, 14,500+ paragraphs with audio narration via audio.urantia.dev.

License

This project is licensed under the MIT License.

Disclaimer

This is an independent community project by Adams Technologies LLC. It is not affiliated with, endorsed by, or connected with Urantia Foundation. The original English text of The Urantia Book is in the public domain (Michael Foundation v. Urantia Foundation, 10th Cir. 2003). All use of "Urantia" is nominative fair use to identify the subject matter.

Urantia Papers