# CKJV API Retrieval Spec For AI Agents

This spec explains how AI agents should retrieve exact CKJV Bible text from
this site.

Base URL:

```text
https://ckjv-web.pages.dev
```

## Preferred Retrieval Method

Use the JSON API for single verses and same-chapter verse ranges.

Single verse:

```text
GET /api/verses/{book}/{chapter}/{verse}.json
```

Same-chapter range:

```text
GET /api/verses/{book}/{chapter}/{start}-{end}.json
```

Examples:

```text
GET /api/verses/genesis/1/1.json
GET /api/verses/genesis/1/1-3.json
GET /api/verses/john/3/16.json
GET /api/verses/1-corinthians/13/4-7.json
```

## Book Slugs

Use English book slugs in URLs. Slugs are derived from the `englishName` in
`/data/manifest.json`:

1. Lowercase the English name.
2. Replace non-alphanumeric runs with `-`.
3. Trim leading or trailing `-`.

Examples:

```text
Genesis -> genesis
John -> john
Psalms -> psalms
1 Samuel -> 1-samuel
1 Corinthians -> 1-corinthians
Song of Solomon -> song-of-solomon
```

Chinese book ids are accepted for compatibility, but English slugs are the
preferred canonical API form.

## Accepted Book Slugs

- `genesis` - Genesis (`创`, 创世记)
- `exodus` - Exodus (`出`, 出埃及记)
- `leviticus` - Leviticus (`利`, 利未记)
- `numbers` - Numbers (`民`, 民数记)
- `deuteronomy` - Deuteronomy (`申`, 申命记)
- `joshua` - Joshua (`书`, 约书亚记)
- `judges` - Judges (`士`, 士师记)
- `ruth` - Ruth (`得`, 路得记)
- `1-samuel` - 1 Samuel (`撒上`, 撒母耳记上)
- `2-samuel` - 2 Samuel (`撒下`, 撒母耳记下)
- `1-kings` - 1 Kings (`王上`, 列王纪上)
- `2-kings` - 2 Kings (`王下`, 列王纪下)
- `1-chronicles` - 1 Chronicles (`代上`, 历代志上)
- `2-chronicles` - 2 Chronicles (`代下`, 历代志下)
- `ezra` - Ezra (`拉`, 以斯拉记)
- `nehemiah` - Nehemiah (`尼`, 尼希米记)
- `esther` - Esther (`斯`, 以斯帖记)
- `job` - Job (`伯`, 约伯记)
- `psalms` - Psalms (`诗`, 诗篇)
- `proverbs` - Proverbs (`箴`, 箴言)
- `ecclesiastes` - Ecclesiastes (`传`, 传道书)
- `song-of-solomon` - Song of Solomon (`歌`, 雅歌)
- `isaiah` - Isaiah (`赛`, 以赛亚书)
- `jeremiah` - Jeremiah (`耶`, 耶利米书)
- `lamentations` - Lamentations (`哀`, 耶利米哀歌)
- `ezekiel` - Ezekiel (`结`, 以西结书)
- `daniel` - Daniel (`但`, 但以理书)
- `hosea` - Hosea (`何`, 何西阿书)
- `joel` - Joel (`珥`, 约珥书)
- `amos` - Amos (`摩`, 阿摩司书)
- `obadiah` - Obadiah (`俄`, 俄巴底亚书)
- `jonah` - Jonah (`拿`, 约拿书)
- `micah` - Micah (`弥`, 弥迦书)
- `nahum` - Nahum (`鸿`, 那鸿书)
- `habakkuk` - Habakkuk (`哈`, 哈巴谷书)
- `zephaniah` - Zephaniah (`番`, 西番雅书)
- `haggai` - Haggai (`该`, 哈该书)
- `zechariah` - Zechariah (`亚`, 撒迦利亚书)
- `malachi` - Malachi (`玛`, 玛拉基书)
- `matthew` - Matthew (`太`, 马太福音)
- `mark` - Mark (`可`, 马可福音)
- `luke` - Luke (`路`, 路加福音)
- `john` - John (`约`, 约翰福音)
- `acts` - Acts (`徒`, 使徒行传)
- `romans` - Romans (`罗`, 罗马书)
- `1-corinthians` - 1 Corinthians (`林前`, 哥林多前书)
- `2-corinthians` - 2 Corinthians (`林後`, 哥林多後书)
- `galatians` - Galatians (`加`, 加拉太书)
- `ephesians` - Ephesians (`弗`, 以弗所书)
- `philippians` - Philippians (`腓`, 腓立比书)
- `colossians` - Colossians (`西`, 歌罗西书)
- `1-thessalonians` - 1 Thessalonians (`帖前`, 帖撒罗尼迦前书)
- `2-thessalonians` - 2 Thessalonians (`帖後`, 帖撒罗尼迦後书)
- `1-timothy` - 1 Timothy (`提前`, 提摩太前书)
- `2-timothy` - 2 Timothy (`提後`, 提摩太後书)
- `titus` - Titus (`多`, 提多书)
- `philemon` - Philemon (`门`, 腓利门书)
- `hebrews` - Hebrews (`来`, 希伯来书)
- `james` - James (`雅`, 雅各书)
- `1-peter` - 1 Peter (`彼前`, 彼得前书)
- `2-peter` - 2 Peter (`彼後`, 彼得後书)
- `1-john` - 1 John (`约一`, 约翰一书)
- `2-john` - 2 John (`约二`, 约翰二书)
- `3-john` - 3 John (`约三`, 约翰三书)
- `jude` - Jude (`犹`, 犹大书)
- `revelation` - Revelation (`启`, 启示录)

## Successful Single-Verse Response

Request:

```text
GET /api/verses/genesis/1/1.json
```

Response shape:

```json
{
  "version": "CKJV",
  "reference": "创1:1",
  "book": {
    "id": "创",
    "name": "创世记",
    "englishName": "Genesis",
    "slug": "genesis"
  },
  "chapter": 1,
  "verse": 1,
  "text": "起初，　神创造天地。",
  "attribution": "《中文英王欽定本》 by ckjv.asia",
  "license": "CC BY-SA 3.0",
  "source": "https://ckjv.asia/"
}
```

Use `text` as the exact CKJV verse text.

## Successful Range Response

Request:

```text
GET /api/verses/genesis/1/1-3.json
```

Response shape:

```json
{
  "version": "CKJV",
  "reference": "创1:1-3",
  "book": {
    "id": "创",
    "name": "创世记",
    "englishName": "Genesis",
    "slug": "genesis"
  },
  "chapter": 1,
  "verse": 1,
  "endVerse": 3,
  "verses": [
    {
      "verse": 1,
      "text": "起初，　神创造天地。"
    }
  ],
  "text": "起初，　神创造天地。\n...",
  "attribution": "《中文英王欽定本》 by ckjv.asia",
  "license": "CC BY-SA 3.0",
  "source": "https://ckjv.asia/"
}
```

For ranges, prefer `verses[]` when preserving verse numbers. Use `text` only
when a joined plain-text passage is desired.

## Errors

Errors are JSON responses.

Bad request:

```json
{
  "error": "bad_request",
  "message": "Chapter and verse must be positive numbers. Ranges must look like 1-3."
}
```

Not found:

```json
{
  "error": "not_found",
  "message": "Verse not found: 创1:999-999"
}
```

If an error is returned, do not invent or infer verse text. Tell the user the
reference was not found or request a corrected reference.

## Range Rules

Ranges are same-chapter only.

Valid:

```text
/api/verses/genesis/1/1-3.json
```

Invalid:

```text
/api/verses/genesis/1/31-2/1.json
```

For a cross-chapter passage, make multiple API calls and combine the results in
canonical order.

## Bulk Retrieval Fallback

For bulk use, avoid calling the Function repeatedly. Use static JSON files:

1. Fetch `/data/manifest.json`.
2. Find the requested book in `books[]`.
3. Fetch `/data/{book.file}`.
4. Read `chapters[String(chapter)]`.
5. Select matching verse objects.

Static data requests do not invoke the Pages Function.

## Quoting Rules

- Quote CKJV `text` exactly as returned.
- Preserve Chinese punctuation, full-width spaces, and wording.
- Do not modernize, paraphrase, summarize, normalize, or translate unless the
  user explicitly asks for that.
- When quoting CKJV text, include attribution:

```text
《中文英王欽定本》 by ckjv.asia, licensed under CC BY-SA 3.0.
```

## Agent Decision Guide

Use `/api/verses/...` when:

- The user asks for one verse.
- The user asks for a same-chapter range.
- You need a simple direct JSON response.

Use `/data/manifest.json` and book JSON when:

- The user asks for many passages.
- The user asks for a whole chapter or book.
- You need to minimize Function requests.
- The API endpoint is unavailable on the current host.