API_DOCUMENTATION.md

Biblos Semantic Search API Documentation

Complete documentation for integrating the Biblos Semantic Search API into your applications.

Base URL

https://dssjon-biblos-api.hf.space

The API is live and publicly accessible at the URL above.

---

Endpoints

1. Health Check

GET /

Returns API status and basic information.

Response:

{
  "status": "online",
  "model": "BAAI/bge-large-en-v1.5",
  "books_loaded": 66,
  "total_embeddings": 6407,
  "device": "cpu"
}

Example:

curl https://dssjon-biblos-api.hf.space/

---

2. Detailed Health Check

GET /health

Returns detailed health status and list of available books.

Response:

{
  "model_loaded": true,
  "tokenizer_loaded": true,
  "embeddings_loaded": true,
  "books_available": ["gen", "exo", "lev", ...]
}

Example:

curl https://dssjon-biblos-api.hf.space/health

---

3. Semantic Search

POST /search

Perform semantic search over the entire Bible (both Old and New Testament).

Request Body

Field	Type	Required	Description
query	string	Yes	Search query text (1-500 chars)
limit	integer	No	Number of results (1-100, default: 10)

Response

{
  "query": "string",
  "results": [
    {
      "book": "string",
      "chapter": integer,
      "testament": "string",
      "content": "string",
      "similarity": float
    }
  ],
  "total_searched": integer,
  "execution_time_ms": float
}

Example

curl -X POST https://dssjon-biblos-api.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "faith without works is dead",
    "limit": 5
  }'

---

Integration Examples

JavaScript/TypeScript

Basic Fetch

async function searchBible(query, limit = 10) {
  const response = await fetch('https://dssjon-biblos-api.hf.space/search', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query,
      limit
    })
  })

  if (!response.ok) {
    throw new Error(`Search failed: ${response.status}`)
  }

  return await response.json()
}

// Usage
const results = await searchBible('love one another', 5)

console.log(results)

React Hook

import { useState, useCallback } from 'react'

interface SearchResult {
  book: string
  chapter: number
  testament: string
  content: string
  similarity: number
}

export function useBibleSearch() {
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState<Error | null>(null)

  const search = useCallback(async (
    query: string,
    limit: number = 10
  ): Promise<SearchResult[]> => {
    setLoading(true)
    setError(null)

    try {
      const response = await fetch('https://dssjon-biblos-api.hf.space/search', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ query, limit })
      })

      if (!response.ok) {
        throw new Error(`Search failed: ${response.status}`)
      }

      const data = await response.json()
      return data.results
    } catch (err) {
      const error = err instanceof Error ? err : new Error('Unknown error')
      setError(error)
      throw error
    } finally {
      setLoading(false)
    }
  }, [])

  return { search, loading, error }
}

// Usage in component
function SearchComponent() {
  const { search, loading, error } = useBibleSearch()
  const [results, setResults] = useState([])

  const handleSearch = async (query: string) => {
    const results = await search(query, 10)
    setResults(results)
  }

  return (
    // Your component JSX
  )
}

---

Python

Basic Example

import requests

def search_bible(query, limit=10):
    """
    Search the Bible using semantic search

    Args:
        query: Search query text
        limit: Number of results to return

    Returns:
        List of search results
    """
    url = 'https://dssjon-biblos-api.hf.space/search'

    payload = {
        'query': query,
        'limit': limit
    }

    response = requests.post(url, json=payload)
    response.raise_for_status()

    return response.json()

# Usage
results = search_bible(
    query='faith and works',
    limit=5
)

for result in results['results']:
    print(f"{result['book'].upper()} {result['chapter']}")
    print(f"Similarity: {result['similarity']:.3f}")
    print(f"Content: {result['content']}")
    print()

Async Example

import asyncio
import aiohttp

async def search_bible_async(query, limit=10):
    """Async version of Bible search"""
    url = 'https://dssjon-biblos-api.hf.space/search'

    payload = {'query': query, 'limit': limit}

    async with aiohttp.ClientSession() as session:
        async with session.post(url, json=payload) as response:
            response.raise_for_status()
            return await response.json()

# Usage
async def main():
    results = await search_bible_async('love your neighbor', limit=5)
    print(results)

asyncio.run(main())

---

cURL

curl -X POST https://dssjon-biblos-api.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "blessed are the peacemakers",
    "limit": 3
  }' | jq '.results[] | "\(.book) \(.chapter) - \(.content)"'

---

Error Handling

HTTP Status Codes

Code	Description
200	Success
400	Bad Request (invalid parameters)
405	Method Not Allowed
500	Internal Server Error
503	Service Unavailable (model not loaded)

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

Example Error Handling (JavaScript)

async function safeSearch(query) {
  try {
    const response = await fetch('https://dssjon-biblos-api.hf.space/search', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query })
    })

    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.detail || 'Search failed')
    }

    return await response.json()
  } catch (error) {
    console.error('Search error:', error.message)
    return null
  }
}

---

Performance Considerations

Response Times

• First request: 2-3 seconds (model loading)
• Subsequent requests: 50-100ms average
• Cold start: None (model stays in memory)

Best Practices

1. Cache results on the client side when possible
2. Debounce search queries to reduce API calls
3. Implement pagination for large result sets
4. Use appropriate limits - higher limits increase response time
5. The API searches the entire Bible (both Old and New Testament) for comprehensive results

Rate Limiting

Currently no rate limiting is enforced, but please use responsibly:

• Avoid making more than 10 requests per second
• Implement exponential backoff on errors
• Cache results when appropriate

---

Interactive Documentation

Visit your Space URL at /docs for interactive Swagger UI documentation where you can:

• Test all endpoints directly in the browser
• See detailed schema information
• Try different parameter combinations
• View real-time responses

Live Interactive Docs: https://dssjon-biblos-api.hf.space/docs

---

Support

For issues, questions, or feature requests:

1. Check the interactive docs at /docs
2. Review this documentation
3. Open an issue on the GitHub repository
4. Contact the maintainer

---

Version

API Version: 1.0.0 Model: BAAI/bge-large-en-v1.5 Last Updated: 2025