> ## 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 Papers REST API

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

## Usage and license

You can use the API for any lawful purpose, including commercial projects. The English text of the Urantia Papers is in the public domain, and everything else the API serves (audio, embeddings, entity descriptions) is dedicated to the public domain under CC0 1.0. See the [Terms of Service](/terms-of-service).

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

## Postman

The [Urantia Papers workspace on Postman](https://www.postman.com/urantia-dev/urantia-papers) has one collection with 28 requests. Each request has real example values and runs as is.


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