A API de Nubbo é unha API REST para traballar cos teus buckets desde o teu propio código: ficheiros, cartafoles, ligazóns, buzóns, galerías, etiquetas, proxectos e automatizacións. Nesta guía creas unha clave e fas as túas primeiras peticións con curl.
Que consegues
- Xestionar o teu espazo de Nubbo desde os teus programas, con claves que só ven o que ti escolles.
- Subir e descargar directamente entre o teu código e o teu provedor de almacenamento.
- Reaccionar a ficheiros novos, subidas a buzóns e actividade cos disparadores.
Antes de comezar
Necesitas unha conta de Nubbo co plan Pro ou Equipos e un terminal con curl. Nun equipo, as claves de API créanas o propietario ou un administrador.
Paso 1: crea unha clave
En Nubbo, abre Configuración › API (ou Equipo › API nun equipo) e preme Crear clave de API.
Ponlle un nome e escolle:
- Acceso: Só lectura ou Lectura e escritura.
- Alcance: Todo o espazo ou Buckets e proxectos escollidos. A clave só ve o que escollas aquí.
- Caducidade: 30 días, 90 días, 1 ano ou Sen caducidade. Nubbo avísache 7 días antes.
Preme Crear clave. Nubbo pídeche o teu contrasinal para confirmar que es ti. Se tes a verificación en dous pasos, tamén che pide o código.

Copia a clave e preme Xa a gardei. Comeza por
nbk_e é a única vez que a verás enteira. Gárdaa no servidor ou na ferramenta que a vaia usar, nunca nunha páxina web.

Paso 2: a túa primeira petición
Envía a clave na cabeceira Authorization de cada petición. Comeza por GET /v1/me, que non gasta peticións:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_a_tua_clave"
A resposta trae o teu espazo, o teu plan, a cota do mes e a clave co seu acceso e o seu alcance. Este é un extracto:
{
"workspace": { "id": "…", "name": "Estudo Norte", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "A miña primeira clave",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Despois, lista os teus buckets e os ficheiros dun cartafol:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_a_tua_clave"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=facturas/" \
-H "Authorization: Bearer nbk_a_tua_clave"
As listas devolven data e nextCursor. Para a páxina seguinte, envía ese valor en cursor. Cando nextCursor é null, non hai máis.

Paso 3: a referencia
En Configuración › API, preme Ver documentación, ou abre api.nubbo.app/v1/docs. Aí está cada recurso cos seus campos e exemplos. O documento OpenAPI está en api.nubbo.app/v1/openapi.json.

Subidas e descargas
Os ficheiros non pasan por Nubbo. Para subir un, pide a subida con POST /v1/buckets/{bucketId}/uploads, envía o ficheiro ao enderezo preasinado que che devolve e remata con POST /v1/uploads/{uploadId}/complete. Para descargar, pide unha ligazón con POST /v1/files/{fileId}/download-link e descárgao desde o teu provedor.
Límites
| Pro | Equipos | |
|---|---|---|
| Peticións por minuto por clave | 60 | 120 |
| Peticións ao mes | 50.000 | 100.000 + 10.000 por praza |
| Eventos de disparadores ao mes | 20.000 | 50.000 + 5.000 por praza |
A cota é do espazo e renóvase con cada período de facturación. GET /v1/me, as consultas dos disparadores e as respostas 401, 429 e 5xx non contan como peticións. Cada evento que entrega un disparador conta como evento. Cada resposta trae as cabeceiras X-RateLimit-Remaining e X-Nubbo-Quota-Requests-Remaining, e en Configuración › API ves o uso do período.

Se algo falla
API_KEY_INVALID,API_KEY_REVOKEDouAPI_KEY_EXPIRED: a clave non vale, está revogada ou caducou. Revisa a cabeceira ou crea outra clave.API_PLAN_REQUIRED: o espazo da clave non ten a API. Está nos plans Pro e Equipos.API_KEY_READ_ONLY: a clave é de só lectura. Crea unha con Lectura e escritura.API_RATE_LIMITED: demasiadas peticións con esta clave. Agarda os segundos deRetry-Aftere volve probar.API_QUOTA_EXCEEDED: o espazo usou o seu límite do mes.details.resetsAtindica cando se renova.
Cada erro trae un requestId. Inclúeo se nos escribes.
Máis sobre a API de Nubbo. Para usala sen escribir código, segue a guía de Zapier, a de n8n ou a de Make. Para usala desde o teu asistente de IA, mira como conectar Nubbo con Claude, ChatGPT ou Cursor.
Preguntas frecuentes
Que plans inclúen a API?
Pro e Equipos. Con Gratuíto ou Personal, as peticións responden API_PLAN_REQUIRED.
Podo ler ficheiros cifrados coa API?
Non. O contido cifrado aparece sen nome, ruta, tamaño nin tipo e calquera cambio sobre el rexéitase con API_ENCRYPTED_CONTENT.
Que pasa se repito unha petición por un fallo de rede?
Envía a cabeceira Idempotency-Key nos teus POST e PATCH. Durante 24 horas, repetir a mesma petición devolve a primeira resposta e non crea nada dúas veces.
Cambiará a API sen avisar?
Non. Un cambio que rompa algo chega como /v2 e /v1 mantense polo menos 12 meses, coas cabeceiras Deprecation e Sunset.
Fontes
Pasos comprobados con estas páxinas.