Skip to content
FolioSign inStart your trial

Developers

Build on a church’s approved teaching.

A key picks the church. Add a teaching, read the transcript and the note it becomes, ask questions with citations, and hear about every change by webhook.

Start the quickstartAPI reference
Base URLhttps://folio-app.candensa.com
AuthBearer key
FormatJSON over HTTPS, under /v1
Machine-readableOpenAPI 3.1

What do you want to build?

QuickstartAdd teachings and read what Folio makesUpload a recording, wait for it to process, then read the transcript and the published note.AskAsk the church’s teachingCited answers from approved teaching, through conversations or an OpenAI-compatible endpoint.WebhooksReact to eventsSigned webhooks with retries, replay and a catalogue generated from the API.PartnersRun many churchesCreate customer churches, act for them with one key and read their usage.Booth devicesBuild for the boothPair a device, sync the library and receive commands.WidgetPut Ask on a pageA public site key, an origin allowlist and a script tag.

Start here

Overview and conceptsWhat the Folio API is for, how a key picks the church, the response envelope and where to go next.QuickstartCreate a key, add a teaching, wait for it to process, read the transcript and note, ask a question and receive a webhook.Sandbox and testingGet a free sandbox church and test keys, know its limits, and test webhooks without touching real data.

Concepts

Authentication and scopesThe three kinds of key, how scopes and wildcards work, sandbox keys, rotation and least privilege.ErrorsThe error envelope, every error code with its cause and fix, and which errors to retry.PaginationHow limit and cursor work, what meta tells you, and how to walk every page.IdempotencyHow Idempotency-Key makes retries safe, what is replayed, and the three ways a key can be refused.Rate limitsThe three limits that apply to a request, the headers that report them, and how to back off.Versioning and deprecationWhat Folio promises about changes within /v1, how deprecations are announced and how webhook payload versions work.

Build

Notes and outputsHow notes and outputs move from draft to published, what a key can see, and how to react to changes.ScriptureLook up passages in the King James Version and see how often the church has taught them.Ask and chat completionsAsk questions answered from the church's own teaching, with citations, through conversations or an OpenAI-compatible endpoint.Widget and embedPut the Ask box on any page with a site key, restrict it to your origins, and build your own front end on the public endpoints.WebhooksRegister an endpoint, verify the signature in your language, handle retries and ordering, and replay what you missed.Webhook event catalogueEvery event Folio sends, generated from the API so it is never out of date.

Partners and devices

PartnersCreate customer churches, act for them with one key, mint church keys, and receive their events.Booth devicesPair a booth, call with a device key, sync the library, receive commands and keep Folio Live up to date.

Operate

API changelogWhat changed in the API, newest first, with the deprecation policy.Going to productionA checklist to run before you point a live church at your integration.FAQ and troubleshootingAnswers to the questions developers ask most, and what to check when a call does not behave.GlossaryThe words the API and the console use, in one place.

Recent API changes

  • A purged event when a church’s data is removed

    partner.church.deleted is now sent twice for a customer church. data.object.deletion.stage is scheduled when deletion is requested and purged once its data is removed. The purged event carries only the church summary captured before removal, so use it as the signal to delete what you hold for that church. Both events share the church’s ordering_key.

  • Data export and deletion for churches and people

    Church owners can request a copy of the church’s data and schedule the church for deletion from the console, and cancel a scheduled deletion until it starts. A signed-in person can download a copy of their own data and schedule deletion of their account, which waits 14 days and can be cancelled. These are console features that use a signed-in session, not key routes. A church deletion ends with the purged event above.

  • Shared Ask conversations have a public read

    GET /v1/public/{church}/ask/shares/{token} returns a conversation shared by link, without a key. The share page counts views with a beacon that is not part of the public API.

Full changelog and deprecation policy

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