A API do Nubbo é uma API REST para trabalhar com seus buckets a partir do seu próprio código: arquivos, pastas, links, pedidos de arquivos, galerias, etiquetas, projetos e automações. Neste guia você cria uma chave e faz suas primeiras requisições com curl.
O que você ganha
- Gerenciar seu espaço do Nubbo pelos seus programas, com chaves que só veem o que você escolher.
- Enviar e baixar arquivos diretamente entre o seu código e o seu provedor de armazenamento.
- Reagir a arquivos novos, uploads em pedidos de arquivos e atividade com os gatilhos.
Antes de começar
Você precisa de uma conta do Nubbo com o plano Pro ou Equipes e de um terminal com curl. Em uma equipe, as chaves de API são criadas pelo proprietário ou por um administrador.
Passo 1: crie uma chave
No Nubbo, abra Configurações › API (ou Equipe › API em uma equipe) e clique em Criar chave de API.
Dê um nome a ela e escolha:
- Acesso: Somente leitura ou Leitura e escrita.
- Alcance: Todo o espaço ou Buckets e projetos escolhidos. A chave só vê o que você escolher aqui.
- Expiração: 30 dias, 90 dias, 1 ano ou Sem expiração. O Nubbo avisa você 7 dias antes.
Clique em Criar chave. O Nubbo pede sua senha para confirmar que é você. Se você usa a verificação em duas etapas, ele também pede o código.

Copie a chave e clique em Já guardei. Ela começa com
nbk_e é a única vez que você a verá inteira. Guarde-a no servidor ou na ferramenta que vai usá-la, nunca em uma página web.

Passo 2: sua primeira requisição
Envie a chave no cabeçalho Authorization de cada requisição. Comece por GET /v1/me, que não gasta requisições:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_sua_chave"
A resposta traz seu espaço, seu plano, a cota do mês e a chave com o acesso e o alcance dela. Este é um trecho:
{
"workspace": { "id": "…", "name": "Estúdio Norte", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "Minha primeira chave",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Depois, liste seus buckets e os arquivos de uma pasta:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_sua_chave"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=faturas/" \
-H "Authorization: Bearer nbk_sua_chave"
As listas devolvem data e nextCursor. Para a página seguinte, envie esse valor em cursor. Quando nextCursor é null, não há mais nada.

Passo 3: a referência
Em Configurações › API, clique em Ver documentação, ou abra api.nubbo.app/v1/docs. Lá está cada recurso com seus campos e exemplos. O documento OpenAPI está em api.nubbo.app/v1/openapi.json.

Uploads e downloads
Os arquivos não passam pelo Nubbo. Para enviar um, peça o upload com POST /v1/buckets/{bucketId}/uploads, envie o arquivo para o endereço pré-assinado que você recebe e termine com POST /v1/uploads/{uploadId}/complete. Para baixar, peça um link com POST /v1/files/{fileId}/download-link e baixe o arquivo do seu provedor.
Limites
| Pro | Equipes | |
|---|---|---|
| Requisições por minuto por chave | 60 | 120 |
| Requisições por mês | 50.000 | 100.000 + 10.000 por lugar |
| Eventos de gatilhos por mês | 20.000 | 50.000 + 5.000 por lugar |
A cota é do espaço e se renova a cada período de cobrança. GET /v1/me, as consultas dos gatilhos e as respostas 401, 429 e 5xx não contam como requisições. Cada evento entregue por um gatilho conta como evento. Toda resposta traz os cabeçalhos X-RateLimit-Remaining e X-Nubbo-Quota-Requests-Remaining, e em Configurações › API você vê o uso do período.

Se algo falhar
API_KEY_INVALID,API_KEY_REVOKEDouAPI_KEY_EXPIRED: a chave não é válida, foi revogada ou expirou. Confira o cabeçalho ou crie outra chave.API_PLAN_REQUIRED: o espaço da chave não tem a API. Ela está nos planos Pro e Equipes.API_KEY_READ_ONLY: a chave é somente leitura. Crie uma com Leitura e escrita.API_RATE_LIMITED: requisições demais com esta chave. Espere os segundos deRetry-Aftere tente de novo.API_QUOTA_EXCEEDED: o espaço usou o limite do mês.details.resetsAtdiz quando ele se renova.
Cada erro traz um requestId. Inclua-o se escrever para nós.
Saiba mais sobre a API do Nubbo. Para usá-la sem escrever código, siga o guia do Zapier, o do n8n ou o do Make. Para usá-la pelo seu assistente de IA, veja como conectar o Nubbo ao Claude, ChatGPT ou Cursor.
Perguntas frequentes
Quais planos incluem a API?
Pro e Equipes. Com Gratuito ou Personal, as requisições respondem API_PLAN_REQUIRED.
Posso ler arquivos criptografados com a API?
Não. O conteúdo criptografado aparece sem nome, caminho, tamanho nem tipo e qualquer alteração nele é recusada com API_ENCRYPTED_CONTENT.
O que acontece se eu repetir uma requisição por causa de uma falha de rede?
Envie o cabeçalho Idempotency-Key nos seus POST e PATCH. Durante 24 horas, repetir a mesma requisição devolve a primeira resposta e não cria nada duas vezes.
A API vai mudar sem aviso?
Não. Uma mudança que quebre algo chega como /v2 e a /v1 continua por pelo menos 12 meses, com os cabeçalhos Deprecation e Sunset.
Fontes
Passos verificados com estas páginas.