Urantia Papers API

Eine entwickler- und KI-agentenfreundliche API für die Urantia-Papiere. Bietet Volltextsuche, strukturierten Inhaltszugriff und Audio-URLs für alle über 14.500 Absätze in 197 Papieren.

API-Endpunkte

Interaktive Dokumentation verfügbar unter /docs (Swagger UI). OpenAPI-Spezifikation unter /openapi.json.

SDKs

Offizielle TypeScript-SDKs sind auf npm verfügbar:

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

Siehe urantia.dev/sdks für die Dokumentation.

Absatz-ID-Formate

Die API akzeptiert drei Referenzformate, die automatisch aus der Zeichenfolge erkannt werden:

Suche

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

Suchmodi: and (alle Wörter, Standard), or (jedes Wort), phrase (exakte Übereinstimmung). Optionale Filter: paperId, partId.

Audio

Absätze enthalten ein audio-Feld – ein verschachteltes Objekt, das nach Modell und Stimme sortiert ist, oder null, falls kein Audio existiert:

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

Verfügbare Modelle und Stimmen variieren je nach Absatz. Der dedizierte Endpunkt /audio/:paragraphId gibt nur die Audiodaten für einen bestimmten Absatz zurück.

Caching

Antworten enthalten Cache-Control-Header. Cloudflares CDN cached am Edge über s-maxage:

Für KI-Agenten

Empfohlener Ablauf:

1. GET /toc – Struktur des Buches verstehen

2. POST /search – relevante Passagen finden

3. GET /paragraphs/:ref/context?window=3 – umgebenden Kontext abrufen

4. GET /papers/:id – ein vollständiges Papier lesen

MCP-Server

Die API enthält einen integrierten MCP-Server unter https://api.urantia.dev/mcp – verbinden Sie Claude Desktop, Cursor oder einen beliebigen MCP-Client, um Zugriff zu erhalten auf:

• 13 Tools – Suche, Absatzsuche, Papiernavigation, Entitäten-Browsing, Audio

• 2 Ressourcen-Vorlagen – urantia://paper/{id} (Markdown) und urantia://entity/{id}

• 2 Prompt-Vorlagen – study_assistant, comparative_theology

Ein-Klick-Installation über Smithery.

Authentifizierung

Öffentliche Endpunkte erfordern keine Authentifizierung. Benutzer-Endpunkte (/me/*) erfordern ein JWT. OAuth-Ablauf:

1. Registrieren Sie eine App über POST /auth/apps (Admin) oder per Self-Service unter accounts.urantiahub.com/developer

2. Der Benutzer meldet sich unter accounts.urantiahub.com an

3. Tauschen Sie den Autorisierungscode gegen ein Zugriffstoken über POST /auth/token aus

4. Übergeben Sie das Token als Authorization: Bearer <token>

Zugriffstoken sind HS256-JWTs mit einer Gültigkeitsdauer von 7 Tagen. PKCE wird für browserbasierte Apps unterstützt.

Beobachtbarkeit

• Logging: BetterStack via @logtail/edge – strukturierte JSON-Logs mit Anforderungs-Metadaten

• Fehlerverfolgung: Globaler Fehler-Handler sendet Stack-Traces an BetterStack

• Gesundheitsprüfung: GET /health – überprüft die Datenbankverbindung

• Uptime: BetterStack Uptime-Monitor

Tech-Stack

• Laufzeit: Bun (Entwicklung) / Cloudflare Workers (Produktion)

• Framework: Hono + @hono/zod-openapi

• Datenbank: Supabase (PostgreSQL + pgvector)

• ORM: Drizzle

• Beobachtbarkeit: BetterStack (Logging, Uptime)

Entwicklung

# 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

Der Server läuft standardmäßig unter http://localhost:3000.

Bereitstellung

Bereitgestellt auf Cloudflare Workers. Erstmalige Einrichtung:

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

Bereitstellen:

bun run deploy

Daten

Inhalte stammen aus urantia-papers-json – 197 Papiere, 1.626 Abschnitte, über 14.500 Absätze mit Audio-Erzählung via audio.urantia.dev.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

Haftungsausschluss

Dies ist ein unabhängiges Community-Projekt von Adams Technologies LLC. Es ist nicht mit der Urantia Foundation verbunden, wird von ihr nicht unterstützt und steht in keiner Verbindung zu ihr. Der englische Originaltext von The Urantia Book ist gemeinfrei (Michael Foundation v. Urantia Foundation, 10th Cir. 2003). Jegliche Verwendung von "Urantia" erfolgt im Rahmen der nominativen fairen Verwendung zur Identifizierung des Gegenstands.