# 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)