API Reference - Urantia Book REST API Documentation

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.

Error responses

All errors follow RFC 9457 Problem Details with Content-Type: application/problem+json:

{
  "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:

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

Interactive docs

Try endpoints directly in the Swagger UI or use the interactive examples on each endpoint page below.

Overview

Table of Contents

Papers

Paragraphs

Entities

Search

Bible

Audio

Citation

OG Images

Embeddings

Feedback

API Reference - Urantia Book REST API Documentation

Base URL

Authentication

Rate limiting

Error responses

Caching

Paragraph ID formats

RAG-optimized format

Feedback

Interactive docs

​Base URL

​Authentication

​Rate limiting

​Error responses

​Caching

​Paragraph ID formats

​RAG-optimized format

​Feedback

​Interactive docs

Base URL

Authentication

Rate limiting

Error responses

Caching

Paragraph ID formats

RAG-optimized format

Feedback

Interactive docs