API «Документов Урантии»

API для «Документов Урантии», удобное для разработчиков и ИИ-агентов. Предоставляет полнотекстовый поиск, доступ к структурированному контенту и аудиоссылки для всех 14 500+ абзацев в 197 документах.

Конечные точки 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. CDN Cloudflare кэширует данные на границе сети через s-maxage:

Для ИИ-агентов

Рекомендуемый порядок действий:

1. GET /toc — понять структуру книги

2. POST /search — найти релевантные отрывки

3. GET /paragraphs/:ref/context?window=3 — получить окружающий контекст

4. GET /papers/:id — прочитать документ целиком

MCP-сервер

API включает встроенный MCP сервер по адресу https://api.urantia.dev/mcp — подключите Claude Desktop, Cursor или любой другой MCP-клиент для доступа к:

• 13 инструментам — поиск, поиск абзацев, навигация по документам, просмотр сущностей, аудио

• 2 шаблонам ресурсов — urantia://paper/{id} (markdown) и 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>

Токены доступа — это HS256 JWT со сроком действия 7 дней. PKCE поддерживается для браузерных приложений.

Наблюдаемость

• Логирование: BetterStack через @logtail/edge — структурированные 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_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. Оригинальный английский текст «Книги Урантии» является общественным достоянием (Michael Foundation v. Urantia Foundation, 10-й окружной апелляционный суд, 2003 г.). Все упоминания «Урантии» являются номинативным добросовестным использованием для идентификации предмета обсуждения.