EGH Research API Documentation

Complete REST API reference for offline access to Ellen Gould Harmon's writings

🚀 Quick Start

Docker (Recommended)

# Pull and run
docker pull ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest
docker run -p 3000:3000 ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest

# Test the API
curl http://localhost:3000/health

Local Development

# Clone and build
git clone https://github.com/GospelSounders/egh-research.git
cd egh-research
pnpm install && pnpm build

# Start server
cd apps/local-server
npm run start:http

📋 API Overview

Base URL

http://localhost:3000

Content Type

application/json

Authentication

None required (local)

🏥 System Endpoints

GET/health

Returns server health status and database statistics

Example Response
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "database": {
    "books": 150,
    "paragraphs": 125000,
    "languages": 12
  }
}
GET/api/docs

Returns interactive API documentation with all available endpoints

GET/stats

Returns detailed database and server statistics including PDF job information

📚 Content Endpoints

GET/content/books

List books with pagination support

Query Parameters

  • page (number, optional): Page number (default: 1)
  • limit (number, optional): Items per page (default: 100)
  • lang (string, optional): Language code (default: en)
  • folder (string, optional): Filter by folder/category
Example Request & Response

Request:

GET /content/books?page=1&limit=5&lang=en

Response:

{
  "count": 150,
  "ipp": 5,
  "next": "http://localhost:3000/content/books?lang=en&limit=5&page=2",
  "previous": null,
  "results": [
    {
      "book_id": 1,
      "title": "The Acts of the Apostles",
      "author": "Ellen G. White",
      "pub_year": "1911",
      "lang": "en",
      "npages": 594,
      "files": {
        "pdf": "/content/books/1/generate-pdf",
        "download": "/content/books/1/download"
      }
    }
  ]
}
GET/content/books/{id}

Get detailed information about a specific book

GET/content/books/{id}/toc

Get table of contents for a book

GET/content/books/{id}/chapters/{chapter}

Get content for a specific chapter

📄 PDF Generation

POST/content/books/{id}/generate-pdf

Start PDF generation for a book with custom formatting options

Request Body & Response

Request Body (optional):

{
  "config": {
    "pageSize": "A4",
    "fontSize": 12,
    "fontFamily": "Times",
    "margins": {
      "top": 72,
      "bottom": 72,
      "left": 72,
      "right": 72
    },
    "toc": {
      "generate": true,
      "maxDepth": 2
    },
    "pagination": {
      "show": true,
      "style": "bottom-center"
    }
  }
}

Response:

{
  "token": "abc123-def456-ghi789",
  "status": "queued",
  "message": "PDF generation started",
  "statusUrl": "/pdf/status/abc123-def456-ghi789",
  "downloadUrl": "/pdf/download/abc123-def456-ghi789"
}
GET/pdf/status/{token}

Check the status of a PDF generation job

Example Response
{
  "token": "abc123-def456-ghi789",
  "status": "generating",
  "progress": 45,
  "stage": "processing-chapters",
  "currentChapter": "Chapter 15",
  "totalChapters": 58,
  "estimatedTimeRemaining": "2 minutes",
  "createdAt": "2024-01-15T10:30:00.000Z"
}
GET/pdf/download/{token}

Download the generated PDF file (only available when status is "completed")

🔍 Search

GET/search

Perform full-text search across all content with FTS5 support

Query Parameters

  • q (string, required): Search query
  • limit (number, optional): Maximum results (default: 20)
  • offset (number, optional): Result offset (default: 0)
Example Request & Response

Request:

GET /search?q=righteousness%20by%20faith&limit=5

Response:

{
  "query": "righteousness by faith",
  "total": 284,
  "limit": 5,
  "offset": 0,
  "results": [
    {
      "book_id": 15,
      "title": "Steps to Christ",
      "author": "Ellen G. White",
      "reference": "SC 62.2",
      "snippet": "...justification by <mark>faith</mark>, or <mark>righteousness</mark> by <mark>faith</mark>, is the act of God...",
      "url": "/content/books/15"
    }
  ]
}

⚠️ Error Handling

All errors follow a consistent JSON format:

{
  "error": "Book not found",
  "status": 404,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Common HTTP Status Codes

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 404 - Not Found (book, PDF job, etc.)
  • 500 - Internal Server Error

💻 SDK Examples

JavaScript/Node.js

// Search for content
const response = await fetch(
  'http://localhost:3000/search?q=righteousness'
);
const data = await response.json();

// Generate PDF
const pdfResponse = await fetch(
  'http://localhost:3000/content/books/1/generate-pdf',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      config: { pageSize: 'A4', fontSize: 12 }
    })
  }
);
const pdfJob = await pdfResponse.json();

Python

import requests

# Search for content
response = requests.get(
    'http://localhost:3000/search',
    params={'q': 'righteousness', 'limit': 10}
)
data = response.json()

# Generate PDF
pdf_response = requests.post(
    'http://localhost:3000/content/books/1/generate-pdf',
    json={
        'config': {'pageSize': 'A4', 'fontSize': 12}
    }
)
pdf_job = pdf_response.json()

🐳 Docker & Deployment

Production Deployment

# Pull latest image
docker pull ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest

# Run with persistent storage
docker run -d \
  --name egh-research \
  -p 3000:3000 \
  -v egh-data:/app/apps/local-server/data \
  --restart unless-stopped \
  ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest

Docker Compose

# Download compose file
curl -O https://raw.githubusercontent.com/GospelSounders/egw-writings-mcp/master/apps/local-server/docker-compose.yml

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

Questions or need help? Check out our resources:

GitHub RepositoryReport IssuesDiscussions