Pagination

L'API REST Qyvo renvoie aujourd'hui des tableaux plats avec des limites strictes par endpoint, et non des enveloppes paginées par curseur. Ceci est intentionnel : les endpoints de trigger et de recherche sont conçus pour les agents de polling (n8n, Zapier, Claude) qui veulent les N enregistrements les plus récents à chaque appel.

Limites par défaut par endpoint

Endpoint	Limite par défaut	Tri	Paramètres de filtre
GET /v1/triggers/new-message-received	100	created_at DESC	message_type
GET /v1/triggers/new-campaign-sent	100	created_at DESC	—
GET /v1/triggers/new-flow-triggered	100	created_at DESC	flow_id
GET /v1/triggers/new-sequence-triggered	100	created_at DESC	sequence_id
POST /v1/actions/search-contacts	50	last_message_at DESC	query, tag, email
POST /v1/actions/list-templates	Tous (plafonné côté serveur)	name	status
POST /v1/actions/list-tags	Tous (plafonné côté serveur)	name	name

Pattern de polling

Pour les triggers, le bon pattern est de mémoriser l'id le plus récent que vous avez vu et de cesser le traitement quand vous le retrouvez au prochain poll. Pseudo-code :

last_seen_id = load_from_state()

batch = GET /v1/triggers/new-message-received
new_messages = []
for msg in batch:
    if msg.id == last_seen_id:
        break
    new_messages.append(msg)

process(new_messages)
if new_messages:
    save_to_state(new_messages[0].id)

C'est exactement ce que le nœud trigger n8n fait en interne. Ne faites pas de polling plus rapidement que toutes les 30 secondes sauf si votre compte a une limite de débit relevée.

Ensembles de résultats plus grands

Si vous avez réellement besoin de plus de 100 enregistrements (p. ex. exporter tous les contacts), utilisez plutôt les outils MCP — list_contacts prend en charge la pagination par curseur via les paramètres page et per_page. Voir Référence des outils MCP : Contacts.

Pour des exports en masse ad hoc, le tableau de bord propose un export CSV sous Contacts → Export.

Comportement des filtres

Les filtres sont combinés en AND. Les chaînes vides sont traitées comme « pas de filtre » :

# Renvoie jusqu'à 50 contacts dont le nom/téléphone/email correspond à "smith" ET qui ont le tag "vip"
curl -X POST https://www.qyvo.io/api/v1/actions/search-contacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "smith", "tag": "vip"}'

Il n'y a pas d'opérateur OR sur la surface REST. Composez deux requêtes côté client et dédupliquez par id si vous avez besoin d'une disjonction.

Direction future

La pagination basée sur curseur (?cursor=...) figure dans la roadmap pour les endpoints triggers et search lorsque les charges au niveau du compte dépasseront le polling à plat. Nous garderons le comportement actuel par défaut et placerons les curseurs derrière un flag opt-in ?paginate=cursor pour la rétrocompatibilité.