Pagination, filtering & sorting

Cursor-based pagination

Every list endpoint returns a JSON object with the resource array and a hasMore boolean. When hasMore is true, additional pages are available.

GET /api/v1/conversations?limit=20

{
  "chats": [ ... ],
  "hasMore": true
}

To fetch the next page, pass the before parameter with the ISO 8601 timestamp of the last item's created_at or last_message_at field:

GET /api/v1/conversations?limit=20&before=2025-03-15T10:30:00.000Z

Pagination parameters

Paginating through all results

Example: fetch all conversations page by page.

async function fetchAllConversations(apiKey) {
  let before = undefined
  const all = []

  while (true) {
    const url = new URL('https://api.watsi.ai/api/v1/conversations')
    url.searchParams.set('limit', '100')
    if (before) url.searchParams.set('before', before)

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    })
    const data = await res.json()

    all.push(...data.chats)

    if (!data.hasMore) break
    before = data.chats.at(-1).last_message_at
  }

  return all
}

Filtering

Some list endpoints accept query parameters to narrow results. The available filters depend on the resource type.

Example: fetch only open conversations:

GET /api/v1/conversations?status=open&limit=20

Sorting

List endpoints return results sorted by most recent first (descending by timestamp). This default sort order is consistent across all resources and cannot be changed via query parameters.

The cursor-based pagination model relies on this sort order — the before parameter always moves backward in time.

Response envelope

Each resource type uses a predictable key in the response object:

All list responses also include hasMore: boolean at the top level.