Endpoints de listagem (GET /agents, GET /conversations, GET /clients, etc.) usam um único shape consistente: page + limit.
Requisição
curl "https://api.gennia.ai/public/api/v1/agents?page=2&limit=50" \
-H "X-Api-Key: $GENNIA_API_KEY"
| Parâmetro | Tipo | Default | Máx |
|---|
page | integer ≥ 1 | 1 | — |
limit | integer | 20 | 100 |
400 VALIDATION_ERROR.
Envelope da resposta
Toda resposta paginada envolve os items no mesmo shape:
{
"items": [
{ "publicId": "...", "name": "..." },
...
],
"page": 2,
"limit": 50,
"total": 123,
"totalPages": 3
}
| Campo | Significado |
|---|
items | Os resultados da página. |
page | Echo da página requisitada (1-indexed). |
limit | Echo do limit requisitado. |
total | Contagem total de resultados em todas as páginas. |
totalPages | ceil(total / limit). |
Iterando por todas as páginas
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
Quando você não souber o total antes, dá pra parar assim que items voltar vazio. Mas sempre confira totalPages se precisar de comportamento consistente de fim-de-dados.
Filtros
A maioria dos endpoints de listagem aceita query parameters adicionais pra restringir resultado:
| Endpoint | Filtros típicos |
|---|
GET /agents | includeArchived |
GET /clients | status, q (busca textual) |
GET /conversations | status, agentPublicId |
GET /knowledge-sources | status, search |
Ordenação estável
Resultados são ordenados por createdAt descendente (mais novos primeiro), exceto onde a documentação do endpoint especifique o contrário. Isso significa que recursos novos podem aparecer na primeira página durante iteração — se precisar de um snapshot estável, capture uma vez e guarde os IDs. 
