Skip to main content

Documentation Index

Fetch the complete documentation index at: https://urantia.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Urantia Papers API is designed for AI agent consumption. Here’s the recommended workflow.
1

Understand the structure

Call GET /toc to get the full table of contents — parts, papers, and their titles.
2

Search for relevant passages

Use POST /search for keyword matching, or POST /search/semantic for meaning-based similarity search. Semantic search finds conceptually related passages even without exact keyword matches — ideal for natural language queries from users.
3

Get surrounding context

For each relevant result, call GET /paragraphs/:ref/context?window=3 to get paragraphs before and after. This improves comprehension significantly.
4

Read full papers if needed

Use GET /papers/:id to read an entire paper when the topic warrants it.

​
Search tips

​
Full-text search (POST /search)

Best for keyword-based queries. Supports three modes:
  • and (default) — all words must appear. Best for specific queries.
  • or — any word can appear. Best for broad exploratory queries.
  • phrase — exact phrase match. Best when quoting specific text.
curl -X POST https://api.urantia.dev/search \
  -H "Content-Type: application/json" \
  -d '{"q": "thought adjuster", "type": "and", "limit": 10}'

​
Semantic search (POST /search/semantic)

Best for natural language queries. Uses vector embeddings to find conceptually similar passages, even when the exact words don’t match. Returns results ranked by similarity (0-1). 
curl -X POST https://api.urantia.dev/search/semantic \
  -H "Content-Type: application/json" \
  -d '{"q": "what happens after death", "limit": 10}'
Both search endpoints support paperId and partId filters to narrow scope.

​
Entity lookup

The API catalogs 4,400+ named entities — beings, places, orders, races, religions, and concepts — with descriptions and cross-references, sourced from Urantiapedia by Jan Herca. Use GET /entities?q=<name> to find entities by name, or GET /entities?type=being to browse by type. Each entity includes a citationCount showing how often it appears. To find every paragraph that mentions an entity: 
curl https://api.urantia.dev/entities/thought-adjusters/paragraphs
This is useful for building knowledge graphs, entity-aware RAG, or letting users explore topics by entity. You can also include entity mentions inline on any paragraph-returning endpoint by adding ?include=entities (or "include": "entities" in search request bodies). Each entity includes an id, name, and type: 
curl "https://api.urantia.dev/paragraphs/2:0.1?include=entities"

​
Bible cross-references

The API hosts the World English Bible (38,034 verses, 81 books) alongside pre-computed UB↔Bible and UB↔UB semantic cross-references. Two ways to wire this into an agent: 1. Enrich any Urantia result inline. Add ?include=bibleParallels and/or ?include=urantiaParallels to any paragraph-returning endpoint (/paragraphs/{ref}, /paragraphs/random, /search, /search/semantic) to get the top-10 semantically nearest Bible verses and/or Urantia paragraphs attached to each result. 
curl "https://api.urantia.dev/paragraphs/2:0.1?include=entities,bibleParallels,urantiaParallels"
2. Start from a Bible verse. GET /bible/{bookCode}/{chapter}/{verse}/urantia-parallels returns the top-10 Urantia paragraphs nearest a given verse. POST /bible/search/semantic does free-form semantic search over the Bible and joins each hit against the UB cross-references in one request — useful when a user asks a Bible-shaped question and you want to surface the Urantia perspective alongside. These are semantic neighbors (computed with text-embedding-3-large), not curated linguistic parallels — top results are conceptually related (e.g. Matt 5:3 ↔ UB 140:3.3 at 0.854). Use them as RAG candidates, not as authoritative citations.

​
Context window

The /paragraphs/:ref/context endpoint is particularly useful for RAG. It returns the target paragraph plus surrounding paragraphs (configurable via the window parameter, 1-10). This provides the LLM with the narrative flow around a passage, which leads to more accurate and contextual responses.

​
Function-calling schemas

If you’re working directly with the OpenAI or Anthropic SDKs (rather than going through MCP), the API publishes ready-to-use tool definitions for both. Drop them straight into your tools array — no manual schema authoring required. 
const { tools } = await fetch("https://api.urantia.dev/tools/openai").then(r => r.json());

const completion = await openai.chat.completions.create({
  model: "gpt-5",
  messages,
  tools, // 19 tools, ready to go
});
Each tool corresponds 1:1 with an MCP tool, so you can dispatch the call against either the REST API or the published @urantia/api SDK.

​
MCP Servers

MCP Servers

Connect AI agents to the Urantia Book via 2 MCP servers — 19 tools + 2 resources + 2 prompts on the API server, plus docs search. One-click install via Smithery.

​
OpenAPI spec

The full OpenAPI 3.1 specification is available at: 
https://api.urantia.dev/openapi.json
Use this to auto-generate typed clients in any language.