FlickerFaith API

Integrate FlickerFaith's Christian AI assistant into your application.

Authentication

All requests require an API key passed via the X-API-Key header.

X-API-Key: ff_live_your_api_key_here

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

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://us-central1-flickergpt.cloudfunctions.net/publicChat \
  -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": "claude-sonnet-4-20250514",
    "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.