Parcourir de grandes listes avec la pagination par curseur

L'API Coffrify expose des listes (transferts, rooms, collections) qui peuvent contenir plusieurs centaines voire milliers d'objets. Pour les parcourir de façon fiable, tous les endpoints GET /v1/* utilisent la pagination par curseur : au lieu d'un numéro de page, vous passez un jeton opaque (cursor) qui pointe exactement sur la dernière ligne lue. Ce mécanisme est stable sous les insertions concurrentes (aucune ligne dupliquée, aucune ligne sautée) et performant (recherche par index, sans COUNT(*)). Chaque réponse contient le champ next_cursor : tant qu'il est non nul, il existe une page suivante.

Authentification

Incluez votre clé API dans l'en-tête Authorization: Bearer <votre_clé>. Pour lire des transferts, la clé doit posséder le scope transfers:read. Pour les rooms, le scope rooms:read. Pour les collections, le scope collections:read. Les clés de test (cof_test_…) et sandbox (cof_sandbox_…) n'exposent que les ressources créées dans leur environnement respectif : une clé live (cof_live_…) ne verra jamais les ressources sandbox.

Paramètres de pagination

La pagination par curseur repose sur deux paramètres : limit (taille de page) et cursor (position de reprise). Le tableau ci-dessous les détaille.

Exemple : parcourir tous les transferts

L'exemple ci-dessous parcourt l'intégralité d'une liste page par page, en suivant le next_cursor jusqu'à épuisement. Choisissez votre langage.

# Page 1
curl -G https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_…" \
  --data-urlencode "limit=50"
 
# Page suivante (remplacer <CURSOR> par la valeur de next_cursor)
curl -G https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_…" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=<CURSOR>"

Structure de la réponse

{
  "object": "list",
  "data": [
    {
      "id": "b2e7c1a0-3f4d-4b8e-9c1a-2d3e4f5a6b7c",
      "short_code": "k9mXpQ",
      "transfer_title": "Rapport annuel 2025",
      "status": "active",
      "expires_at": "2026-07-06T12:00:00.000Z",
      "total_downloads": 3,
      "max_downloads": 10,
      "scan_status": "clean",
      "folder_id": null,
      "created_at": "2026-06-06T09:15:00.000Z"
    }
  ],
  "next_cursor": "MjAyNi0wNi0wNlQwOToxNTowMC4wMDBafGIyZTdjMWEw",
  "has_more": true,
  "limit": 50
}

Les champs de pagination dans la réponse sont les suivants : object vaut toujours "list" ; data contient les objets de la page courante ; next_cursor est le jeton à passer au prochain appel (il est null sur la dernière page) ; has_more est un alias booléen de next_cursor !== null, conservé pour la rétrocompatibilité ; limit rappelle la limite demandée.

Codes d'erreur

Les erreurs portent surtout sur un curseur invalide (expiré ou falsifié) ou un limit hors bornes. Le tableau ci-dessous indique la résolution.

Voir aussi

• Créer votre première clé API
• Envoyer un transfert via l'API
• Filtrer les transferts par statut ou dossier
• Référence : GET /v1/transfers
• Référence : GET /v1/rooms
• Référence : GET /v1/collections