L’API di Nubbo è un’API REST per lavorare con i tuoi bucket dal tuo codice: file, cartelle, link, inbox, gallerie, etichette, progetti e automazioni. In questa guida crei una chiave e fai le tue prime richieste con curl.
Cosa ottieni
- Gestire il tuo spazio Nubbo dai tuoi programmi, con chiavi che vedono solo ciò che scegli tu.
- Caricare e scaricare direttamente tra il tuo codice e il tuo provider di storage.
- Reagire ai nuovi file, ai caricamenti nelle inbox e all’attività con i trigger.
Prima di iniziare
Ti servono un account Nubbo con il piano Pro o Team e un terminale con curl. In un team, le chiavi API le creano il proprietario o un amministratore.
Passo 1: crea una chiave
In Nubbo apri Impostazioni › API (o Team › API in un team) e premi Crea chiave API.
Dalle un nome e scegli:
- Accesso: Sola lettura o Lettura e scrittura.
- Ambito: Tutto lo spazio o Bucket e progetti scelti. La chiave vede solo ciò che scegli qui.
- Scadenza: 30 giorni, 90 giorni, 1 anno o Nessuna scadenza. Nubbo ti avvisa 7 giorni prima.
Premi Crea chiave. Nubbo ti chiede la password per confermare che sei tu. Se hai attivato la verifica in due passaggi, ti chiede anche il codice.

Copia la chiave e premi L’ho salvata. Inizia con
nbk_ed è l’unica volta in cui la vedrai per intero. Conservala sul server o nello strumento che la userà, mai in una pagina web.

Passo 2: la tua prima richiesta
Invia la chiave nell’header Authorization di ogni richiesta. Inizia con GET /v1/me, che non consuma richieste:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_la_tua_chiave"
La risposta contiene il tuo spazio, il tuo piano, la quota del mese e la chiave con il suo accesso e il suo ambito. Eccone un estratto:
{
"workspace": { "id": "…", "name": "Studio Nord", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "La mia prima chiave",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Poi elenca i tuoi bucket e i file di una cartella:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_la_tua_chiave"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=fatture/" \
-H "Authorization: Bearer nbk_la_tua_chiave"
Gli elenchi restituiscono data e nextCursor. Per la pagina successiva, invia quel valore in cursor. Quando nextCursor è null, non c’è altro.

Passo 3: la reference
In Impostazioni › API premi Vedi la documentazione, oppure apri api.nubbo.app/v1/docs. Lì trovi ogni risorsa con i suoi campi ed esempi. Il documento OpenAPI è in api.nubbo.app/v1/openapi.json.

Caricamenti e download
I file non passano da Nubbo. Per caricarne uno, richiedi il caricamento con POST /v1/buckets/{bucketId}/uploads, invia il file all’indirizzo prefirmato che ricevi e concludi con POST /v1/uploads/{uploadId}/complete. Per scaricare, chiedi un link con POST /v1/files/{fileId}/download-link e scarica il file dal tuo provider.
Limiti
| Pro | Team | |
|---|---|---|
| Richieste al minuto per chiave | 60 | 120 |
| Richieste al mese | 50.000 | 100.000 + 10.000 per postazione |
| Eventi dei trigger al mese | 20.000 | 50.000 + 5.000 per postazione |
La quota è dello spazio e si rinnova a ogni periodo di fatturazione. GET /v1/me, le interrogazioni dei trigger e le risposte 401, 429 e 5xx non contano come richieste. Ogni evento consegnato da un trigger conta come evento. Ogni risposta contiene gli header X-RateLimit-Remaining e X-Nubbo-Quota-Requests-Remaining, e in Impostazioni › API vedi l’utilizzo del periodo.

Se qualcosa va storto
API_KEY_INVALID,API_KEY_REVOKEDoAPI_KEY_EXPIRED: la chiave non è valida, è stata revocata o è scaduta. Controlla l’header o crea un’altra chiave.API_PLAN_REQUIRED: lo spazio della chiave non ha l’API. È inclusa nei piani Pro e Team.API_KEY_READ_ONLY: la chiave è di sola lettura. Creane una con Lettura e scrittura.API_RATE_LIMITED: troppe richieste con questa chiave. Aspetta i secondi indicati inRetry-Aftere riprova.API_QUOTA_EXCEEDED: lo spazio ha esaurito il limite del mese.details.resetsAtindica quando si rinnova.
Ogni errore contiene un requestId. Includilo se ci scrivi.
Per saperne di più, vedi l’API di Nubbo. Per usarla senza scrivere codice, segui la guida di Zapier, quella di n8n o quella di Make. Per usarla dal tuo assistente IA, scopri come collegare Nubbo a Claude, ChatGPT o Cursor.
Domande frequenti
Quali piani includono l'API?
Pro e Team. Con Gratis o Personal, le richieste rispondono API_PLAN_REQUIRED.
Posso leggere file cifrati con l'API?
No. I contenuti cifrati appaiono senza nome, percorso, dimensione né tipo e ogni modifica viene rifiutata con API_ENCRYPTED_CONTENT.
Cosa succede se ripeto una richiesta per un errore di rete?
Invia l'header Idempotency-Key nelle tue POST e PATCH. Per 24 ore, ripetere la stessa richiesta restituisce la prima risposta e non crea nulla due volte.
L'API cambierà senza preavviso?
No. Una modifica incompatibile arriva come /v2 e /v1 resta disponibile per almeno 12 mesi, con gli header Deprecation e Sunset.
Fonti
Passaggi verificati con queste pagine.