{
  "markdown": "# Urantia Papers API\n\n[![smithery badge](https://smithery.ai/badge/urantiahub/urantia-papers)](https://smithery.ai/servers/urantiahub/urantia-papers)\n\nA 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.\n\n## API Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/toc` | Table of contents (parts → papers) |\n| GET | `/papers` | List all 197 papers |\n| GET | `/papers/:id` | Single paper with all paragraphs |\n| GET | `/papers/:id/sections` | Sections within a paper |\n| GET | `/paragraphs/random` | Random paragraph |\n| GET | `/paragraphs/:ref` | Paragraph by any ID format |\n| GET | `/paragraphs/:ref/context` | Paragraph with surrounding context |\n| POST | `/search` | Full-text search with pagination |\n| GET | `/audio/:paragraphId` | Audio info for a paragraph |\n| POST | `/search/semantic` | Semantic (vector) search |\n| GET | `/entities` | List entities (beings, places, concepts, etc.) |\n| GET | `/entities/:id` | Entity details |\n| GET | `/entities/:id/paragraphs` | Paragraphs mentioning an entity |\n| GET | `/cite` | Generate citation (APA, MLA, Chicago, BibTeX) |\n| GET | `/og/:ref` | Dynamic Open Graph image |\n| POST | `/embeddings` | Vector embeddings for paragraphs |\n| GET | `/me` | User profile (auth required) |\n| POST | `/me/bookmarks` | Create bookmark (auth required) |\n| GET | `/me/bookmarks` | List bookmarks (auth required) |\n| GET | `/me/notes` | List notes (auth required) |\n| POST | `/me/notes` | Create note (auth required) |\n| GET | `/me/reading-progress` | Reading progress (auth required) |\n| GET | `/me/preferences` | User preferences (auth required) |\n| POST | `/auth/authorize` | Get authorization code (auth required) |\n| POST | `/auth/token` | Exchange code for token |\n| GET | `/auth/apps/:id` | Get OAuth app info |\n\nInteractive docs available at `/docs` (Swagger UI). OpenAPI spec at `/openapi.json`.\n\n## SDKs\n\nOfficial TypeScript SDKs are available on npm:\n\n```bash\nnpm install @urantia/api    # Typed client for all endpoints\nnpm install @urantia/auth   # OAuth client for accounts.urantiahub.com\n```\n\nSee [urantia.dev/sdks](https://urantia.dev/sdks) for documentation.\n\n## Paragraph ID Formats\n\nThe API accepts three reference formats — auto-detected from the string:\n\n| Format | Example | Structure |\n|--------|---------|-----------|\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\n## Search\n\n```bash\ncurl -X POST https://api.urantia.dev/search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"q\": \"Universal Father\", \"limit\": 10, \"type\": \"and\"}'\n```\n\nSearch modes: `and` (all words, default), `or` (any word), `phrase` (exact match). Optional filters: `paperId`, `partId`.\n\n## Audio\n\nParagraphs include an `audio` field — a nested object keyed by model and voice, or `null` if no audio exists:\n\n```json\n{\n  \"audio\": {\n    \"tts-1-hd\": {\n      \"nova\": {\n        \"format\": \"mp3\",\n        \"url\": \"https://cdn.urantia.dev/audio/eng/paragraphs/nova/tts-1-hd-nova-3:119.1.5.mp3\",\n        \"bitrate\": 160,\n        \"duration\": 43.3,\n        \"fileSize\": 866400\n      }\n    }\n  }\n}\n```\n\nAvailable models and voices vary per paragraph. The dedicated `/audio/:paragraphId` endpoint returns just the audio data for a given paragraph.\n\n## Caching\n\nResponses include `Cache-Control` headers. Cloudflare's CDN caches at the edge via `s-maxage`:\n\n| Route | CDN (s-maxage) | Browser (max-age) |\n|-------|---------------|-------------------|\n| `/toc`, `/papers/*`, `/paragraphs/:ref`, `/audio/*` | 24 hours | 1 hour |\n| `/search` | 1 hour | 5 minutes |\n| `/paragraphs/random` | no-store | no-store |\n| `/`, `/docs`, `/openapi.json` | 1 hour | 5 minutes |\n\n## For AI Agents\n\nRecommended flow:\n\n1. `GET /toc` — understand the book structure\n2. `POST /search` — find relevant passages\n3. `GET /paragraphs/:ref/context?window=3` — get surrounding context\n4. `GET /papers/:id` — read a full paper\n\n## MCP Server\n\nThe API includes a built-in [MCP](https://modelcontextprotocol.io) server at `https://api.urantia.dev/mcp` — connect Claude Desktop, Cursor, or any MCP client to access:\n\n- **19 tools** — search, paragraph lookup, paper navigation, entity browsing, audio, Bible (WEB) lookup + semantic search, and bidirectional cross-reference enrichment between Urantia and Bible passages (plus paragraph-to-paragraph parallels within the Papers)\n- **2 resource templates** — `urantia://paper/{id}` (markdown) and `urantia://entity/{id}`\n- **2 prompt templates** — `study_assistant`, `comparative_theology`\n\nOne-click install via [Smithery](https://smithery.ai/servers/urantiahub/urantia-papers).\n\n## Authentication\n\nPublic endpoints require no auth. User endpoints (`/me/*`) require a JWT. OAuth flow:\n\n1. Register an app via `POST /auth/apps` (admin) or self-service at accounts.urantiahub.com/developer\n2. User signs in at [accounts.urantiahub.com](https://accounts.urantiahub.com)\n3. Exchange authorization code for access token via `POST /auth/token`\n4. Pass token as `Authorization: Bearer <token>`\n\nAccess tokens are HS256 JWTs with 7-day expiry. PKCE is supported for browser-based apps.\n\n## Observability\n\n- **Logging:** BetterStack via `@logtail/edge` — structured JSON logs with request metadata\n- **Error tracking:** Global error handler sends stack traces to BetterStack\n- **Health check:** `GET /health` — verifies DB connectivity\n- **Uptime:** BetterStack uptime monitor\n\n## Tech Stack\n\n- **Runtime:** [Bun](https://bun.sh) (dev) / [Cloudflare Workers](https://workers.cloudflare.com) (production)\n- **Framework:** [Hono](https://hono.dev) + [@hono/zod-openapi](https://github.com/honojs/middleware/tree/main/packages/zod-openapi)\n- **Database:** [Supabase](https://supabase.com) (PostgreSQL + pgvector)\n- **ORM:** [Drizzle](https://orm.drizzle.team)\n- **Observability:** [BetterStack](https://betterstack.com) (logging, uptime)\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Set up environment\ncp .env.example .env\n# Edit .env with your Supabase DATABASE_URL\n\n# Push schema to database\nbun run db:push\n\n# Set up full-text search (run after db:push)\nbun scripts/run-fts-setup.ts\n\n# Generate audio manifest (requires ../urantia-hub-api)\nbun run generate-manifest\n\n# Seed database from urantia-papers-json\nbun run seed\n\n# Start dev server (hot reload)\nbun run dev\n```\n\nThe server runs at `http://localhost:3000` by default.\n\n## Deployment\n\nDeployed to Cloudflare Workers. First-time setup:\n\n```bash\nnpx wrangler login\nnpx wrangler secret put DATABASE_URL\n# paste your Supabase connection string (use pooler port 6543)\n\nnpx wrangler secret put APP_JWT_SECRET\n# paste a 64-byte hex secret: node -e \"console.log(require('crypto').randomBytes(64).toString('hex'))\"\n\nnpx wrangler secret put ADMIN_USER_IDS\n# comma-separated Supabase user UUIDs for admin access\n```\n\nDeploy:\n\n```bash\nbun run deploy\n```\n\n## Data\n\nContent sourced from [urantia-papers-json](https://github.com/nicholasgasior/urantia-papers-json) — 197 papers, 1,626 sections, 14,500+ paragraphs with audio narration via [cdn.urantia.dev](https://cdn.urantia.dev/audio/eng/papers/1.mp3).\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE).\n\n## Disclaimer\n\nThis is an independent community project by [Adams Technologies LLC](https://adamstechnologies.com). 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.\n",
  "bytes": 7787,
  "sha": "3c9fbf05429ef02346ff2711de2b0bf3c33b7973a2a44d829647a47b436568e6",
  "repo_slug": "urantia-hub/urantia-dev-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_urantia_urantia_papers_8288c771/readme"
}