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

# API Reference - Urantia Book REST API Documentation

> REST API reference for the Urantia Papers API. No key needed, 200 requests per minute, cached at the edge.

## Base URL

```
https://api.urantia.dev
```

## Authentication

No authentication is required. The API is free and open.

## Rate limiting

Requests are rate limited to **200 requests per minute** per IP address. Rate limit headers are included in every response:

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | Maximum requests per window (200) |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |

If you exceed the limit, you'll receive a `429` response.

`POST /feedback` has its own, lower limit: 5 requests per minute and 10 per 15 minutes. See [Feedback](/feedback).

## Error responses

All errors follow [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`:

```json theme={null}
{
  "type": "https://urantia.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Paragraph \"999:999.999\" not found"
}
```

| Field | Description |
| - | - |
| `type` | URI identifying the error type |
| `title` | Short human-readable summary |
| `status` | HTTP status code |
| `detail` | Specific explanation for this occurrence |

## Caching

All responses include `Cache-Control` headers. Cloudflare's CDN caches responses at the edge using `s-maxage`, so repeated requests are served from the nearest edge node without hitting the origin.

| Route | CDN cache | Browser cache |
| - | - | - |
| `/toc`, `/papers/*`, `/paragraphs/:ref`, `/audio/*`, `/cite`, `/entities/*`, `/embeddings/*` | 24 hours | 1 hour |
| `/og/:ref` | Permanent (immutable) | Permanent |
| `/search` | 1 hour | 5 minutes |
| `/paragraphs/random` | None | None |
| `/`, `/docs`, `/openapi.json` | 1 hour | 5 minutes |

Static content (papers, paragraphs, audio, OG images) is immutable, so it's cached aggressively. The random endpoint is never cached.

## Paragraph ID formats

Many endpoints accept paragraph references in three auto-detected formats:

| Format | Example | Structure |
| - | - | - |
| globalId | `1:2.0.1` | `partId:paperId.sectionId.paragraphId` |
| standardReferenceId | `2:0.1` | `paperId:sectionId.paragraphId` |
| paperSectionParagraphId | `2.0.1` | `paperId.sectionId.paragraphId` |

## RAG-optimized format

Paragraph endpoints support `?format=rag` to return a streamlined shape for AI/RAG pipelines:

```json theme={null}
{
  "data": {
    "ref": "1:0.1",
    "text": "plain text",
    "citation": "The Urantia Book, Paper 1, Section 0, Paragraph 1",
    "metadata": { "paperId": "1", "paperTitle": "...", "sectionId": "0", ... },
    "navigation": { "prev": null, "next": "1:0.2" },
    "tokenCount": 142,
    "entities": ["Universal Father"]
  }
}
```

Works on `GET /paragraphs/:ref?format=rag` and `GET /paragraphs/random?format=rag`.

## Feedback

Found a bug or a gap in these docs? Send it to `POST /feedback`. No authentication required. See [Feedback](/feedback).

## Interactive docs

Try endpoints directly in the [Swagger UI](https://api.urantia.dev/docs) or use the interactive examples on each endpoint page below.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.