Pagination

List endpoints (GET /agents, GET /conversations, GET /clients, etc.) use a single, consistent pagination shape: page + limit.

Request

curl "https://api.gennia.ai/public/api/v1/agents?page=2&limit=50" \
  -H "X-Api-Key: $GENNIA_API_KEY"

Parameter	Type	Default	Max
`page`	integer ≥ 1	`1`	—
`limit`	integer	`20`	`100`

Invalid pagination (page < 1, limit > 100) returns 400 VALIDATION_ERROR.

Response envelope

Every paginated response wraps the items in the same shape:

{
  "items": [
    { "publicId": "...", "name": "..." },
    ...
  ],
  "page": 2,
  "limit": 50,
  "total": 123,
  "totalPages": 3
}

Field	Meaning
`items`	The page’s results.
`page`	Echo of the requested page (1-based).
`limit`	Echo of the requested limit.
`total`	Total result count across all pages.
`totalPages`	`ceil(total / limit)`.

Iterating through all pages

page=1
while :; do
  resp=$(curl -s "https://api.gennia.ai/public/api/v1/agents?page=$page&limit=100" \
    -H "X-Api-Key: $GENNIA_API_KEY")
  echo "$resp" | jq -c '.items[]'
  total_pages=$(echo "$resp" | jq -r '.totalPages')
  [ "$page" -ge "$total_pages" ] && break
  page=$((page + 1))
done

When you don’t know the total upfront, you can also stop as soon as items comes back empty. But always check totalPages if you need consistent end-of-data behavior.

Filters

Most list endpoints accept additional query parameters to narrow the result set:

Endpoint	Typical filters
`GET /agents`	`includeArchived`
`GET /clients`	`status`, `q` (free-text search)
`GET /conversations`	`status`, `agentPublicId`
`GET /knowledge-sources`	`status`, `search`

Refer to the individual endpoint pages in the reference for the full filter list.

Stable ordering

Results are ordered by createdAt descending (newest first) unless the endpoint documentation specifies otherwise. This means new resources can appear on the first page during iteration — if you need a stable snapshot, capture it once and store the IDs.

Getting started

Conventions

Agents

Threads

Hub

Request

Response envelope

Iterating through all pages

Filters

Stable ordering

​Request

​Response envelope

​Iterating through all pages

​Filters

​Stable ordering

Request

Response envelope

Iterating through all pages

Filters

Stable ordering