FlickerFaith API

Integrate FlickerFaith's Christian AI assistant and Bible study data into your application.

Authentication

All requests require an API key passed via the X-API-Key header. The Data API also accepts the same key as a bearer token.

X-API-Key: ff_live_your_api_key_here
# or
Authorization: Bearer ff_live_your_api_key_here

Contact FlickerFaith to obtain an API key. Each key has configurable rate limits.

Chat API

Endpoint

POST /v1/chat

Request Body

Field	Type	Required	Description
message	string	Yes	The user's message (max 10,000 chars)
conversationHistory	array	No	Previous messages: [{role: "user"|"assistant", content: "..."}] (max 20)
persona	string	No	AI persona: default, biblical_scholar, or simple_helper
maxTokens	number	No	Max response tokens (capped by your key's limit)

Example Request

curl -X POST https://api.flickerfaith.com/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ff_live_your_key_here" \
  -d '{
    "message": "What does Philippians 4:13 mean?",
    "persona": "biblical_scholar"
  }'

Example Response

{
  "success": true,
  "data": {
    "message": "Philippians 4:13 — 'I can do all things through Christ...'",
    "model": "flickerfaith-1",
    "usage": { "inputTokens": 180, "outputTokens": 350 }
  },
  "meta": {
    "requestId": "a1b2c3d4-...",
    "latencyMs": 2150,
    "persona": "biblical_scholar",
    "rateLimits": {
      "daily": { "limit": 100, "remaining": 87 },
      "monthly": { "limit": 2000, "remaining": 1543 }
    }
  }
}

Personas

ID	Description
default	Balanced Christian AI assistant — bold, Biblical, compassionate
biblical_scholar	Academic depth — Hebrew/Greek origins, manuscript traditions, church history
simple_helper	Warm encourager — short, practical, plain language for new believers

Error Codes

HTTP	Code	Description
401	MISSING_API_KEY	No API key provided
401	INVALID_API_KEY	Key not found or revoked
429	DAILY_LIMIT_EXCEEDED	Daily message cap reached (resets midnight UTC)
429	MONTHLY_LIMIT_EXCEEDED	Monthly cap reached (resets 1st of month)
400	INVALID_REQUEST	Missing or invalid message field
400	INVALID_PERSONA	Unknown persona ID
500	INTERNAL_ERROR	Server error — retry the request

Rate Limits

Each API key has configurable daily and monthly message limits. Current limits are returned in every response under meta.rateLimits. When a limit is exceeded, the API returns HTTP 429.

Notes

• The system prompt and theological guardrails cannot be overridden via the API.
• Conversation history is capped at the last 20 messages.
• Individual messages are capped at 10,000 characters.
• Response token count is capped per your key's maxTokensPerRequest setting.

Data API

Read-only access to the Bible study resources behind FlickerFaith: Bible translations, commentaries, dictionaries, topical works, Strong's lexicons, cross-references and a curated index of Bible stories. Partners receive only the resources the FlickerFaith team has marked shareable for their key; start with /catalog to see what yours can read. The machine-readable contract is at /openapi.json (OpenAPI 3.0.3).

Base URL and envelope

https://api.flickerfaith.com/v1/data

Every response uses the same envelope. Successful responses carry Cache-Control: private, max-age=300 (responses are specific to your key), so a client-side HTTP cache will absorb repeat lookups.

// success
{ "success": true, "data": { ... } }

// error
{ "success": false, "error": { "code": "NOT_FOUND", "message": "No story with slug jonah-and-the-whale" } }

Error codes

HTTP	Code	Description
401	MISSING_API_KEY	No key in X-API-Key or Authorization
401	INVALID_API_KEY	Key not found or revoked
403	SCOPE_DENIED	The resource exists but is not shareable with this key
404	NOT_FOUND	Unknown book, chapter, verse, entry, topic or story
400	INVALID_REQUEST	Malformed reference, missing query, or a limit exceeded
429	DAILY_LIMIT_EXCEEDED	Per-key daily request quota reached (resets midnight UTC)
500	INTERNAL_ERROR	Server error — retry the request

Catalog

What this key can access, grouped by family. Every item carries the id you pass to the other endpoints, a display name, and the attribution string you must show with its content.

{
  "success": true,
  "data": {
    "bible":        [{ "id": "WEB", "name": "World English Bible", "attribution": "World English Bible (WEB), public domain." }],
    "commentaries": [{ "id": "MHC", "name": "Matthew Henry's Concise Commentary", "attribution": "..." }],
    "dictionaries": [{ "id": "Easton", "name": "Easton's Bible Dictionary", "attribution": "..." }],
    "topics":       [{ "id": "Nave", "name": "Nave's Topical Bible", "attribution": "..." }],
    "lexicons":     [{ "id": "StrGrk", "name": "Strong's Greek", "attribution": "Lemma and transliteration data from Open Scriptures, CC BY-SA 4.0." }],
    "crossrefs":    { "id": "crossrefs", "name": "Cross-references", "attribution": "..." },
    "stories":      { "id": "stories", "name": "FlickerFaith Bible Stories", "attribution": "Story index curated by FlickerFaith." }
  }
}

Bible

The 66 books in canonical order with abbreviations, chapter count and the verse count of every chapter (verseCounts[0] is chapter 1). Use it to validate references before you request them.

{ "success": true, "data": { "books": [
  { "number": 9, "name": "1 Samuel", "abbreviations": ["1sam", "1sa", "1sm"], "chapters": 31, "verseCounts": [28, 36, 21, ...] },
  ...
] } }

book may be the book number, the full English name, or a common abbreviation (1sam, Song of Songs, Rev). Whole chapter only.

{ "success": true, "data": {
  "translation": "WEB",
  "book": { "number": 9, "name": "1 Samuel" },
  "chapter": 17,
  "verses": [{ "v": 1, "text": "..." }, { "v": 2, "text": "..." }, ...],
  "attribution": "World English Bible (WEB), public domain."
} }

Semicolon-separated references. Accepts Book c, Book c:v, Book c:v-v, Book c:v-c:v and Book c-c. Limits: at most 10 refs per call, each spanning at most 4 chapters; anything larger returns INVALID_REQUEST.

{ "success": true, "data": {
  "translation": "WEB",
  "passages": [
    { "ref": "John 3:16-18", "verses": [{ "book": "John", "chapter": 3, "v": 16, "text": "..." }, ...] },
    { "ref": "Psalm 23",     "verses": [{ "book": "Psalms", "chapter": 23, "v": 1, "text": "..." }, ...] }
  ],
  "attribution": "World English Bible (WEB), public domain."
} }

Strong's lexicons

G1234 for Greek, H430 for Hebrew.

{ "success": true, "data": {
  "number": "G26", "lexicon": "greek",
  "lemma": "ἀγάπη", "transliteration": "agapē", "gloss": "love",
  "definition": "...",
  "attribution": "Lemma and transliteration data from Open Scriptures, CC BY-SA 4.0."
} }

Matches lemma, transliteration and gloss. Returns up to 25 entries under data.results; lex is optional.

Commentaries

Entries for every verse in the chapter that the commentary covers, as data.entries: [{ verse, text }].

A single verse entry: { id, book, chapter, verse, text, attribution }.

Dictionaries

Headword prefix search, up to 25 hits of { idx, headword }.

The full entry: { id, idx, headword, text, attribution }.

Topics

Headword search inside one topical work; returns { slug, headword } hits.

Every headword beginning with the letter.

{ "success": true, "data": {
  "id": "Nave", "slug": "courage", "headword": "Courage",
  "sections": [
    { "heading": "Enjoined",
      "refs": [{ "ref": "Joshua 1:6-7", "bookNum": 6, "ch": 1, "v": 6, "vEnd": 7 }, ...],
      "see": ["Boldness", "Fear"] }
  ],
  "attribution": "..."
} }

The same headword merged across every topical work the key can read, one sources[] entry per work, each with its own attribution.

Cross-references

{ "success": true, "data": { "book": "1 Samuel", "chapter": 17, "verse": 45,
  "refs": ["1 Samuel 17:47", "Psalms 20:7", "Zechariah 4:6", ...], "attribution": "..." } }

Bible stories

A curated index of the major narratives of both testaments plus a set of parables (kind is narrative or parable). Each entry maps a story to exact passages, characters, lowercase theme tags, one to three factual one-sentence hooks, a short summary in FlickerFaith's own words, a period tag and a canonical reading order. Passages are validated against real chapter and verse counts.

Query	Description
theme	Exact theme tag, e.g. courage, forgiveness, provision
q	Free-text match on title, characters, hooks and summary
testament	OT or NT
kind	narrative or parable
limit	1–100, default 25; results are in canonical order

{ "success": true, "data": {
  "slug": "david-and-goliath", "title": "David and Goliath",
  "kind": "narrative", "testament": "OT", "book": "1 Samuel",
  "passages": [{ "ref": "1 Samuel 17" }],
  "characters": ["David", "Goliath", "Saul", "Eliab"],
  "themes": ["courage", "faith", "underdog", "god's power"],
  "hooks": ["A teenager with a sling faces a nine-foot champion", "..."],
  "summary": "The Philistine champion Goliath taunts Israel's army for forty days ...",
  "era": "united-monarchy", "order": 61,
  "attribution": "Story index curated by FlickerFaith."
} }

Quotas

Each key has a per-day request quota across all Data API endpoints. When it is exhausted the API returns 429 DAILY_LIMIT_EXCEEDED until midnight UTC. Responses are cacheable for five minutes; caching them on your side does not count against the quota.

Worked example

Find a story about courage, pull its passage in the WEB translation, then fetch the Nave's topic Courage to surface related verses.

1. Find a story tagged courage

curl "https://api.flickerfaith.com/v1/data/stories?theme=courage&limit=3" \
  -H "X-API-Key: ff_live_your_key_here"

{ "success": true, "data": { "total": 14, "stories": [
  { "slug": "birth-of-moses", "title": "The Birth of Moses", "book": "Exodus",
    "passages": [{ "ref": "Exodus 1:8-2:10" }], "themes": ["courage", "protection", ...], "order": 26, ... },
  { "slug": "the-twelve-spies", "title": "The Twelve Spies", "order": 38, ... },
  { "slug": "david-and-goliath", "title": "David and Goliath", "book": "1 Samuel",
    "passages": [{ "ref": "1 Samuel 17" }],
    "hooks": ["A teenager with a sling faces a nine-foot champion", ...], "order": 61, ... }
], "attribution": "Story index curated by FlickerFaith." } }

2. Pull the passage in the WEB translation

curl "https://api.flickerfaith.com/v1/data/bible/WEB/passage?ref=1%20Samuel%2017:45-47" \
  -H "X-API-Key: ff_live_your_key_here"

{ "success": true, "data": {
  "translation": "WEB",
  "passages": [{ "ref": "1 Samuel 17:45-47", "verses": [
    { "book": "1 Samuel", "chapter": 17, "v": 45, "text": "Then David said to the Philistine, ..." },
    { "book": "1 Samuel", "chapter": 17, "v": 46, "text": "..." },
    { "book": "1 Samuel", "chapter": 17, "v": 47, "text": "..." }
  ] }],
  "attribution": "World English Bible (WEB), public domain."
} }

3. Fetch the Nave's topic "Courage"

curl "https://api.flickerfaith.com/v1/data/topics/Nave/entries/courage" \
  -H "X-API-Key: ff_live_your_key_here"

{ "success": true, "data": {
  "id": "Nave", "slug": "courage", "headword": "Courage",
  "sections": [
    { "heading": "Enjoined", "refs": [
        { "ref": "Deuteronomy 31:6-7", "bookNum": 5, "ch": 31, "v": 6, "vEnd": 7 },
        { "ref": "Joshua 1:6-7",       "bookNum": 6, "ch": 1,  "v": 6, "vEnd": 7 },
        { "ref": "1 Samuel 17:32",     "bookNum": 9, "ch": 17, "v": 32, "vEnd": null }, ...
      ], "see": ["Boldness", "Fear"] },
    { "heading": "Instances of", "refs": [ ... ], "see": [] }
  ],
  "attribution": "Nave's Topical Bible, public domain."
} }

Feed any of those ref values back into step 2 to render the verses. Show each response's attribution next to the content it came from.

Licensing and attribution

• Shareable resources only. Partners receive only the resources the FlickerFaith team has marked shareable for their key. Requesting anything else returns 403 SCOPE_DENIED; /catalog is always the authoritative list.
• Attribution is mandatory. Every resource response carries an attribution string. It must be displayed wherever the content is shown — on screen, in captions, or in generated media credits. Do not strip or shorten it.
• Strong's lexicon data. Lemma and transliteration data comes from Open Scriptures and is licensed CC BY-SA 4.0. Derived works must keep that notice and carry the same license.
• Bible translations. Translations are served only where they are public domain or where FlickerFaith holds redistribution rights. Which translations your key can read is decided per key and listed under catalog.bible.
• Bible stories. The story index (titles, passages, characters, themes, hooks and summaries) is written by FlickerFaith and may be retold, adapted and quoted in partner products with the supplied attribution.

© 2025 FlickerFaith · flickerfaith.com