L’API de Nubbo est une API REST pour travailler avec vos buckets depuis votre propre code : fichiers, dossiers, liens, demandes de fichiers, galeries, labels, projets et automatisations. Dans ce guide, vous créez une clé et faites vos premières requêtes avec curl.
Ce que vous obtenez
- Gérer votre espace Nubbo depuis vos programmes, avec des clés qui ne voient que ce que vous choisissez.
- Envoyer et télécharger directement entre votre code et votre fournisseur de stockage.
- Réagir aux nouveaux fichiers, aux envois dans les demandes de fichiers et à l’activité grâce aux déclencheurs.
Avant de commencer
Il vous faut un compte Nubbo avec l’offre Pro ou Équipes et un terminal avec curl. Dans une équipe, ce sont le propriétaire ou un administrateur qui créent les clés d’API.
Étape 1 : créez une clé
Dans Nubbo, ouvrez Paramètres › API (ou Équipe › API dans une équipe) et appuyez sur Créer une clé d’API.
Donnez-lui un nom et choisissez :
- Accès : Lecture seule ou Lecture et écriture.
- Portée : Tout l’espace ou Buckets et projets choisis. La clé ne voit que ce que vous choisissez ici.
- Expiration : 30 jours, 90 jours, 1 an ou Pas d’expiration. Nubbo vous prévient 7 jours avant.
Appuyez sur Créer la clé. Nubbo vous demande votre mot de passe pour confirmer que c’est bien vous. Si la vérification en deux étapes est activée, il vous demande aussi le code.

Copiez la clé et appuyez sur Je l’ai enregistrée. Elle commence par
nbk_et c’est la seule fois où vous la verrez en entier. Conservez-la sur le serveur ou dans l’outil qui va l’utiliser, jamais dans une page web.

Étape 2 : votre première requête
Envoyez la clé dans l’en-tête Authorization de chaque requête. Commencez par GET /v1/me, qui ne consomme pas de requêtes :
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_votre_cle"
La réponse contient votre espace, votre offre, le quota du mois et la clé avec son accès et sa portée. En voici un extrait :
{
"workspace": { "id": "…", "name": "Studio Nord", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "Ma première clé",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Ensuite, listez vos buckets et les fichiers d’un dossier :
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_votre_cle"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=factures/" \
-H "Authorization: Bearer nbk_votre_cle"
Les listes renvoient data et nextCursor. Pour la page suivante, envoyez cette valeur dans cursor. Quand nextCursor vaut null, il n’y a plus rien.

Étape 3 : la référence
Dans Paramètres › API, appuyez sur Voir la documentation, ou ouvrez api.nubbo.app/v1/docs. Vous y trouvez chaque ressource avec ses champs et des exemples. Le document OpenAPI se trouve sur api.nubbo.app/v1/openapi.json.

Envois et téléchargements
Les fichiers ne passent pas par Nubbo. Pour en envoyer un, demandez l’envoi avec POST /v1/buckets/{bucketId}/uploads, envoyez le fichier à l’adresse présignée renvoyée et terminez avec POST /v1/uploads/{uploadId}/complete. Pour télécharger, demandez un lien avec POST /v1/files/{fileId}/download-link et téléchargez le fichier depuis votre fournisseur.
Limites
| Pro | Équipes | |
|---|---|---|
| Requêtes par minute par clé | 60 | 120 |
| Requêtes par mois | 50 000 | 100 000 + 10 000 par siège |
| Événements de déclencheurs par mois | 20 000 | 50 000 + 5 000 par siège |
Le quota appartient à l’espace et se renouvelle à chaque période de facturation. GET /v1/me, les interrogations des déclencheurs et les réponses 401, 429 et 5xx ne comptent pas comme requêtes. Chaque événement livré par un déclencheur compte comme événement. Chaque réponse contient les en-têtes X-RateLimit-Remaining et X-Nubbo-Quota-Requests-Remaining, et dans Paramètres › API vous voyez l’utilisation de la période.

En cas de problème
API_KEY_INVALID,API_KEY_REVOKEDouAPI_KEY_EXPIRED: la clé n’est pas valide, a été révoquée ou a expiré. Vérifiez l’en-tête ou créez une autre clé.API_PLAN_REQUIRED: l’espace de la clé n’a pas l’API. Elle est incluse dans les offres Pro et Équipes.API_KEY_READ_ONLY: la clé est en lecture seule. Créez-en une avec Lecture et écriture.API_RATE_LIMITED: trop de requêtes avec cette clé. Attendez les secondes indiquées dansRetry-Afteret réessayez.API_QUOTA_EXCEEDED: l’espace a atteint sa limite du mois.details.resetsAtindique quand elle se renouvelle.
Chaque erreur contient un requestId. Indiquez-le si vous nous écrivez.
Pour en savoir plus, consultez l’API de Nubbo. Pour l’utiliser sans écrire de code, suivez le guide de Zapier, celui de n8n ou celui de Make. Pour l’utiliser depuis votre assistant IA, voyez comment connecter Nubbo à Claude, ChatGPT ou Cursor.
Questions fréquentes
Quelles offres incluent l'API ?
Pro et Équipes. Avec Gratuit ou Personal, les requêtes répondent API_PLAN_REQUIRED.
Puis-je lire des fichiers chiffrés avec l'API ?
Non. Le contenu chiffré apparaît sans nom, chemin, taille ni type et toute modification est refusée avec API_ENCRYPTED_CONTENT.
Que se passe-t-il si je répète une requête après une erreur réseau ?
Envoyez l'en-tête Idempotency-Key dans vos POST et PATCH. Pendant 24 heures, répéter la même requête renvoie la première réponse et ne crée rien deux fois.
L'API changera-t-elle sans prévenir ?
Non. Un changement incompatible arrive en /v2 et /v1 est maintenue au moins 12 mois, avec les en-têtes Deprecation et Sunset.
Sources
Étapes vérifiées à partir de ces pages.