A API do Nubbo é uma API REST para trabalhar com os seus buckets a partir do seu próprio código: ficheiros, pastas, links, pedidos de ficheiros, galerias, etiquetas, projetos e automatizações. Neste guia cria uma chave e faz os seus primeiros pedidos com curl.
O que consegue
- Gerir o seu espaço do Nubbo a partir dos seus programas, com chaves que só veem o que escolher.
- Carregar e transferir ficheiros diretamente entre o seu código e o seu fornecedor de armazenamento.
- Reagir a ficheiros novos, carregamentos em pedidos de ficheiros e atividade com os acionadores.
Antes de começar
Precisa de uma conta do Nubbo com o plano Pro ou Equipas e de um terminal com curl. Numa equipa, as chaves de API são criadas pelo proprietário ou por um administrador.
Passo 1: crie uma chave
No Nubbo, abra Definições › API (ou Equipa › API numa equipa) e prima Criar chave de API.
Dê-lhe um nome e escolha:
- Acesso: Só de leitura ou Leitura e escrita.
- Alcance: Todo o espaço ou Buckets e projetos escolhidos. A chave só vê o que escolher aqui.
- Expiração: 30 dias, 90 dias, 1 ano ou Sem expiração. O Nubbo avisa-o 7 dias antes.
Prima Criar chave. O Nubbo pede a sua palavra-passe para confirmar que é você. Se tiver a verificação em dois passos ativada, também pede o código.

Copie a chave e prima Já a guardei. Começa por
nbk_e é a única vez que a verá completa. Guarde-a no servidor ou na ferramenta que a vai usar, nunca numa página web.

Passo 2: o seu primeiro pedido
Envie a chave no cabeçalho Authorization de cada pedido. Comece por GET /v1/me, que não gasta pedidos:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_a_sua_chave"
A resposta traz o seu espaço, o seu plano, a quota do mês e a chave com o respetivo acesso e alcance. Este é um excerto:
{
"workspace": { "id": "…", "name": "Estúdio Norte", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "A 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 os seus buckets e os ficheiros de uma pasta:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_a_sua_chave"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=faturas/" \
-H "Authorization: Bearer nbk_a_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.

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

Carregamentos e transferências
Os ficheiros não passam pelo Nubbo. Para carregar um, peça o carregamento com POST /v1/buckets/{bucketId}/uploads, envie o ficheiro para o endereço pré-assinado que recebe e termine com POST /v1/uploads/{uploadId}/complete. Para transferir, peça um link com POST /v1/files/{fileId}/download-link e transfira o ficheiro a partir do seu fornecedor.
Limites
| Pro | Equipas | |
|---|---|---|
| Pedidos por minuto por chave | 60 | 120 |
| Pedidos por mês | 50.000 | 100.000 + 10.000 por lugar |
| Eventos de acionadores por mês | 20.000 | 50.000 + 5.000 por lugar |
A quota é do espaço e renova-se a cada período de faturação. GET /v1/me, as consultas dos acionadores e as respostas 401, 429 e 5xx não contam como pedidos. Cada evento entregue por um acionador conta como evento. Cada resposta traz os cabeçalhos X-RateLimit-Remaining e X-Nubbo-Quota-Requests-Remaining, e em Definições › API vê a utilização do período.

Se algo falhar
API_KEY_INVALID,API_KEY_REVOKEDouAPI_KEY_EXPIRED: a chave não é válida, foi revogada ou expirou. Verifique o cabeçalho ou crie outra chave.API_PLAN_REQUIRED: o espaço da chave não tem a API. Está nos planos Pro e Equipas.API_KEY_READ_ONLY: a chave é só de leitura. Crie uma com Leitura e escrita.API_RATE_LIMITED: demasiados pedidos com esta chave. Aguarde os segundos deRetry-Aftere volte a tentar.API_QUOTA_EXCEEDED: o espaço usou o limite do mês.details.resetsAtindica quando se renova.
Cada erro traz um requestId. Inclua-o se nos escrever.
Saiba mais sobre a API do Nubbo. Para a usar sem escrever código, siga o guia do Zapier, o do n8n ou o do Make. Para a usar a partir do seu assistente de IA, veja como ligar o Nubbo ao Claude, ChatGPT ou Cursor.
Perguntas frequentes
Que planos incluem a API?
Pro e Equipas. Com Grátis ou Personal, os pedidos respondem API_PLAN_REQUIRED.
Posso ler ficheiros encriptados com a API?
Não. O conteúdo encriptado aparece sem nome, caminho, tamanho nem tipo e qualquer alteração sobre ele é rejeitada com API_ENCRYPTED_CONTENT.
O que acontece se repetir um pedido por uma falha de rede?
Envie o cabeçalho Idempotency-Key nos seus POST e PATCH. Durante 24 horas, repetir o mesmo pedido devolve a primeira resposta e não cria nada duas vezes.
A API vai mudar sem aviso?
Não. Uma alteração que quebre algo chega como /v2 e a /v1 mantém-se pelo menos 12 meses, com os cabeçalhos Deprecation e Sunset.
Fontes
Passos verificados com estas páginas.