Notes and outputs · API docs

A note is Folio's written record of a teaching: a summary and sections, written from the transcript. An output is something written from a note: a devotional, blog post, newsletter or study guide. Both are reviewed by a person before members see them.

Lifecycle#

Status	Meaning	Visible to a key
`draft`	Folio wrote it; nobody has read it.	No
`in_review`	Sent for review.	No
`approved`	A reviewer approved it, or the church's automatic approval did. `approval_kind` says which.	No
`published`	Live on the church's public site.	Yes
`retired`, `superseded`	Taken down or replaced.	No

A note a reviewer sent back carries a reason in the console. Keys never see drafts, notes in review or retired notes, and ask for them with 404, exactly as for an unknown id. That is the review step working, not an error to work around.

approval_kind is human when a person read it and automatic when the church's automatic approval approved it. If you show notes to readers, say which, because churches choose how much review they want.

Reading#

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

List published notes with GET /v1/notes and read one with GET /v1/notes/{note}. Outputs: GET /v1/outputs (add ?teaching= to narrow) and GET /v1/outputs/{output}. Note sections have a heading (h) and a body; an output's body is Markdown in body_md, and verses lists the passages it quotes, checked against the King James Version.

Staying current#

Poll less, subscribe more:

Event	Do
`note.published`	Fetch the note and publish it to your site.
`note.superseded`	Take the note down; the church replaced it.
`output.published`	Fetch and post the output.
`output.unpublished`	Remove it from wherever you posted it. The note it was written from changed, or a reviewer reopened it.
`output.stale`	The note changed; the output may no longer match.

Edits and preconditions#

Editing and approving happen in the console. Those console routes use optimistic concurrency: they take If-Match: <row_version> and answer 428 if it is missing and 412 stale_version if the row changed since you read it. The church API does not edit notes today.

Mind the gaps#

A teaching can be ready for a while before its note is published. Do not treat 404 on the note as a failure; subscribe to note.published instead of polling.

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