ウランティア・ペーパー API

『ウランティア・ペーパー』のための、開発者およびAIエージェントフレンドリーなAPIです。197のペーパーにわたる14,500以上の全段落について、全文検索、構造化されたコンテンツへのアクセス、および音声URLを提供します。

API エンドポイント

インタラクティブなドキュメントは /docs (Swagger UI) で利用可能です。OpenAPI仕様は /openapi.json にあります。

SDK

公式TypeScript SDKがnpmで利用可能です：

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

ドキュメントについては urantia.dev/sdks を参照してください。

段落ID形式

APIは、文字列から自動検出される3つの参照形式を受け入れます：

検索

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://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" }
    }
  }
}

利用可能なモデルと音声は段落ごとに異なります。専用の /audio/:paragraphId エンドポイントは、特定の段落の音声データのみを返します。

キャッシュ

レスポンスには Cache-Control ヘッダーが含まれます。CloudflareのCDNは s-maxage を介してエッジでキャッシュします：

AIエージェント向け

推奨フロー：

1. GET /toc — 本の構造を理解する

2. POST /search — 関連する箇所を見つける

3. GET /paragraphs/:ref/context?window=3 — 前後の文脈を取得する

4. GET /papers/:id — ペーパー全体を読む

MCPサーバー

APIには https://api.urantia.dev/mcp に組み込みの MCP サーバーが含まれています。Claude Desktop、Cursor、または任意のMCPクライアントを接続して以下にアクセスできます：

• 13個のツール — 検索、段落検索、ペーパーナビゲーション、エンティティ閲覧、音声

• 2個のリソーステンプレート — urantia://paper/{id} (マークダウン) および urantia://entity/{id}

• 2個のプロンプトテンプレート — study_assistant、comparative_theology

Smithery を介してワンクリックでインストールできます。

認証

パブリックエンドポイントは認証を必要としません。ユーザーエンドポイント (/me/*) はJWTを必要とします。OAuthフロー：

1. POST /auth/apps (管理者) または accounts.urantiahub.com/developer でアプリを登録する

2. accounts.urantiahub.com でユーザーがサインインする

3. POST /auth/token を介して認可コードをアクセストークンと交換する

4. Authorization: Bearer <token> としてトークンを渡す

アクセストークンは7日間有効なHS256 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_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

デプロイ：

bun run deploy

データ

コンテンツは urantia-papers-json から取得 — 197のペーパー、1,626のセクション、14,500以上の段落。音声ナレーションは audio.urantia.dev を経由。

ライセンス

このプロジェクトは MITライセンス の下でライセンスされています。

免責事項

これは Adams Technologies LLC による独立したコミュニティプロジェクトです。ウランティア財団とは提携、承認、または関連していません。『ウランティア・ブック』のオリジナルの英語テキストはパブリックドメインです (Michael Foundation v. Urantia Foundation, 10th Cir. 2003)。「ウランティア」という言葉の使用はすべて、主題を特定するための名目的公正使用です。