Language models trained for studying Scripture.

Quickstart

To make a request, point any OpenAI client at https://api.carrell.ai/v1 and set the model to biblical-1.

curl https://api.carrell.ai/v1/chat/completions \
  -H "Authorization: Bearer $CARRELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "biblical-1",
    "messages": [
      { "role": "user", "content": "What is the context of Romans 8:28?" }
    ],
    "max_completion_tokens": 512
  }'

import OpenAI from "openai"

const carrell = new OpenAI({
  baseURL: "https://api.carrell.ai/v1",
  apiKey: process.env.CARRELL_API_KEY,
  maxRetries: 0, // each attempt uses a credit
})

const answer = await carrell.chat.completions.create({
  model: "biblical-1",
  messages: [{ role: "user", content: "What is the context of Romans 8:28?" }],
  max_completion_tokens: 512,
})
console.log(answer.choices[0].message.content)

import os
from openai import OpenAI

carrell = OpenAI(
    base_url="https://api.carrell.ai/v1",
    api_key=os.environ["CARRELL_API_KEY"],
    max_retries=0,  # each attempt uses a credit
)

answer = carrell.chat.completions.create(
    model="biblical-1",
    messages=[{"role": "user", "content": "What is the context of Romans 8:28?"}],
    max_completion_tokens=512,
)
print(answer.choices[0].message.content)

Authentication

Send your API key as a Bearer token on every request except /health. Each key has a rate limit, a number of credits, and permissions that control whether it can list models, create completions and send feedback.

Authorization: Bearer $CARRELL_API_KEY

We aren’t issuing keys yet. Join the waitlist to get one when we are.

Endpoints

Chat completions

POST /v1/chat/completions accepts the OpenAI request body. The gateway rejects fields it doesn’t recognize, so you’ll get an error if you misspell a field name.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "biblical-1-…",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "Paul writes Romans 8:28 at the end of a passage about suffering…"
    }
  }],
  "usage": { "prompt_tokens": 1180, "completion_tokens": 214, "total_tokens": 1394 }
}

If the moderation model blocks an answer, the response has finish_reason: "content_filter" and a short refusal instead of the text.

Streaming

When you set "stream": true, the gateway returns standard OpenAI chunks and ends with data: [DONE]. The gateway waits for the whole answer and its moderation check before it sends the first chunk, so streaming doesn’t make the first words arrive sooner. The x-moderation-mode: buffered header tells clients about the wait.

Tool calling

You can give the model functions to call, e.g., one that fetches a passage, and your code runs them. When the model calls a tool, the response has finish_reason: "tool_calls", and you send each result back in a tool message. The gateway doesn’t check the arguments, so your code should validate them.

{
  "model": "biblical-1",
  "messages": [{ "role": "user", "content": "Compare John 1:1 with Genesis 1:1." }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_passage",
      "description": "Returns the text of a Bible reference.",
      "parameters": {
        "type": "object",
        "properties": { "reference": { "type": "string" } },
        "required": ["reference"]
      }
    }
  }]
}

If the model writes a malformed call, or calls a tool you didn’t send, the gateway returns HTTP 503 with the code invalid_tool_call. You can retry the request, and each retry uses a credit.

Feedback

POST /v1/feedback rates one answer, which you identify by its x-request-id. Feedback requests are free. The gateway stores the conversation only when share_conversation is true, and it deletes stored feedback after 180 days.

{
  "request_id": "chatcmpl-…",
  "rating": "down",
  "reasons": ["wrong_citation"],
  "comment": "Quoted Psalm 23:4 as verse 5.",
  "share_conversation": false
}

The reasons you can send are wrong_scripture, wrong_citation, unfair_to_a_tradition, unsupported_claim, unhelpful, unsafe, formatting and other. If you rate the same answer twice, the second rating replaces the first.

Response headers

Limits and credits

• Each completion attempt uses one credit, including attempts that fail or are blocked after they start. Reads and feedback are free. You should turn off automatic retries in your SDK unless you want to spend credits on them.
• A request can be up to 262,144 bytes, with up to 200 messages and 16 tools.
• The prompt must leave room for the output limit you set. If it doesn’t, the gateway returns context_length_exceeded and doesn’t use a credit.
• Each key has its own rate limit. When you go over it, the gateway returns HTTP 429.

Errors

Errors use the same format as OpenAI errors, so the OpenAI SDKs raise their usual exceptions.

{ "error": { "type": "invalid_request_error", "code": "invalid_request", "param": "temperature", "message": "…" } }