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

# API Reference - Urantia Book REST API Documentation

> Complete REST API reference for the Urantia Papers API. 17 endpoints, no auth required, 200 req/min, CDN cached.

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

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

## Interactive docs

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