Guias

Comece a usar a API do Nubbo

Do zero à sua primeira requisição em poucos minutos. Crie uma chave e comece a gerenciar seu armazenamento pelo seu próprio código.

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

  1. No Nubbo, abra Configurações › API (ou Equipe › API em uma equipe) e clique em Criar chave de API.

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

    Janela Criar chave de API com o acesso, o alcance e a expiração Janela Criar chave de API com o acesso, o alcance e a expiração
  3. 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.

    Janela Sua chave de API com a chave pronta para copiar Janela Sua chave de API com a chave pronta para copiar

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.

Terminal com a requisição GET /v1/me e a resposta Terminal com a requisição GET /v1/me e a resposta

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.

Referência da API do Nubbo com o exemplo em curl Referência da API do Nubbo com o exemplo em curl

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

ProEquipes
Requisições por minuto por chave60120
Requisições por mês50.000100.000 + 10.000 por lugar
Eventos de gatilhos por mês20.00050.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.

Uso da API no período nas configurações do Nubbo Uso da API no período nas configurações do Nubbo

Se algo falhar

  • API_KEY_INVALID, API_KEY_REVOKED ou API_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 de Retry-After e tente de novo.
  • API_QUOTA_EXCEEDED: o espaço usou o limite do mês. details.resetsAt diz 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.