La API de Nubbo es una API REST para trabajar con tus buckets desde tu propio código: archivos, carpetas, enlaces, buzones, galerías, etiquetas, proyectos y automatizaciones. En esta guía creas una clave y haces tus primeras peticiones con curl.
Qué consigues
- Gestionar tu espacio de Nubbo desde tus programas, con claves que solo ven lo que tú eliges.
- Subir y descargar directamente entre tu código y tu proveedor de almacenamiento.
- Reaccionar a archivos nuevos, subidas a buzones y actividad con los disparadores.
Antes de empezar
Necesitas una cuenta de Nubbo con el plan Pro o Equipos y un terminal con curl. En un equipo, las claves de API las crea el propietario o un administrador.
Paso 1: crea una clave
En Nubbo, abre Configuración › API (o Equipo › API en un equipo) y pulsa Crear clave de API.
Ponle un nombre y elige:
- Acceso: Solo lectura o Lectura y escritura.
- Alcance: Todo el espacio o Buckets y proyectos elegidos. La clave solo ve lo que elijas aquí.
- Caducidad: 30 días, 90 días, 1 año o Sin caducidad. Nubbo te avisa 7 días antes.
Pulsa Crear clave. Nubbo te pide tu contraseña para confirmar que eres tú. Si tienes la verificación en dos pasos, también te pide el código.

Copia la clave y pulsa Ya la he guardado. Empieza por
nbk_y es la única vez que la verás entera. Guárdala en el servidor o en la herramienta que vaya a usarla, nunca en una página web.

Paso 2: tu primera petición
Envía la clave en la cabecera Authorization de cada petición. Empieza por GET /v1/me, que no gasta peticiones:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_tu_clave"
La respuesta trae tu espacio, tu plan, la cuota del mes y la clave con su acceso y su alcance. Este es un extracto:
{
"workspace": { "id": "…", "name": "Estudio Norte", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "Mi primera 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
}
}
Después, lista tus buckets y los archivos de una carpeta:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_tu_clave"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=facturas/" \
-H "Authorization: Bearer nbk_tu_clave"
Las listas devuelven data y nextCursor. Para la página siguiente, envía ese valor en cursor. Cuando nextCursor es null, no hay más.

Paso 3: la referencia
En Configuración › API, pulsa Ver documentación, o abre api.nubbo.app/v1/docs. Ahí está cada recurso con sus campos y ejemplos. El documento OpenAPI está en api.nubbo.app/v1/openapi.json.

Subidas y descargas
Los archivos no pasan por Nubbo. Para subir uno, pide la subida con POST /v1/buckets/{bucketId}/uploads, envía el archivo a la dirección prefirmada que te devuelve y termina con POST /v1/uploads/{uploadId}/complete. Para descargar, pide un enlace con POST /v1/files/{fileId}/download-link y descárgalo desde tu proveedor.
Límites
| Pro | Equipos | |
|---|---|---|
| Peticiones por minuto por clave | 60 | 120 |
| Peticiones al mes | 50.000 | 100.000 + 10.000 por plaza |
| Eventos de disparadores al mes | 20.000 | 50.000 + 5.000 por plaza |
La cuota es del espacio y se renueva con cada periodo de facturación. GET /v1/me, las consultas de los disparadores y las respuestas 401, 429 y 5xx no cuentan como peticiones. Cada evento que entrega un disparador cuenta como evento. Cada respuesta trae las cabeceras X-RateLimit-Remaining y X-Nubbo-Quota-Requests-Remaining, y en Configuración › API ves el uso del periodo.

Si algo falla
API_KEY_INVALID,API_KEY_REVOKEDoAPI_KEY_EXPIRED: la clave no vale, está revocada o ha caducado. Revisa la cabecera o crea otra clave.API_PLAN_REQUIRED: el espacio de la clave no tiene la API. Está en los planes Pro y Equipos.API_KEY_READ_ONLY: la clave es de solo lectura. Crea una con Lectura y escritura.API_RATE_LIMITED: demasiadas peticiones con esta clave. Espera los segundos deRetry-Aftery vuelve a probar.API_QUOTA_EXCEEDED: el espacio ha usado su límite del mes.details.resetsAtdice cuándo se renueva.
Cada error trae un requestId. Inclúyelo si nos escribes.
Más sobre la API de Nubbo. Para usarla sin escribir código, sigue la guía de Zapier, la de n8n o la de Make. Para usarla desde tu asistente de IA, mira cómo conectar Nubbo a Claude, ChatGPT o Cursor.
Preguntas frecuentes
¿Qué planes incluyen la API?
Pro y Equipos. Con Gratuito o Personal, las peticiones responden API_PLAN_REQUIRED.
¿Puedo leer archivos cifrados con la API?
No. Lo cifrado aparece sin nombre, ruta, tamaño ni tipo y cualquier cambio sobre ello se rechaza con API_ENCRYPTED_CONTENT.
¿Qué pasa si repito una petición por un fallo de red?
Envía la cabecera Idempotency-Key en tus POST y PATCH. Durante 24 horas, repetir la misma petición devuelve la primera respuesta y no crea nada dos veces.
¿Cambiará la API sin avisar?
No. Un cambio que rompa algo llega como /v2 y /v1 se mantiene al menos 12 meses, con las cabeceras Deprecation y Sunset.
Fuentes
Pasos comprobados con estas páginas.