Ask and chat completions · API docs

Folio answers from what the church has taught and approved, and cites its sources. There are two ways in: conversations, which give you the full answer with sources, and a chat completions endpoint for tools that already speak the OpenAI format.

Conversations#

Start a conversation with a first question. The answer is written asynchronously, so the first response holds an answer with kind pending:

curl -X POST "$FOLIO_API_URL/v1/conversations" \
  -H "Authorization: Bearer $FOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: faq-forgiveness-1" \
  -d '{
  "title": "Forgiveness",
  "input": "What did we teach about forgiveness?"
}'

Poll until the answer is final:

curl -X GET "$FOLIO_API_URL/v1/conversations/conv_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012" \
  -H "Authorization: Bearer $FOLIO_API_KEY"

An answer ends as one of these kinds:

Kind	Meaning
`answer`	Written from the church's teaching, with numbered `sources`.
`not_covered`	The church has not taught on this. Folio says so rather than guessing.
`stopped`	You stopped it with `POST /v1/conversations/{conversation}/stop`.
`unavailable`	The answer could not be written; ask again.
`greeting`, `smalltalk`, `offtopic`	Conversational replies with no teaching behind them.

A finished answer has short_answer, blocks (each citing source_refs), sources (speaker, date and a time-coded excerpt), follow_ups, and standing: whether a teaching it drew on has since been superseded or retracted. Show that to readers; a superseded source should not read as current.

Ask a follow-up in the same conversation with POST /v1/conversations/{conversation}/messages. Only one answer can be written at a time; asking while one is pending answers 409.

Streaming#

Send "stream": true on a message to receive server-sent events instead of a pending answer: a turn.created event first, then answer events until it is final.

Chat completions#

For tools that point at an OpenAI-compatible base URL:

curl -X POST "$FOLIO_API_URL/v1/chat/completions" \
  -H "Authorization: Bearer $FOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: completion-1" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What did Sunday say about forgiveness?"
    }
  ]
}'

Response

{
  "id": "chatcmpl-conv_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
  "object": "chat.completion",
  "model": "folio",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Forgiveness is a decision to release a debt, as God released ours. [1]" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

The last user message is the question. model is accepted and ignored.
Pass conversation_id to continue a thread.
The request waits up to 55 seconds for the answer and answers 504 if it is slower. Streaming is not supported.
usage is always zero. Errors use the Folio error envelope, not OpenAI's.

Cost and limits#

Each new question counts against the plan's Ask allowance (402 quota_exceeded when it is used up) and the monthly AI budget (402 ai_budget_exhausted). A sandbox church stops at its test budget. Keys need ask:create to ask and ask:read to read conversations, and the church's plan needs the API and Ask features.

Questions that need a person#

Questions that suggest a crisis are not answered with a model answer. They get care guidance and are raised to the church as a care alert. That is deliberate and cannot be turned off from the API.

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.