GET/v1/conversations
List conversations#
Lists conversations started with this church's keys, most recently updated first. Messages are not included; read one conversation to get them.
Auth. A church API key. Needs the ask: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
ask:read- Operation id
machineListConversations
Parameters
| Name | In | Description |
|---|---|---|
limit | query | How many items to return, from 1 to 100. (integer, e.g. 20) |
cursor | query | The opaque meta.next_cursor from the previous page. (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 |
|---|---|---|
audience required | string | Who can see the conversation: private for keys. |
created_at required | string (date-time) | When it was created, in RFC 3339 UTC. |
id required | string | The id, with a type prefix such as tch_ or note_. |
message_count required | integer (int32) | How many messages the conversation holds. |
messages required | object[] | The messages. |
mine required | boolean | Whether the calling credential started it. |
object required | string | The object type. |
scope required | value | What the answers may draw on. |
surface required | string | Where the conversation was started: machine for keys. |
title required | string | The title. |
updated_at required | string (date-time) | When it last changed, in RFC 3339 UTC. |
200 Success. List conversations.
{
"status": true,
"message": "conversations",
"data": [
{
"id": "conv_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012",
"object": "conversation",
"title": "What did we teach about forgiveness?",
"scope": {
"kind": "org",
"library": "own"
},
"surface": "machine",
"audience": "private",
"message_count": 2,
"mine": false,
"created_at": "2026-11-01T14:00:00Z",
"updated_at": "2026-11-01T14:00:09Z",
"messages": []
}
],
"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/conversations?limit=20" \
-H "Authorization: Bearer $FOLIO_API_KEY"