Requête exemple
Réponse exemple
Renvoie la liste paginée des transferts du workspace authentifié, triés du plus récent au plus ancien (created_at décroissant, puis id décroissant comme critère de départage). La pagination repose sur un curseur stable (next_cursor) qui ne saute ni ne duplique de lignes lorsque de nouveaux transferts sont créés entre deux appels ; l'ancien mode offset reste accepté pour les SDK non migrés. Plusieurs filtres combinables permettent de restreindre par statut, dossier, statut d'analyse antivirus, ou recherche texte sur le code court et le titre. Seuls les transferts appartenant au workspace de la clé d'API sont visibles, la portée étant systématiquement imposée côté serveur via workspace_id.
Authentification
Requiert une clé d'API valide passée en Authorization: Bearer cof_live_... (ou cof_test_, cof_rk_, cof_mcp_) et la portée transfers:read. Une clé dépourvue de cette portée reçoit une erreur scope_missing (HTTP 403). Cet endpoint est classé en lecture (read) pour le calcul du quota de débit par minute, et l'idempotence est désactivée (lecture pure).
Paramètres de requête
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| limit | integer | Non | Nombre de transferts à renvoyer. Défaut 20, borné entre 1 et 100. Une valeur hors plage est ramenée dans ces bornes. |
| cursor | string | Non | Curseur de pagination opaque (base64url) renvoyé par next_cursor lors de l'appel précédent. Prioritaire sur offset si les deux sont fournis. Un curseur malformé est ignoré (retour à la première page). |
| offset | integer | Non | Décalage hérité (legacy), utilisé uniquement si cursor est absent. Préférer cursor pour une pagination stable. |
| status | string | Non | Filtre exact sur le statut du transfert (ex. active, expired). Correspondance stricte sur la colonne status. |
| folder_id | string | Non | Filtre par dossier. Un UUID restreint à ce dossier ; les valeurs sentinelles null ou unfiled renvoient les transferts non classés (sans dossier). |
| scan_status | string | Non | Liste de statuts d'analyse antivirus séparés par des virgules (ex. infected,quarantined,flagged). Renvoie les transferts dont scan_status figure dans la liste. |
| search | string | Non | Recherche insensible à la casse sur le code court (short_code) et le titre (transfer_title). Les caractères %, _ et , sont retirés de la requête avant exécution. |
Réponse
L'objet renvoyé porte object: "list". Le tableau data contient les transferts, chacun exposant : id, short_code (code court de partage), transfer_title, status, expires_at, total_downloads, max_downloads (peut être null si illimité), scan_status (statut de l'analyse antivirus), folder_id (peut être null) et created_at. La pagination est portée par next_cursor (jeton à repasser dans cursor pour la page suivante, null quand il n'y a plus de résultats), has_more (booléen hérité) et limit (limite effective appliquée). Le champ offset n'est présent que si l'appel a utilisé le mode offset.
Erreurs
| Code | Quand | Comment résoudre |
|---|---|---|
| missing_api_key (401) | En-tête Authorization absent. | Ajouter Authorization: Bearer cof_live_... à la requête. |
| invalid_api_key (401) | Clé malformée, inconnue ou préfixe non reconnu. | Vérifier la clé et son préfixe (cof_live_, cof_test_, cof_rk_, cof_mcp_). |
| expired_api_key (401) | Clé arrivée à expiration. | Émettre une nouvelle clé d'API depuis la console. |
| revoked_api_key (401) | Clé révoquée ou désactivée. | Générer une nouvelle clé active. |
| scope_missing (403) | La clé n'a pas la portée transfers:read. | Créer ou utiliser une clé incluant transfers:read. |
| ip_not_allowed (403) | IP appelante hors de l'allowlist de la clé. | Appeler depuis une IP autorisée ou ajuster l'allowlist. |
| rate_limited (429) | Quota de requêtes par minute dépassé. | Respecter les en-têtes X-RateLimit-* / Retry-After et réessayer après le reset. |
| internal_error (500) | Erreur côté base lors de la requête. | Réessayer ; si le problème persiste, contacter le support avec le request_id. |
Voir aussi
POST/v1/transfersCréer un transfert et obtenir les URL d'upload signées.GET/v1/transfers/{id}Récupérer le détail d'un transfert, y compris ses fichiers.GET/v1/analytics/top-transfersLister les transferts les plus consultés ou téléchargés.