# Shepherd Bible API

> A RESTful API for building Bible applications with Red Letter precision

## Overview

The Shepherd Bible API provides access to the King James Version (KJV) with unique features including Red Letter data (character ranges marking Jesus' words), chapter summaries, verse groupings, and full-text search.

- Base URL: https://bible.simplecohortllc.com
- Documentation: https://simplecohortllc.com/api-portal/docs
- Pricing: https://simplecohortllc.com/api-portal/pricing

## MCP Endpoint

- MCP URL (Streamable HTTP): https://bible.simplecohortllc.com/mcp
- Authentication: Optional `x-api-key` header (required for premium red-letter access and higher limits)
- Notes: Read-only tools for translations, books, chapters, verses, and search

## Authentication

- **Free Access**: No API key required. Unlimited requests but no Red Letter data.
- **Subscription Access**: Include `x-api-key` header with your API key (format: `bible_live_xxxxxxxxxxxx`)

## Rate Limits

| Plan | Requests | Red Letter Data |
|------|----------|-----------------|
| Free (no key) | Unlimited | No |
| Standard ($9.99/mo) | 1,000/day | Yes |
| Unlimited ($49.99/mo) | Unlimited | Yes |

## Endpoints

### GET /api/v1/translations

List all available Bible translations.

**Response:**
```json
{
  "data": [
    { "id": 4, "name": "King James Version", "abbreviation": "KJV" }
  ]
}
```

### GET /api/v1/translations/:translation/books

Get all books with their available chapters for a translation.

**Parameters:**
- `translation` (path, required): Translation abbreviation (currently `KJV`)

**Response:**
```json
{
  "data": {
    "Genesis": [1, 2, 3, 4, 5, "...up to 50"],
    "Exodus": [1, 2, 3, 4, 5, "...up to 40"],
    "John": [1, 2, 3, 4, 5, "...up to 21"]
  }
}
```

Note: Each book maps to an array of available chapter numbers.

### GET /api/v1/chapters/:translation/:book/:chapter

Get a full chapter with verses and Red Letter data.

**Parameters:**
- `translation` (path, required): Translation abbreviation
- `book` (path, required): Book name (e.g., "John", "Genesis")
- `chapter` (path, required): Chapter number

**Headers:**
- `x-api-key` (optional): Required for Red Letter data access

**Response:**
```json
{
  "data": {
    "translation": "KJV",
    "book": "John",
    "chapter": 3,
    "verses": [
      {
        "verse": 1,
        "text": "There was a man of the Pharisees, named Nicodemus, a ruler of the Jews:"
      },
      {
        "verse": 16,
        "text": "For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life."
      }
    ]
  }
}
```

**Red Letter Data:**
- `jesusWordsRanges`: Array of character ranges (0-based indices) marking Jesus' words
- Available for the KJV translation
- Requires subscription (Standard or Unlimited plan)

### GET /api/v1/verses/:translation/:book/:chapter/:verse

Get a single verse.

**Parameters:**
- `translation` (path, required): Translation abbreviation
- `book` (path, required): Book name
- `chapter` (path, required): Chapter number
- `verse` (path, required): Verse number

**Response:**
```json
{
  "data": {
    "book": "John",
    "chapter": 3,
    "verse": 16,
    "translation": "KJV",
    "text": "For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.",
    "jesusWordsRanges": "[{\"start\":0,\"end\":141,\"text\":\"For God so loved...\"}]"
  },
  "hasRedLetterAccess": false
}
```

Note: `jesusWordsRanges` is returned as a JSON string. `hasRedLetterAccess` indicates whether the ranges are accessible (requires subscription).

### GET /api/v1/search

Full-text search across the KJV.

**Parameters:**
- `q` (query, required): Search query string
- `page` (query, optional): Page number (default: 1)
- `type` (query, optional): Search type - "exact" or "jesus" (Jesus' words only, requires subscription)
- `translation` (query, optional): Translation abbreviation (default: `KJV`)
- `book` (query, optional): Restrict results to a single book

**Response:**
```json
{
  "data": [
    {
      "translation": "KJV",
      "book": "John",
      "chapter": 3,
      "verse": 16,
      "text": "For God so loved the world..."
    }
  ]
}
```

## Available Translations

- KJV (King James Version) - Red Letter supported

Additional translations will be added as publisher licensing permits.

## Red Letter Data Implementation

Red Letter data marks Jesus' words in Scripture using character ranges. Example React implementation:

```jsx
function VerseWithRedLetters({ text, jesusWordsRanges }) {
  if (!jesusWordsRanges?.length) return <span>{text}</span>;

  let result = [];
  let lastIndex = 0;

  jesusWordsRanges.forEach(({ start, end }, i) => {
    if (start > lastIndex) {
      result.push(<span key={`t${i}`}>{text.slice(lastIndex, start)}</span>);
    }
    result.push(
      <span key={`r${i}`} style={{ color: 'red' }}>
        {text.slice(start, end)}
      </span>
    );
    lastIndex = end;
  });

  if (lastIndex < text.length) {
    result.push(<span key="end">{text.slice(lastIndex)}</span>);
  }

  return <>{result}</>;
}
```

## Example Requests

**Get all translations (free):**
```bash
curl https://bible.simplecohortllc.com/api/v1/translations
```

**Get John chapter 3 with Red Letter data (subscription required):**
```bash
curl -H "x-api-key: bible_live_xxxxxxxxxxxx" \
  https://bible.simplecohortllc.com/api/v1/chapters/KJV/John/3
```

**Search for "love" (defaults to KJV):**
```bash
curl "https://bible.simplecohortllc.com/api/v1/search?q=love&page=1"
```

## Stats

- KJV (King James Version)
- 66 books
- 31,000+ verses
- 99.9% uptime
- Fast response times

## Support

- Documentation: https://simplecohortllc.com/api-portal/docs
- Pricing & Plans: https://simplecohortllc.com/api-portal/pricing
- Manage Subscription: https://simplecohortllc.com/api-portal/manage