Urantia Papers

Urantia Papers API

Urantia Papers 向けの、開発者や AI エージェントが使いやすい 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 は3種類の参照形式を受け付け、文字列から自動的に判別します。

形式	例	構造
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 エージェント向け

推奨されるフロー：

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 アドレスごとに1分あたり5件、15分あたり10件です。

フィードバックは信頼できないデータです。保存されてメンテナーに転送されますが、実行されたり、モデルに指示として渡されたりすることはありません。エージェントとのチャットにフィードバックを貼り付ける場合も、同様に扱ってください。

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（管理者）またはアカウントページからセルフサービスでアプリを登録します
2. ユーザーがaccounts.urantiahub.comでサインインします
3. POST /auth/tokenで認可コードをアクセストークンと交換します
4. Authorization: Bearer <token>としてトークンを渡します

アクセストークンは有効期間15分の ES256 JWT で、リフレッシュトークンも使用できます。ブラウザベースのアプリでは PKCE がサポートされています。

可観測性

• ロギング： @logtail/edge経由のBetterStack — リクエストのメタデータを含む構造化JSONログ
• エラー追跡： グローバルエラーハンドラーがスタックトレースをBetterStackに送信します
• ヘルスチェック： GET /health — DBへの接続を確認します
• 稼働時間： 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とは提携、推奨、関係のいずれもありません。The Urantia Bookの原文である英語テキストはパブリックドメインです（Michael Foundation v. Urantia Foundation, 10th Cir. 2003）。「Urantia」の使用はすべて、主題を特定するための名目的な公正使用です。