GET/v1/teachings
List teachings#
Lists the church's teachings, newest first, with where each one is in processing. Unlike notes and outputs, keys see teachings in every status, so you can watch an upload progress.
Filter with status (comma separated) or search titles, speakers and series with q. Pages follow the standard cursor rules; meta.total is the number of matching teachings.
Auth. A church API key. Needs the teachings:read scope, or a wildcard that includes it (machine:read, machine:*, * on a partner key). A partner key can call it for a customer church by sending X-Folio-Church.
Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.
- Auth
- Church API key
- Scope
teachings:read- Operation id
machineListTeachings
Parameters
| Name | In | Description |
|---|---|---|
limit | query | Items per page. (integer, e.g. 25) |
cursor | query | Opaque cursor from meta.next_cursor of the previous page. (string) |
status | query | Comma separated: ready, failed, queued, processing (everything still working) or awaiting_upload. (string, e.g. ready) |
q | query | Words to look for in titles, speakers and series. (string) |
X-Folio-Church | header | Partner keys only: run this call as one of your customer churches (its org_ id or slug). The church must be one of yours, the key must be allowed to act for it, and plan checks run against that church. (string, e.g. org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012) |
Responses
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | When the teaching was added. |
duration_seconds | integer (int32) | The spoken length in seconds. Zero until the recording is read. |
failure_reason | string | A short, plain reason when status is failed. Empty otherwise. |
id | string | The teaching id, prefixed tch_. |
note_id | string | The note written from it, prefixed note_. Null until a note exists. |
note_status | string | The status of that note: none, draft, in_review, approved, published, failed or superseded. |
object | enum: teaching | Always teaching. |
passage | string | The main passage, as a reference such as Romans 8:28-39. Empty until known. |
recorded_at | string (date-time) | When the teaching was given, when known. |
series | string | The series it belongs to. Empty when it is not part of one. |
speaker | string | Who taught it. Empty until known. |
status | string | Where the teaching is: awaiting_upload, queued, processing, ready or failed. Only ready teachings have a transcript and a note. |
title | string | The teaching title. |
200 Success. List teachings.
{
"status": true,
"message": "teachings",
"data": [
{
"id": "tch_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
"object": "teaching",
"title": "Sunday, 1 November: Nothing can separate us",
"speaker": "Pastor Ade",
"series": "Romans 8",
"passage": "Romans 8:31-39",
"status": "ready",
"failure_reason": "",
"duration_seconds": 2412,
"recorded_at": "2026-11-01T09:00:00Z",
"created_at": "2026-11-01T10:02:11Z",
"note_id": "note_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
"note_status": "published"
}
],
"meta": {
"request_id": "req_b337770ecebe03b03a88a8998b59263d",
"has_next": false,
"has_prev": false
}
}400 The request could not be read.
{
"status": false,
"message": "the page cursor is not valid",
"error": {
"code": "invalid_argument",
"status": 400,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}401 The key or session is missing, invalid or expired.
{
"status": false,
"message": "That API key is not valid or has expired.",
"error": {
"code": "unauthenticated",
"status": 401,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}403 The credential lacks the scope, the church is suspended, the feature is not in the plan, or the address is not allowed.
{
"status": false,
"message": "That API key does not have the required scope.",
"error": {
"code": "permission_denied",
"status": 403,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}404 The resource is not in this church.
{
"status": false,
"message": "That item is not in this church.",
"error": {
"code": "not_found",
"status": 404,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}409 Conflict, including a duplicate Idempotency-Key still being processed.
{
"status": false,
"message": "A request with this Idempotency-Key is still running.",
"error": {
"code": "conflict",
"status": 409,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}422 A field failed validation, or an Idempotency-Key was reused with a different body.
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}429 Rate limited. Wait Retry-After seconds.
{
"status": false,
"message": "Too many requests. Wait before trying again.",
"error": {
"code": "rate_limited",
"status": 429,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}500 Something went wrong. Quote error.request_id.
{
"status": false,
"message": "Something went wrong. Quote the request id to support.",
"error": {
"code": "internal",
"status": 500,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}Code samples
curl -X GET "$FOLIO_API_URL/v1/teachings?limit=25&status=ready" \
-H "Authorization: Bearer $FOLIO_API_KEY"