Skip to main content
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"

​
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.

​
MCP Servers

MCP Servers

Connect AI agents to the Urantia Book via 2 MCP servers — 13 API tools + docs search. Full setup instructions, tool reference, and example prompts.

​
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.