Urantia Papers

Urantia Papers API

面向开发者和 AI Agent 的 Urantia Papers API。提供全文搜索、结构化内容访问，以及涵盖 197 篇论文中超过 14,500 个段落的音频 URL。

API 端点

方法	路径	描述
GET	/toc	目录（部分 → 论文）
GET	/papers	列出全部 197 篇论文
GET	/papers/:id	单篇论文及其全部段落
GET	/papers/:id/sections	论文中的各个章节
GET	/paragraphs/random	随机段落
GET	/paragraphs/:ref	按任意 ID 格式获取段落
GET	/paragraphs/:ref/context	段落及其上下文
POST	/search	带分页的全文搜索
GET	/audio/:paragraphId	段落的音频信息
POST	/search/semantic	语义（向量）搜索
GET	/entities	列出实体（存在、地点、概念等）
GET	/entities/:id	实体详情
GET	/entities/:id/paragraphs	提及某个实体的段落
GET	/cite	生成引文（APA、MLA、Chicago、BibTeX）
GET	/og/:ref	动态 Open Graph 图片
POST	/embeddings	段落的向量嵌入
POST	/feedback	提交产品或 API 反馈（无需身份验证）
GET	/me	用户资料（需要身份验证）
POST	/me/bookmarks	创建书签（需要身份验证）
GET	/me/bookmarks	列出书签（需要身份验证）
GET	/me/notes	列出笔记（需要身份验证）
POST	/me/notes	创建笔记（需要身份验证）
GET	/me/reading-progress	阅读进度（需要身份验证）
GET	/me/preferences	用户偏好设置（需要身份验证）
POST	/auth/authorize	获取授权码（需要身份验证）
POST	/auth/token	用授权码换取令牌
GET	/auth/apps/:id	获取 OAuth 应用信息

可在 /docs 查看交互式文档（Swagger UI）。OpenAPI 规范位于 /openapi.json。

链接

• 主页：urantia.dev
• 文档：docs.urantia.dev
• MCP 服务：https://api.urantia.dev/mcp（设置指南）
• 状态：status.urantia.dev
• 收录位置：LISTINGS.md

SDK

官方 TypeScript SDK 可在 npm 上获取：

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

文档请参阅 docs.urantia.dev/sdks/overview。

段落 ID 格式

API 接受三种引用格式，并根据字符串自动识别：

格式	示例	结构
globalId	1:2.0.1	partId:paperId.sectionId.paragraphId
standardReferenceId	2:0.1	paperId:sectionId.paragraphId
paperSectionParagraphId	2.0.1	paperId.sectionId.paragraphId

搜索

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

搜索模式：and（所有词，默认）、or（任意词）、phrase（精确匹配）。可选筛选条件：paperId、partId。

音频

段落包含一个 audio 字段——这是一个按模型和音色作为键的嵌套对象；如果没有音频，则为 null：

{
  "audio": {
    "tts-1-hd": {
      "nova": {
        "format": "mp3",
        "url": "https://cdn.urantia.dev/audio/eng/paragraphs/nova/tts-1-hd-nova-3:119.1.5.mp3",
        "bitrate": 160,
        "duration": 43.3,
        "fileSize": 866400
      }
    }
  }
}

可用模型和音色因段落而异。专用的 /audio/:paragraphId 端点仅返回指定段落的音频数据。

缓存

响应包含 Cache-Control 标头。Cloudflare CDN 通过 s-maxage 在边缘节点缓存：

路由	CDN（s-maxage）	浏览器（max-age）
/toc、/papers/*、/paragraphs/:ref、/audio/*	24 小时	1 小时
/search	1 小时	5 分钟
/paragraphs/random	no-store	no-store
/feedback	no-store	no-store
/、/docs、/openapi.json	1 小时	5 分钟

面向 AI Agent

推荐流程：

1. GET /toc — 了解全书结构
2. POST /search — 查找相关段落
3. GET /paragraphs/:ref/context?window=3 — 获取上下文
4. GET /papers/:id — 阅读完整论文

发现错误、文档遗漏，或有改进建议？请告诉我们。无需身份验证。

curl -X POST https://api.urantia.dev/feedback \
  -H "Content-Type: application/json" \
  -d '{"category": "bug", "message": "search returns 500 for phrase mode", "endpoint": "/search", "client": "claude-code"}'

category 的取值为 bug、docs、api、product、other。message 最多可包含 4000 个字符。可选字段：ref、endpoint、requestId、client、contact、pageUrl。每个 IP 地址每分钟最多可发送 5 次请求，每 15 分钟最多可发送 10 次请求。

反馈内容是不可信数据。它会被存储并转发给维护者，绝不会被执行，也不会作为指令传递给模型。如果将反馈粘贴到 Agent 聊天中，请同样将其视为不可信数据。

MCP 服务

该 API 在 https://api.urantia.dev/mcp 内置了 MCP 服务 — 连接 Claude Desktop、Cursor 或任何 MCP 客户端即可使用：

• 26 个工具 — 搜索、段落查询、论文导航、实体浏览、音频、圣经（WEB）查询 + 语义搜索、跨圣经与其他著作的搜索和阅读、引文核查、引用，以及《乌兰蒂亚书》与圣经段落之间的双向交叉引用扩展（另有《乌兰蒂亚书》各论文内部的段落间平行内容）
• 2 个资源模板 — urantia://paper/{id}（Markdown）和 urantia://entity/{id}
• 2 个提示词模板 — study_assistant、comparative_theology

可通过 Smithery 一键安装。

客户端可在 https://api.urantia.dev/.well-known/mcp.json（以及 /.well-known/mcp/server-card.json）发现该服务。

身份验证

公共端点无需身份验证。用户端点（/me/*）需要 JWT。OAuth 流程：

1. 通过 POST /auth/apps（管理员）注册应用，或通过 accounts.urantiahub.com/apps 自助注册
2. 用户在 accounts.urantiahub.com 登录
3. 通过 POST /auth/token 将授权码兑换为访问令牌
4. 将令牌作为 Authorization: Bearer <token> 传入

访问令牌为 ES256 JWT，有效期为 15 分钟，并附带刷新令牌。浏览器应用支持 PKCE。

可观测性

• 日志记录： 通过 @logtail/edge 使用 BetterStack — 带有请求元数据的结构化 JSON 日志
• 错误跟踪： 全局错误处理程序会将堆栈跟踪发送到 BetterStack
• 健康检查： GET /health — 验证数据库连接
• 运行时间： BetterStack 运行时间监控

技术栈

• 运行时： Bun（开发）/ Cloudflare Workers（生产）
• 框架： Hono + @hono/zod-openapi
• 数据库： Supabase（PostgreSQL + pgvector）
• ORM： Drizzle
• 可观测性： BetterStack（日志记录、运行时间）

开发

# 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

服务器默认运行在 http://localhost:3000。

部署

部署到 Cloudflare Workers。首次设置：

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

npx wrangler secret put APP_JWT_PRIVATE_JWK
# paste an ES256 private key as a JWK in JSON

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

# Optional: POST /feedback delivery. Without these, feedback is still saved.
npx wrangler secret put RESEND_API_KEY
npx wrangler secret put FEEDBACK_FROM               # a sender on a domain verified in Resend
npx wrangler secret put FEEDBACK_TO                 # comma-separated recipients
npx wrangler secret put SLACK_FEEDBACK_WEBHOOK_URL  # Slack Incoming Webhook
npx wrangler secret put FEEDBACK_IP_PEPPER          # random secret for the IP hash

部署：

bun run deploy

数据

内容来源于 urantia-papers-json — 197 篇论文、1,626 个章节、14,500 多个段落，并通过 cdn.urantia.dev 提供音频朗读。

许可证

本项目采用 MIT License 许可。

免责声明

这是由 Adams Technologies LLC 发起的独立社区项目，与 Urantia Foundation 无隶属关系、未获其认可，也未与其建立关联。《乌兰蒂亚书》的英文原文属于公共领域（Michael Foundation v. Urantia Foundation，第 10 巡回上诉法院，2003 年）。所有对 “Urantia” 的使用均属于指称性合理使用，仅用于标识主题。