Overview and concepts · API docs

Folio turns a church's recorded teaching into transcripts, notes and cited answers, and a person at the church reviews them before members see anything. The API gives your software the same pipeline: add a teaching, read what Folio made from it, ask questions of the approved teaching, and hear about changes by webhook.

The five ideas#

Idea	What it means for your code
A key is one church	A church API key picks the church. There is no church id in the URL, so one key can never read another church's data.
Review comes first	Keys read notes and outputs only after they are published. A draft, a note in review and a retired note answer `404`.
Everything is under `/v1`	Within `/v1` Folio only adds. See versioning.
One envelope	Every response has the same shape, so one client wrapper covers every call.
Scripture is King James	Verse text is the King James Version only. Any other translation is not found.

Base URLs#

Calls go to the API host shown at the top of the API reference. Production and sandbox churches share one host: a folio_live_ key reaches real churches and a folio_test_ key reaches sandbox churches, and the API refuses a mismatch on every request. Code in these docs reads the host from FOLIO_API_URL and the key from FOLIO_API_KEY.

The response envelope#

Success:

Code

{
  "status": true,
  "message": "teaching",
  "data": { "id": "tch_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012", "object": "teaching", "status": "ready" },
  "meta": { "request_id": "req_b337770ecebe03b03a88a8998b59263d" }
}

Failure always has the same shape, with a closed list of error.code values (see errors):

Code

{
  "status": false,
  "message": "That teaching is not in this church.",
  "error": { "code": "not_found", "status": 404, "request_id": "req_b337770ecebe03b03a88a8998b59263d" }
}

message is written for a person. Branch on error.code. Quote request_id when you contact support; it is also in the X-Request-Id response header.

Lists add paging details to meta: has_next, has_prev and next_cursor. See pagination.

What you can build#

A pipeline that uploads each Sunday's recording and publishes the note to your own site when it is approved: quickstart and webhooks.
A question box that answers from your church's teaching: Ask and chat completions, or the widget for a page you do not control.
A product that runs many churches: partners.
Software that runs in the sound booth: booth devices.

How these docs stay accurate#

The API reference and the event catalogue are generated from the running API. Every request example in the guides is checked against the same OpenAPI document before the site builds, and each guide shows the API version it was last checked against.

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