# Gamaliel Public API OpenAI-compatible Biblical Chat API — drop-in replacement for OpenAI’s chat completions shape, with biblical intelligence. **BYOK supports OpenAI and Anthropic (Claude).** ## Base URL https://api.gamaliel.ai/v1 ## Authentication BYOK (Bring Your Own Key). Send **either** an OpenAI or an Anthropic API key (must match the model provider you request): - **OpenAI:** `Authorization: Bearer sk-...` or `sk-proj-...` (normal OpenAI key shapes) - **Anthropic:** `Authorization: Bearer sk-ant-...` The key is used per request only — not stored. Use an **OpenAI** key with plain model ids (default provider) or `openai/<id>`. Use an **Anthropic** key with `anthropic/<model_id>` (e.g. `anthropic/claude-sonnet-4-20250514`). Mismatched key and model return `401` with an OpenAI-style error body. ## Main Endpoint POST /v1/chat/completions ## Key Parameters ### Standard OpenAI Parameters - `model` (string, optional): Defaults to **gpt-4.1-mini** when omitted (OpenAI path — same as Gamaliel’s normal tier). - **OpenAI:** pass a plain id (e.g. `gpt-4.1-mini`, `gpt-4o-mini`) or `openai/<id>`. Supported families: **GPT-4o, GPT-4.1, GPT-5+, o1/o3/o4** — not GPT-3.5 or legacy GPT-4 (e.g. `gpt-4-0613`). - **Anthropic:** pass `anthropic/<id>` with your Anthropic key. **Sonnet and Opus** only — **Haiku is not supported** on this endpoint. - Use **GET /v1/models** for ids your deployment lists (OpenAI rows from the server’s `OPENAI_API_KEY`, Anthropic rows from `ANTHROPIC_API_KEY`; each side may be empty if that key is unset or listing fails). - `messages` (array, required): Array of message objects with `role` and `content` - `stream` (boolean, optional): Whether to stream responses. Defaults to false ### Gamaliel-Specific Parameters - `theology` (string, optional): Theological perspective. Defaults to "default". Use GET /v1/theologies for options. - `profile` (string, optional): User profile. Defaults to "universal_explorer". Use GET /v1/profiles for options. - `book_id` (string, optional): Scripture context - book ID (e.g., "MAT", "GEN", "1CO") - `chapter` (integer, optional): Scripture context - chapter number - `verses` (array of integers, optional): Scripture context - specific verse numbers - `bible_id` (string, optional): Bible translation ID. Defaults to "eng-web" - `max_words` (integer, optional): Maximum response length in words. Defaults to 300 - `messages` array supports `system` role: Custom tone/format/audience instructions via standard system messages (appended to mandatory guardrails). Multiple system messages are concatenated. Examples: Discord bot for youth group, Christian counseling app, atheist/skeptical audience, children, new believers, minimal citations, academic context. See docs/guides/customizing-responses.md for detailed use case examples. - `disable_scripture_links` (boolean, optional): Disable scripture link conversion. Defaults to false. When false (default), references are converted to markdown links pointing to Gamaliel reader. When true, references remain as plain text without links. - `skip_preflight` (boolean, optional): Skip input validation. Defaults to false ## Scripture Search Endpoint GET /v1/scripture/search or POST /v1/scripture/search Semantic search for Bible chapters by meaning. No authentication required. ### Parameters - `q` / `query` (string, required): Search query. Use `q` for GET, `query` in POST body. - `bible_id` (string, optional): Bible translation for returned text. Defaults to "eng-web" - `limit` (integer, optional): Number of results, 1–20. Defaults to 5 - `testament` (string, optional): Filter by testament — "Old Testament" or "New Testament" - `book` (string, optional): Filter to a specific book by name or ID (e.g. "John", "GEN", "Psalms") ### Examples ``` GET /v1/scripture/search?q=love+your+enemies&testament=New+Testament&limit=3 ``` ```json POST /v1/scripture/search { "query": "love your enemies", "testament": "New Testament", "limit": 3 } ``` ## Other Endpoints - GET /v1/theologies - List available theology slugs for use in `theology` param - GET /v1/profiles - List available profile slugs for use in `profile` param - GET /v1/models - List supported chat models (OpenAI and `anthropic/...` rows when keys are configured) ## Quick Example (OpenAI key) ```python from openai import OpenAI client = OpenAI( api_key="sk-...", # Your OpenAI API key base_url="https://api.gamaliel.ai/v1" ) response = client.chat.completions.create( model="gpt-4.1-mini", messages=[ {"role": "user", "content": "What does the Bible say about forgiveness?"} ], theology="default", profile="universal_explorer" ) print(response.choices[0].message.content) ``` ## Quick Example (Anthropic / Claude key) Same OpenAI SDK and base URL; use your Anthropic key and an `anthropic/` model id from GET /v1/models: ```python from openai import OpenAI client = OpenAI( api_key="sk-ant-...", # Your Anthropic API key base_url="https://api.gamaliel.ai/v1" ) response = client.chat.completions.create( model="anthropic/claude-sonnet-4-20250514", messages=[ {"role": "user", "content": "What does the Bible say about forgiveness?"} ], theology="default", profile="universal_explorer" ) print(response.choices[0].message.content) ``` ## Important Limitations ❌ **Conversations are limited to 20 user messages** - Gamaliel is a focused Q&A service, not a generalized chat agent - When `messages` contains more than 20 entries with `"role": "user"`, the API returns `429` with `code: "conversation_limit_exceeded"` - Start a new conversation (fresh `messages` array) to continue - Only `"role": "user"` messages count — `system` and `assistant` messages do not ❌ **Does NOT support `tools` or `function_calling` parameters** - Gamaliel handles all tool execution internally (biblical search, passage lookup, etc.) - You receive final answers with scripture citations already included - Cannot build agents with custom tools or function calling ## Response Format Standard OpenAI chat completion format: - Non-streaming: Returns complete response object - Streaming: Server-Sent Events (SSE) format with `data:` prefixed JSON chunks ## Documentation - Full docs: docs/index.md - Endpoint reference: docs/endpoints/chat-completions.md - Examples: docs/examples/ - FAQ: docs/index.md#frequently-asked-questions ## Key Features - OpenAI-compatible request/response format (works with official OpenAI client libraries) - **OpenAI and Anthropic BYOK** with provider/key validation - Streaming and non-streaming support - Stateless (no chat persistence - manage history client-side) - Same biblical intelligence as Gamaliel UI (same prompts, tools, guardrails)