---
title: "Semantic search across the works"
method: POST
path: "/works/search/semantic"
tags: ["Works"]
---

# Semantic search across the works

`POST /works/search/semantic`

## Request

- Base URL: `https://api.urantia.dev`
- URL: `https://api.urantia.dev/works/search/semantic`
- Auth: none required

Natural-language search across the Bible and the other works, or one work with `work`. The list holds the 100 nearest chunks (a chunk is a few verses, about one Urantia paragraph long); each has `similarity` and `strength` (strong, related, weak), and `meta.total` is the length of that list, and `meta.related` counts those that are related or better. A reference gives those units with no vector. Each result carries its nearest Urantia paragraphs (`urantiaParallelLimit`, 0 to 10, default 3).

**The Urantia parallels are semantic, not curated.** They show the paragraphs closest in meaning by embedding similarity. They do not claim that two teachings are the same.

## Request body

- object
  - `q` string, required
  - `work` string: One work only: "bible" or a work id such as "dhammapada".
  - `page` integer
  - `limit` integer
  - `urantiaParallelLimit` integer

## Response `200`

Search results

- object
  - `data` object[], required
    - `work` object, required
      - `id` string, required
      - `title` string, required
      - `tradition` string, required
    - `reference` string, required: "John 3:16", "Dhp 183", "BG 2.47-49" (a chunk in semantic search).
    - `text` string, required
    - `url` string, nullable, required: The public page that holds the text, or null.
    - `match` 'reference' | 'exact' | 'all' | 'near': Keyword search: how it matched.
    - `similarity` number: Semantic search: cosine similarity.
    - `strength` 'strong' | 'related' | 'weak': How close the result is: strong (most right answers score this), related, or weak (likely off the topic).
    - `urantiaParallels` object[], required: The nearest Urantia paragraphs (semantic parallels, not curated ones).
      - `standardReferenceId` string, required
      - `paperTitle` string, required
      - `sectionTitle` string, nullable, required
      - `text` string, required
      - `similarity` number, required
      - `rank` integer, required
  - `meta` object, required
    - `page` integer, required
    - `limit` integer, required
    - `total` integer, required
    - `totalPages` integer, required
    - `didYouMean` string
    - `related` integer: Semantic search only: how many results of the list are related or better.

## Other responses

- `400`: Invalid request
- `429`: Too many requests
- `500`: Internal server error

## Changes

- **2026-10-19** `a7d08cd0de9f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/urantia/apis/urantia-papers-api/changes/works/search/semantic/post.md)

---

[API](https://skmtc.dev/urantia/apis/urantia-papers-api.md) - [All operations](https://skmtc.dev/urantia/apis/urantia-papers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/urantia/apis/urantia-papers-api/revisions/d046ecd9b449?raw)