Docs · Operate
API changelog
What changed in the Folio API, newest first, and how deprecations are announced.
Deprecation policy
Within /v1 Folio only adds. Before anything is removed it is announced at least 365 days ahead, deprecated operations answer with Deprecation and Sunset headers, and the OpenAPI document marks them deprecated. See versioning and deprecation.
Changes
addedA 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.
addedData 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.
addedShared 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.
addedRead the current legal versions
GET /v1/public/legal returns the current Terms, Privacy Policy and DPA versions, their effective dates and links, so a client does not hard-code them. People who own or administer a church accept a new version in the console, and the acceptance is recorded with its version and source.
changedWebhook events carry the whole resource
Events are now version 2026-12-01. The flat body (type, timestamp, a few fields) is replaced by an event with a stable evt_ id, created, livemode, request, actor and data.object, the full resource, with data.previous_attributes on updates. Related resources are embedded, lists are capped with has_more and a url, and every event has a privacy class. Events on partner endpoints for customer churches carry an ordering_key, the church id, to sort by created within a church. Signatures, retries and headers are unchanged. Deduplicate on the event id; webhook-id still names one delivery. See the event catalogue for the envelope, privacy classes, signature samples, retries and replay.
changedTeaching ids from the key API are typed
POST /v1/teachings and POST /v1/teachings/{teaching}/upload now return tch_ ids instead of raw UUIDs, matching every read. Both forms are still accepted in the path.
changedPlan catalogue version 3: Ask pack and overage rate
GET /v1/public/plans and GET /v1/billing/plans show version 3 of the plans. Plan prices and allowances are unchanged; the Ask pack and the Ask overage rate differ. Existing subscribers renew on their pinned version until they choose a plan or interval change. Read prices from the catalogue rather than copying them.
addedTax appears on invoices only where the seller is registered
Invoice and subscription objects, in the API and in billing webhook events, carry a tax label, notes and tax lines. Where the seller is not registered for a country no tax is added and the invoice says no tax was charged, with no tax line.
securityThe API serves its developer description only
GET /openapi.json and /openapi.yaml now describe the public operations and nothing else. The full internal description is no longer served in production.
addedRead teachings, transcripts, notes, outputs and scripture with a key
New read routes: GET /v1/teachings, /v1/teachings/{teaching}, /v1/teachings/{teaching}/transcript, /v1/teachings/{teaching}/note, /v1/outputs, /v1/outputs/{output}, /v1/scripture/lookup and /v1/scripture/translations. Keys see published notes and outputs only.
addedThe webhook event catalogue is public
GET /v1/public/webhook-events returns every event type with its description and an example, without a key.
changedNotes for keys no longer carry reviewer fields
GET /v1/notes and GET /v1/notes/{note} return a smaller note: reviewer and generation details such as the return reason and model information are no longer in the response, and approval_kind is human or automatic.
removedGift, unsubscribe and beacon routes left the public description
Routes that exist for the Folio site itself, such as gift purchase, email unsubscribe links and analytics beacons, are no longer listed as part of the public API. They are not an integration surface.
Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.