L’API de Nubbo és una API REST per treballar amb els teus buckets des del teu propi codi: fitxers, carpetes, enllaços, bústies, galeries, etiquetes, projectes i automatitzacions. En aquesta guia crees una clau i fas les primeres peticions amb curl.
Què aconsegueixes
- Gestionar el teu espai de Nubbo des dels teus programes, amb claus que només veuen el que tu tries.
- Pujar i baixar directament entre el teu codi i el teu proveïdor d’emmagatzematge.
- Reaccionar a fitxers nous, pujades a bústies i activitat amb els activadors.
Abans de començar
Necessites un compte de Nubbo amb el pla Pro o Equips i un terminal amb curl. En un equip, les claus d’API les creen el propietari o un administrador.
Pas 1: crea una clau
A Nubbo, obre Configuració › API (o Equip › API en un equip) i prem Crea una clau d’API.
Posa-li un nom i tria:
- Accés: Només lectura o Lectura i escriptura.
- Abast: Tot l’espai o Buckets i projectes triats. La clau només veu el que triïs aquí.
- Caducitat: 30 dies, 90 dies, 1 any o Sense caducitat. Nubbo t’avisa 7 dies abans.
Prem Crea la clau. Nubbo et demana la contrasenya per confirmar que ets tu. Si tens la verificació en dos passos, també et demana el codi.

Copia la clau i prem Ja l’he desada. Comença per
nbk_i és l’única vegada que la veuràs sencera. Guarda-la al servidor o a l’eina que la farà servir, mai en una pàgina web.

Pas 2: la teva primera petició
Envia la clau a la capçalera Authorization de cada petició. Comença per GET /v1/me, que no gasta peticions:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_la_teva_clau"
La resposta porta el teu espai, el teu pla, la quota del mes i la clau amb el seu accés i el seu abast. Aquest n’és un extracte:
{
"workspace": { "id": "…", "name": "Estudi Nord", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "La meva primera clau",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Després, llista els teus buckets i els fitxers d’una carpeta:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_la_teva_clau"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=factures/" \
-H "Authorization: Bearer nbk_la_teva_clau"
Les llistes retornen data i nextCursor. Per a la pàgina següent, envia aquest valor a cursor. Quan nextCursor és null, no n’hi ha més.

Pas 3: la referència
A Configuració › API, prem Mostra la documentació, o obre api.nubbo.app/v1/docs. Hi trobaràs cada recurs amb els seus camps i exemples. El document OpenAPI és a api.nubbo.app/v1/openapi.json.

Pujades i baixades
Els fitxers no passen per Nubbo. Per pujar-ne un, demana la pujada amb POST /v1/buckets/{bucketId}/uploads, envia el fitxer a l’adreça presignada que et retorna i acaba amb POST /v1/uploads/{uploadId}/complete. Per baixar-ne un, demana un enllaç amb POST /v1/files/{fileId}/download-link i baixa’l des del teu proveïdor.
Límits
| Pro | Equips | |
|---|---|---|
| Peticions per minut per clau | 60 | 120 |
| Peticions al mes | 50.000 | 100.000 + 10.000 per plaça |
| Esdeveniments d’activadors al mes | 20.000 | 50.000 + 5.000 per plaça |
La quota és de l’espai i es renova amb cada període de facturació. GET /v1/me, les consultes dels activadors i les respostes 401, 429 i 5xx no compten com a peticions. Cada esdeveniment que lliura un activador compta com a esdeveniment. Cada resposta porta les capçaleres X-RateLimit-Remaining i X-Nubbo-Quota-Requests-Remaining, i a Configuració › API veus l’ús del període.

Si alguna cosa falla
API_KEY_INVALID,API_KEY_REVOKEDoAPI_KEY_EXPIRED: la clau no és vàlida, s’ha revocat o ha caducat. Revisa la capçalera o crea una altra clau.API_PLAN_REQUIRED: l’espai de la clau no té l’API. És als plans Pro i Equips.API_KEY_READ_ONLY: la clau és de només lectura. Crea’n una amb Lectura i escriptura.API_RATE_LIMITED: massa peticions amb aquesta clau. Espera els segons deRetry-Afteri torna-ho a provar.API_QUOTA_EXCEEDED: l’espai ha esgotat el límit del mes.details.resetsAtdiu quan es renova.
Cada error porta un requestId. Inclou-lo si ens escrius.
Més sobre l’API de Nubbo. Per fer-la servir sense escriure codi, segueix la guia de Zapier, la de n8n o la de Make. Per fer-la servir des del teu assistent d’IA, mira com connectar Nubbo amb Claude, ChatGPT o Cursor.
Preguntes freqüents
Quins plans inclouen l'API?
Pro i Equips. Amb Gratuït o Personal, les peticions responen API_PLAN_REQUIRED.
Puc llegir fitxers xifrats amb l'API?
No. El contingut xifrat apareix sense nom, ruta, mida ni tipus, i qualsevol canvi s'hi rebutja amb API_ENCRYPTED_CONTENT.
Què passa si repeteixo una petició després d'una fallada de xarxa?
Envia la capçalera Idempotency-Key a les peticions POST i PATCH. Durant 24 hores, repetir la mateixa petició retorna la primera resposta i no crea res dues vegades.
L'API canviarà sense avís?
No. Un canvi incompatible surt com a /v2, i /v1 es manté com a mínim 12 mesos amb les capçaleres Deprecation i Sunset.
Fonts
Passos comprovats amb aquestes pàgines.