API de los Documentos de Urantia

Una API amigable para desarrolladores y agentes de IA para los Documentos de Urantia. Proporciona búsqueda de texto completo, acceso a contenido estructurado y URLs de audio para los más de 14,500 párrafos en 197 documentos.

Endpoints de la API

Documentación interactiva disponible en /docs (Swagger UI). Especificación OpenAPI en /openapi.json.

SDKs

Los SDKs oficiales de TypeScript están disponibles en npm:

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

Consulta urantia.dev/sdks para obtener la documentación.

Formatos de ID de Párrafo

La API acepta tres formatos de referencia, detectados automáticamente a partir de la cadena:

Búsqueda

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

Modos de búsqueda: and (todas las palabras, predeterminado), or (cualquier palabra), phrase (coincidencia exacta). Filtros opcionales: paperId, partId.

Audio

Los párrafos incluyen un campo audio: un objeto anidado indexado por modelo y voz, o null si no existe audio:

{
  "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" }
    }
  }
}

Los modelos y voces disponibles varían según el párrafo. El endpoint dedicado /audio/:paragraphId devuelve solo los datos de audio para un párrafo determinado.

Caché

Las respuestas incluyen encabezados Cache-Control. La CDN de Cloudflare realiza caché en el borde mediante s-maxage:

Para Agentes de IA

Flujo recomendado:

1. GET /toc — comprender la estructura del libro

2. POST /search — encontrar pasajes relevantes

3. GET /paragraphs/:ref/context?window=3 — obtener contexto circundante

4. GET /papers/:id — leer un documento completo

Servidor MCP

La API incluye un servidor MCP integrado en https://api.urantia.dev/mcp: conecta Claude Desktop, Cursor o cualquier cliente MCP para acceder a:

• 13 herramientas — búsqueda, búsqueda de párrafos, navegación por documentos, navegación de entidades, audio

• 2 plantillas de recursos — urantia://paper/{id} (markdown) y urantia://entity/{id}

• 2 plantillas de prompts — study_assistant, comparative_theology

Instalación con un clic a través de Smithery.

Autenticación

Los endpoints públicos no requieren autenticación. Los endpoints de usuario (/me/*) requieren un JWT. Flujo OAuth:

1. Registra una aplicación mediante POST /auth/apps (administrador) o autoservicio en accounts.urantiahub.com/developer

2. El usuario inicia sesión en accounts.urantiahub.com

3. Intercambia el código de autorización por un token de acceso mediante POST /auth/token

4. Pasa el token como Authorization: Bearer <token>

Los tokens de acceso son JWTs HS256 con una caducidad de 7 días. PKCE es compatible para aplicaciones basadas en navegador.

Observabilidad

• Registro: BetterStack mediante @logtail/edge — registros JSON estructurados con metadatos de solicitud

• Seguimiento de errores: El manejador de errores global envía seguimientos de pila a BetterStack

• Verificación de estado: GET /health — verifica la conectividad con la base de datos

• Tiempo de actividad: Monitor de tiempo de actividad de BetterStack

Stack Tecnológico

• Runtime: Bun (desarrollo) / Cloudflare Workers (producción)

• Framework: Hono + @hono/zod-openapi

• Base de datos: Supabase (PostgreSQL + pgvector)

• ORM: Drizzle

• Observabilidad: BetterStack (registro, tiempo de actividad)

Desarrollo

# 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

El servidor se ejecuta en http://localhost:3000 de forma predeterminada.

Despliegue

Desplegado en Cloudflare Workers. Configuración inicial:

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

Desplegar:

bun run deploy

Datos

Contenido obtenido de urantia-papers-json — 197 documentos, 1,626 secciones, más de 14,500 párrafos con narración de audio a través de audio.urantia.dev.

Licencia

Este proyecto tiene licencia MIT License.

Descargo de responsabilidad

Este es un proyecto comunitario independiente de Adams Technologies LLC. No está afiliado, respaldado ni conectado con la Fundación Urantia. El texto original en inglés de El Libro de Urantia es de dominio público (Michael Foundation v. Urantia Foundation, 10th Cir. 2003). Todo uso de "Urantia" es un uso justo nominativo para identificar el tema.