Guide

Inizia con l'API di Nubbo

Da zero alla tua prima richiesta in pochi minuti. Crea una chiave e inizia a gestire il tuo storage dal tuo codice.

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

  1. In Nubbo apri Impostazioni › API (o Team › API in un team) e premi Crea chiave API.

  2. 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.

    Finestra Crea chiave API con accesso, ambito e scadenza Finestra Crea chiave API con accesso, ambito e scadenza
  3. 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.

    Finestra La tua chiave API con la chiave pronta da copiare Finestra La tua chiave API con la chiave pronta da copiare

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.

Terminale con la richiesta GET /v1/me e la sua risposta Terminale con la richiesta GET /v1/me e la sua risposta

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.

Reference dell'API di Nubbo con l'esempio in curl Reference dell'API di Nubbo con l'esempio in curl

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

ProTeam
Richieste al minuto per chiave60120
Richieste al mese50.000100.000 + 10.000 per postazione
Eventi dei trigger al mese20.00050.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.

Utilizzo dell'API nel periodo nelle impostazioni di Nubbo Utilizzo dell'API nel periodo nelle impostazioni di Nubbo

Se qualcosa va storto

  • API_KEY_INVALID, API_KEY_REVOKED o API_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 in Retry-After e riprova.
  • API_QUOTA_EXCEEDED: lo spazio ha esaurito il limite del mese. details.resetsAt indica 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.