# Shepherd Bible API

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

## Overview

The Shepherd Bible API provides access to multiple Bible translations 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

## 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": 3, "name": "English Standard Version", "abbreviation": "ESV" },
    { "id": 4, "name": "King James Version", "abbreviation": "KJV" },
    { "id": 34, "name": "New American Standard Bible", "abbreviation": "NASB" },
    { "id": 1, "name": "New International Version", "abbreviation": "NIV" },
    { "id": 35, "name": "New King James Version", "abbreviation": "NKJV" },
    { "id": 2, "name": "New Living Translation", "abbreviation": "NLT" }
  ]
}
```

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

Get all books with their available chapters for a translation.

**Parameters:**
- `translation` (path, required): Translation abbreviation (KJV, ESV, NIV, etc.)

**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
- Only available for KJV and ESV translations
- 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 all translations.

**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)

**Response:**
```json
{
  "data": [
    {
      "translation": "NIV",
      "book": "1 Chronicles",
      "chapter": 16,
      "verse": 34,
      "text": "Give thanks to the Lord, for he is good; his love endures forever."
    },
    {
      "translation": "KJV",
      "book": "John",
      "chapter": 3,
      "verse": 16,
      "text": "For God so loved the world..."
    }
  ]
}
```

## Available Translations

- KJV (King James Version) - Red Letter supported
- ESV (English Standard Version) - Red Letter supported
- NIV (New International Version)
- NLT (New Living Translation)
- NASB (New American Standard Bible)
- NKJV (New King James Version)

## 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" in all translations:**
```bash
curl "https://bible.simplecohortllc.com/api/v1/search?q=love&page=1"
```

## Stats

- 6 Bible translations
- 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