Guías

Empieza con la API de Nubbo

De cero a tu primera petición en unos minutos. Crea una clave y empieza a gestionar tu almacenamiento desde tu propio código.

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

  1. En Nubbo, abre Configuración › API (o Equipo › API en un equipo) y pulsa Crear clave de API.

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

    Ventana Crear clave de API con el acceso, el alcance y la caducidad Ventana Crear clave de API con el acceso, el alcance y la caducidad
  3. 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.

    Ventana Tu clave de API con la clave lista para copiar Ventana Tu clave de API con la clave lista para copiar

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.

Terminal con la petición GET /v1/me y su respuesta Terminal con la petición GET /v1/me y su respuesta

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.

Referencia de la API de Nubbo con el ejemplo en curl Referencia de la API de Nubbo con el ejemplo en curl

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

ProEquipos
Peticiones por minuto por clave60120
Peticiones al mes50.000100.000 + 10.000 por plaza
Eventos de disparadores al mes20.00050.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.

Uso de la API del periodo en la configuración de Nubbo Uso de la API del periodo en la configuración de Nubbo

Si algo falla

  • API_KEY_INVALID, API_KEY_REVOKED o API_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 de Retry-After y vuelve a probar.
  • API_QUOTA_EXCEEDED: el espacio ha usado su límite del mes. details.resetsAt dice 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.