Urantia Papers API

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

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:

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:

For AI Agents

Recommended flow:

1. GET /toc — understand the book structure

2. POST /search — find relevant passages

3. GET /paragraphs/:ref/context?window=3 — get surrounding context

4. 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:

• 13 tools — search, paragraph lookup, paper navigation, entity browsing, audio

• 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:

1. Register an app via POST /auth/apps (admin) or self-service at accounts.urantiahub.com/developer

2. User signs in at accounts.urantiahub.com

3. Exchange authorization code for access token via POST /auth/token

4. 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.