Introduction

The BAF (Bible AI Framework) API provides AI-powered context resolution for biblical narratives. Our API automatically detects characters, eras, locations, and themes from scripture text to help create accurate visual representations.

Base URL: https://api.midown.pro

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header of every request.

Request Header

Authorization: Bearer tk_your-tenant_live_your-api-key

API Key Format

API keys follow the format: tk_[tenant-id]_[environment]_[32-char-hex]

tk_ - Fixed prefix
tenant-id - Your account identifier
live_ or test_ - Environment indicator
32-char-hex - Unique key identifier

Security: Never expose your API key in client-side code. Always make API calls from your backend server.

Rate Limits

Rate limits vary by plan:

Plan	Requests/Month	Requests/Minute
Free	1,000	10
Pro	50,000	60
Ultra	500,000	300

Shot Context

The primary endpoint for resolving biblical context from scripture references. Returns characters, era, location, and visual themes.

Endpoint

POST /api/shots/context

Request Body

{
  "project": "ESTHER",
  "verseRef": "EST.1.1",
  "shotText": "King Xerxes sat on the royal throne in the citadel of Susa",
  "language": "en"
}

Parameters

Parameter	Type	Required	Description
`project`	string	No	Project identifier (e.g., ESTHER, GENESIS)
`verseRef`	string	Yes	Bible verse reference (e.g., GEN.1.1, EST.1.1)
`shotText`	string	Yes	The text/description of the scene
`language`	string	No	Language code (default: "en")

Response

{
  "success": true,
  "data": {
    "project": "ESTHER",
    "era": {
      "era_key": "PERSIAN_EMPIRE_480BC",
      "display_name": "Persian Empire",
      "year_range": "486-465 BC",
      "cultural_context": "Achaemenid Persian Empire"
    },
    "characters": [
      {
        "character_id": "XERXES_I",
        "display_name": "King Xerxes I",
        "role": "primary",
        "appearance": {
          "age": "adult",
          "gender": "male",
          "clothing": "Persian royal robes",
          "accessories": ["crown", "scepter"]
        }
      }
    ],
    "location": {
      "location_id": "SUSA_PALACE",
      "display_name": "Palace of Susa",
      "type": "palace",
      "region": "Persia"
    },
    "visualContext": {
      "timeOfDay": "day",
      "mood": "royal",
      "themes": ["royalty", "power", "opulence"]
    }
  }
}

Characters

Retrieve information about biblical characters.

List Characters

GET /api/characters

Get Character by ID

GET /api/characters/:characterId

Search Characters

GET /api/characters/search?q=moses&era=EXODUS_1446BC

Eras

Access historical era information.

List All Eras

GET /api/eras

Response

{
  "success": true,
  "data": [
    {
      "era_key": "CREATION",
      "display_name": "Creation",
      "year_range": "Beginning",
      "description": "The creation of the world"
    },
    {
      "era_key": "PATRIARCHS_2000BC",
      "display_name": "Patriarchal Period",
      "year_range": "2000-1800 BC",
      "description": "Era of Abraham, Isaac, and Jacob"
    }
    // ... more eras
  ]
}

Locations

Access biblical location data.

List Locations

GET /api/locations

Get Location by ID

GET /api/locations/:locationId

Projects

Manage project configurations.

List Projects

GET /api/projects

Get Project Config

GET /api/projects/:projectName/config

Error Codes

Code	Message	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid Bearer token
403	Forbidden	Invalid API key or insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Examples

cURL

curl -X POST https://api.midown.pro/api/shots/context \
  -H "Authorization: Bearer tk_your-tenant_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "GENESIS",
    "verseRef": "GEN.1.1",
    "shotText": "In the beginning God created the heavens and the earth"
  }'

JavaScript (fetch)

const response = await fetch('https://api.midown.pro/api/shots/context', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tk_your-tenant_live_your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    project: 'GENESIS',
    verseRef: 'GEN.1.1',
    shotText: 'In the beginning God created the heavens and the earth'
  })
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    'https://api.midown.pro/api/shots/context',
    headers={
        'Authorization': 'Bearer tk_your-tenant_live_your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'project': 'GENESIS',
        'verseRef': 'GEN.1.1',
        'shotText': 'In the beginning God created the heavens and the earth'
    }
)

data = response.json()
print(data)