---
title: "Semantic search across the Bible (with UB paragraphs)"
method: POST
path: "/bible/search/semantic"
tags: ["Bible"]
---

# Semantic search across the Bible (with UB paragraphs)

`POST /bible/search/semantic`

Free-form natural-language search across all 17,641 Bible chunks. Each result includes the top-N pre-computed Urantia paragraphs related to that chunk via the existing cross-reference data, so a single query surfaces both the Bible matches and the relevant UB content.

Query is embedded via `text-embedding-3-small` (1536-d) and matched against `bible_chunks.embedding_small` with a pgvector HNSW index. Latency is ~50-100ms on cache miss for the embedding call, ~30ms cached.

Optional filters: `canon` (`ot`, `deuterocanon`, `nt`), `bookCode` (any OSIS/USFM/full-name/alias). `urantiaParallelLimit` controls how many UB paragraphs to attach per result (0-10, default 3). Set to 0 to suppress.

## Request body

- object
  - `q` string, required
  - `page` integer
  - `limit` integer
  - `canon` 'ot' | 'deuterocanon' | 'nt'
  - `bookCode` string
  - `urantiaParallelLimit` integer

## Response `200`

Bible semantic search results

- object
  - `data` object[], required
    - `id` string, required
    - `reference` string, required
    - `bookCode` string, required
    - `bookName` string, required
    - `canon` 'ot' | 'deuterocanon' | 'nt', required
    - `chapter` integer, required
    - `verseStart` integer, required
    - `verseEnd` integer, required
    - `text` string, required
    - `similarity` number, required
    - `urantiaParallels` object[], required
      - `id` string, required
      - `standardReferenceId` string, required
      - `paperId` 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

## Other responses

- `400` — Invalid request
- `500` — Internal server error

---

[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-service-production.skmtc.workers.dev/v1/apis/urantia/urantia-papers-api/revisions/6a8c13929fda/schema)