> ## Documentation Index
> Fetch the complete documentation index at: https://urantia.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agent Integration - RAG & LLM Patterns for Urantia Book

> Recommended patterns for integrating Urantia Book content into AI agents, RAG pipelines, and LLM applications.

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

## Recommended flow

<Steps>
  <Step title="Understand the structure">
    Call `GET /toc` to get the full table of contents — parts, papers, and their titles.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Get surrounding context">
    For each relevant result, call `GET /paragraphs/:ref/context?window=3` to get paragraphs before and after. This improves comprehension significantly.
  </Step>

  <Step title="Read full papers if needed">
    Use `GET /papers/:id` to read an entire paper when the topic warrants it.
  </Step>
</Steps>

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

```bash theme={null}
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).

```bash theme={null}
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](https://urantiapedia.org) by [Jan Herca](https://github.com/JanHerca).

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:

```bash theme={null}
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`:

```bash theme={null}
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.

```bash theme={null}
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.

<CodeGroup>
  ```ts OpenAI theme={null}
  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
  });
  ```

  ```ts Anthropic theme={null}
  const { tools } = await fetch("https://api.urantia.dev/tools/anthropic").then(r => r.json());

  const message = await anthropic.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 1024,
    tools, // 19 tools, ready to go
    messages,
  });
  ```
</CodeGroup>

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

<Card title="MCP Servers" icon="plug" href="/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.
</Card>

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