Guies

Comença amb l'API de Nubbo

De zero a la teva primera petició en uns minuts. Crea una clau i comença a gestionar el teu emmagatzematge des del teu propi codi.

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

  1. A Nubbo, obre Configuració › API (o Equip › API en un equip) i prem Crea una clau d’API.

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

    Finestra Crea una clau d'API amb l'accés, l'abast i la caducitat Finestra Crea una clau d'API amb l'accés, l'abast i la caducitat
  3. 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.

    Finestra La teva clau d'API amb la clau a punt per copiar Finestra La teva clau d'API amb la clau a punt per copiar

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.

Terminal amb la petició GET /v1/me i la seva resposta Terminal amb la petició GET /v1/me i la seva resposta

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.

Referència de l'API de Nubbo amb l'exemple de curl Referència de l'API de Nubbo amb l'exemple de curl

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

ProEquips
Peticions per minut per clau60120
Peticions al mes50.000100.000 + 10.000 per plaça
Esdeveniments d’activadors al mes20.00050.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.

Ús de l'API del període a la configuració de Nubbo Ús de l'API del període a la configuració de Nubbo

Si alguna cosa falla

  • API_KEY_INVALID, API_KEY_REVOKED o API_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 de Retry-After i torna-ho a provar.
  • API_QUOTA_EXCEEDED: l’espai ha esgotat el límit del mes. details.resetsAt diu 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.