유란시아 서 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는 문자열에서 자동으로 감지되는 세 가지 참조 형식을 허용합니다:

검색

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에서 진행하는 독립적인 커뮤니티 프로젝트입니다. 유란시아 재단(Urantia Foundation)과 제휴, 보증 또는 연결되어 있지 않습니다. *유란시아 서(The Urantia Book)*의 원본 영어 텍스트는 퍼블릭 도메인입니다(Michael Foundation v. Urantia Foundation, 10th Cir. 2003). "Urantia"라는 용어의 모든 사용은 주제를 식별하기 위한 명목상의 공정 사용(nominative fair use)입니다.