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

# Quickstart - Urantia Book API in 60 Seconds

> Make your first Urantia Book API call in under a minute. Search paragraphs, look up references, and access audio narration.

<Card title="Try the Interactive Demo" icon="play" href="https://demo.urantia.dev">
  See all these examples running live at demo.urantia.dev
</Card>

## Get a random paragraph

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.urantia.dev/paragraphs/random
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { UrantiaAPI } from '@urantia/api'

    const api = new UrantiaAPI()
    const { data } = await api.paragraphs.random()

    console.log(data.text)
    console.log(data.standardReferenceId) // e.g., "107:0.1"
    ```

    Install: `npm install @urantia/api`
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch('https://api.urantia.dev/paragraphs/random')
    const data = await response.json()

    console.log(data.text)
    console.log(data.standardReferenceId)
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get('https://api.urantia.dev/paragraphs/random')
    data = response.json()

    print(data['text'])
    print(data['standardReferenceId'])
    ```
  </Tab>
</Tabs>

## Search the Urantia Papers

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.urantia.dev/search \
      -H "Content-Type: application/json" \
      -d '{"q": "Universal Father", "limit": 5}'
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { UrantiaAPI } from '@urantia/api'

    const api = new UrantiaAPI()
    const { data } = await api.search.fulltext({
      q: 'Universal Father',
      type: 'and',
      limit: 5
    })

    data.results.forEach(result => {
      console.log(result.text)
      console.log(result.standardReferenceId)
    })
    ```
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch('https://api.urantia.dev/search', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ q: 'Universal Father', limit: 5 })
    })
    const data = await response.json()

    data.results.forEach(result => {
      console.log(result.text)
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://api.urantia.dev/search',
        json={'q': 'Universal Father', 'limit': 5}
    )
    data = response.json()

    for result in data['results']:
        print(result['text'])
    ```
  </Tab>
</Tabs>

Search modes: `and` (all words, default), `or` (any word), `phrase` (exact match).

## Look up a specific paragraph

The API accepts three reference formats, detected from the string:

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.urantia.dev/paragraphs/1:2.0.1
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { UrantiaAPI } from '@urantia/api'

    const api = new UrantiaAPI()
    const { data } = await api.paragraphs.get({ ref: '1:2.0.1' })

    console.log(data.text)
    console.log(data.paperTitle)
    ```
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch('https://api.urantia.dev/paragraphs/1:2.0.1')
    const data = await response.json()

    console.log(data.text)
    ```
  </Tab>
</Tabs>

## Get a paragraph with surrounding context

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.urantia.dev/paragraphs/1:2.0.1/context?window=3"
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { UrantiaAPI } from '@urantia/api'

    const api = new UrantiaAPI()
    const { data } = await api.paragraphs.context({
      ref: '1:2.0.1',
      window: 3
    })

    // Array with target paragraph + 3 before + 3 after
    data.paragraphs.forEach(p => {
      console.log(`[${p.standardReferenceId}] ${p.text}`)
    })
    ```
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch(
      'https://api.urantia.dev/paragraphs/1:2.0.1/context?window=3'
    )
    const data = await response.json()

    data.paragraphs.forEach(p => console.log(p.text))
    ```
  </Tab>
</Tabs>

Returns the target paragraph plus 3 paragraphs before and after it, which is useful for RAG and AI applications.

## Browse entities

The API includes 4,400+ entities (beings, places, orders, races, religions, concepts) sourced from [Urantiapedia](https://urantiapedia.org), a knowledge graph built by [Jan Herca](https://github.com/JanHerca).

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # List entities, filter by type or search by name
    curl "https://api.urantia.dev/entities?type=being&limit=5"
    curl "https://api.urantia.dev/entities?q=adam"

    # Get a single entity
    curl https://api.urantia.dev/entities/adam-and-eve

    # Get all paragraphs mentioning an entity
    curl https://api.urantia.dev/entities/adam-and-eve/paragraphs
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { UrantiaAPI } from '@urantia/api'

    const api = new UrantiaAPI()

    // List entities
    const { data: beings } = await api.entities.list({ type: 'being', limit: 5 })
    const { data: search } = await api.entities.list({ q: 'adam' })

    // Get a single entity
    const { data: entity } = await api.entities.get({ id: 'adam-and-eve' })
    console.log(entity.name, entity.type, entity.description)

    // Get paragraphs mentioning this entity
    const { data: paragraphs } = await api.entities.paragraphs({
      id: 'adam-and-eve'
    })
    ```
  </Tab>
</Tabs>

You can also include entity mentions inline on any paragraph-returning endpoint with `?include=entities`:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.urantia.dev/paragraphs/2:0.1?include=entities"
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    const { data } = await api.paragraphs.get({
      ref: '2:0.1',
      include: 'entities'
    })

    // Each entity has id, name, type
    data.entities?.forEach(entity => {
      console.log(entity.name, entity.type)
    })
    ```
  </Tab>
</Tabs>

## Read a full paper

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.urantia.dev/papers/1
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { UrantiaAPI } from '@urantia/api'

    const api = new UrantiaAPI()
    const { data } = await api.papers.get({ id: '1' })

    console.log(data.title)
    data.paragraphs.forEach(p => {
      console.log(`[${p.standardReferenceId}] ${p.text}`)
    })
    ```
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```javascript theme={null}
    const response = await fetch('https://api.urantia.dev/papers/1')
    const data = await response.json()

    console.log(data.title)
    data.paragraphs.forEach(p => console.log(p.text))
    ```
  </Tab>
</Tabs>

Returns the paper metadata and all its paragraphs in order.

## Next Steps

<CardGroup cols={2}>
  <Card title="Build a Daily Quote Bot" icon="robot" href="/blog/daily-quote-bot">
    10-minute tutorial: create a bot that shares Urantia quotes
  </Card>

  <Card title="TypeScript SDKs" icon="code" href="/sdks/overview">
    Install @urantia/api and @urantia/auth from npm
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Full documentation for all 24 endpoints
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/use-cases">
    Ideas and examples for what you can build
  </Card>

  <Card title="Changelog" icon="clock" href="/changelog">
    See what's new in the API and docs
  </Card>
</CardGroup>


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