Returns whether the key belongs to a partner church, the programme grants it has, and how many customer churches it runs. A good first call to check a partner key works.
Auth. A partner key. Needs the partners:read scope, or a wildcard that includes it (machine:read, * on a partner key).
Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.
Auth
Partner key
Scope
partners:read
Operation id
machinePartnerOverview
Responses
Response data fields
Field
Type
Description
churches
integer (int64)
How many customer churches the partner runs.
grants
string[]
The programme features the partner has.
is_partner
boolean
Whether the church is a partner.
200 Success. Read the partner overview.200 example
{
"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.401 example
{
"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.403 example
{
"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.404 example
{
"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.409 example
{
"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.422 example
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
429 Rate limited. Wait Retry-After seconds.429 example
Lists the churches this partner created or runs, including sandbox churches with their expires_at. A key limited to some churches (church_ids) sees only those.
Auth. A partner key. Needs the partners:read scope, or a wildcard that includes it (machine:read, * on a partner key).
Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.
Auth
Partner key
Scope
partners:read
Operation id
machinePartnerChurches
Parameters
Parameters
Name
In
Description
limit
query
Items per page. (integer)
cursor
query
Opaque cursor from meta.next_cursor of the previous page. (string)
{
"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.401 example
{
"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.403 example
{
"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.404 example
{
"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.409 example
{
"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.422 example
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
429 Rate limited. Wait Retry-After seconds.429 example
Creates a customer church, or with sandbox: true a free sandbox church for development. The admin is invited by email at admin_email (sandbox churches send no email).
A sandbox church is not metered, takes only folio_test_ keys, holds at most 20 teachings, has a small AI budget, and is deleted after 30 days. Calls in a sandbox use the real transcription and AI providers under those caps, so keep recordings short. Live captions, the booth, audience email, publishing, networks, care, SSO, the widget, exports and outbound webhooks are switched off.
Auth. A partner key. Needs the partners:write scope, or a wildcard that includes it (* on a partner key).
Plan. Needs the Partner plan with the partners feature. A live church counts against the partner's churches meter. A partner can hold at most 25 sandbox churches.
Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.
Auth
Partner key
Scope
partners:write
Plan
Needs the Partner plan with the partners feature. A live church counts against the partner's churches meter. A partner can hold at most 25 sandbox churches.
Operation id
machinePartnerCreateChurch
Parameters
Parameters
Name
In
Description
Idempotency-Key
header
Makes a retry safe. The same key with the same body replays the first response for 24 hours; the same key with a different body returns 422; a duplicate that is still running returns 409 with Retry-After. Responses that carry a one-time secret are not replayed. (string, e.g. sunday-2026-11-01-upload)
Request body
Request body fields
Field
Type
Description
admin_email
string (email)
The email address of the church's first administrator.
name
string
The name.
sandbox
boolean
Create a free sandbox church for testing. It takes only folio_test_ keys, has hard limits and is deleted after 30 days.
{
"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.401 example
{
"status": false,
"message": "That API key is not valid or has expired.",
"error": {
"code": "unauthenticated",
"status": 401,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
402 The partner reached its church allowance or the sandbox limit.402 example
{
"status": false,
"message": "This partner has reached its church allowance.",
"error": {
"code": "quota_exceeded",
"status": 402,
"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.403 example
{
"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.404 example
{
"status": false,
"message": "That item is not in this church.",
"error": {
"code": "not_found",
"status": 404,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
422 A field failed validation, or an Idempotency-Key was reused with a different body.422 example
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
429 Rate limited. Wait Retry-After seconds.429 example
{
"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.401 example
{
"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.403 example
{
"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.404 example
{
"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.409 example
{
"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.422 example
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
429 Rate limited. Wait Retry-After seconds.429 example
Issues a church key for a customer church, to hand to that church's own system. It can carry only scopes the partner's programme grants. The full key is in the response once; Folio stores only a hash. A sandbox church gets a folio_test_ key and a live church a folio_live_ key.
Prefer one partner key with X-Folio-Church when your own server calls on the church's behalf; issue a church key when the church's system calls directly.
Auth. A partner key. Needs the partners:write scope, or a wildcard that includes it (* on a partner key).
Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.
Auth
Partner key
Scope
partners:write
Operation id
machinePartnerIssueKey
Parameters
Parameters
Name
In
Description
church required
path
The church slug, such as grace-chapel. For partner routes, the customer church id (org_) or slug. (string, e.g. grace-chapel)
Idempotency-Key
header
Makes a retry safe. The same key with the same body replays the first response for 24 hours; the same key with a different body returns 422; a duplicate that is still running returns 409 with Retry-After. Responses that carry a one-time secret are not replayed. (string, e.g. sunday-2026-11-01-upload)
{
"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.401 example
{
"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.403 example
{
"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.404 example
{
"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.409 example
{
"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.422 example
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
429 Rate limited. Wait Retry-After seconds.429 example
Revokes a key at once. The next call with it answers 401. Revoking is safe to repeat.
Auth. A partner key. Needs the partners:write scope, or a wildcard that includes it (* on a partner key).
Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.
Auth
Partner key
Scope
partners:write
Operation id
machinePartnerRevokeKey
Parameters
Parameters
Name
In
Description
church required
path
The church slug, such as grace-chapel. For partner routes, the customer church id (org_) or slug. (string, e.g. grace-chapel)
key required
path
The API key id, such as key_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012. (string, e.g. key_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012)
Idempotency-Key
header
Makes a retry safe. The same key with the same body replays the first response for 24 hours; the same key with a different body returns 422; a duplicate that is still running returns 409 with Retry-After. Responses that carry a one-time secret are not replayed. (string, e.g. sunday-2026-11-01-upload)
Responses
200 Success. Revoke a church key.200 example
{
"status": true,
"message": "api key revoked"
}
400 The request could not be read.400 example
{
"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.401 example
{
"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.403 example
{
"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.404 example
{
"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.409 example
{
"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.422 example
{
"status": false,
"message": "A field is not valid.",
"error": {
"code": "validation",
"status": 422,
"request_id": "req_b337770ecebe03b03a88a8998b59263d"
}
}
429 Rate limited. Wait Retry-After seconds.429 example