API Nubbo to API REST do pracy z Twoimi bucketami z własnego kodu: pliki, foldery, linki, prośby o pliki, galerie, etykiety, projekty i automatyzacje. W tym poradniku tworzysz klucz i wysyłasz pierwsze żądania za pomocą curl.
Co zyskujesz
- Zarządzasz swoją przestrzenią Nubbo z własnych programów, kluczami, które widzą tylko to, co wybierzesz.
- Przesyłasz i pobierasz pliki bezpośrednio między swoim kodem a dostawcą pamięci masowej.
- Reagujesz na nowe pliki, przesłania do próśb o pliki i aktywność dzięki wyzwalaczom.
Zanim zaczniesz
Potrzebujesz konta Nubbo z planem Pro lub Zespoły i terminala z curl. W zespole klucze API tworzy właściciel lub administrator.
Krok 1: utwórz klucz
W Nubbo otwórz Ustawienia › API (lub Zespół › API w zespole) i naciśnij Utwórz klucz API.
Nadaj mu nazwę i wybierz:
- Dostęp: Tylko odczyt lub Odczyt i zapis.
- Zakres: Cała przestrzeń lub Wybrane buckety i projekty. Klucz widzi tylko to, co tu wybierzesz.
- Wygaśnięcie: 30 dni, 90 dni, 1 rok lub Bez wygaśnięcia. Nubbo przypomni Ci 7 dni wcześniej.
Naciśnij Utwórz klucz. Nubbo poprosi o hasło, aby potwierdzić, że to Ty. Jeśli masz włączoną weryfikację dwuetapową, poprosi też o kod.

Skopiuj klucz i naciśnij Klucz zapisany. Zaczyna się od
nbk_i tylko teraz widzisz go w całości. Przechowuj go na serwerze lub w narzędziu, które będzie go używać, nigdy na stronie internetowej.

Krok 2: pierwsze żądanie
Wysyłaj klucz w nagłówku Authorization każdego żądania. Zacznij od GET /v1/me, które nie zużywa żądań:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_twoj_klucz"
Odpowiedź zawiera twoją przestrzeń, twój plan, limit na ten miesiąc oraz klucz z jego dostępem i zakresem. Oto fragment:
{
"workspace": { "id": "…", "name": "Studio Północ", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "Mój pierwszy klucz",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Następnie wyświetl swoje buckety i pliki z folderu:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_twoj_klucz"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=faktury/" \
-H "Authorization: Bearer nbk_twoj_klucz"
Listy zwracają data i nextCursor. Aby pobrać następną stronę, wyślij tę wartość w cursor. Gdy nextCursor ma wartość null, nie ma nic więcej.

Krok 3: dokumentacja
W Ustawienia › API naciśnij Zobacz dokumentację albo otwórz api.nubbo.app/v1/docs. Znajdziesz tam każdy zasób z polami i przykładami. Dokument OpenAPI jest pod adresem api.nubbo.app/v1/openapi.json.

Przesyłanie i pobieranie
Pliki nie przechodzą przez Nubbo. Aby przesłać plik, poproś o przesłanie przez POST /v1/buckets/{bucketId}/uploads, wyślij plik na otrzymany podpisany adres i zakończ przez POST /v1/uploads/{uploadId}/complete. Aby pobrać plik, poproś o link przez POST /v1/files/{fileId}/download-link i pobierz go od swojego dostawcy.
Limity
| Pro | Zespoły | |
|---|---|---|
| Żądania na minutę na klucz | 60 | 120 |
| Żądania na miesiąc | 50 000 | 100 000 + 10 000 za stanowisko |
| Zdarzenia wyzwalaczy na miesiąc | 20 000 | 50 000 + 5 000 za stanowisko |
Limit należy do przestrzeni i odnawia się z każdym okresem rozliczeniowym. GET /v1/me, odpytywanie wyzwalaczy oraz odpowiedzi 401, 429 i 5xx nie liczą się jako żądania. Każde zdarzenie dostarczone przez wyzwalacz liczy się jako zdarzenie. Każda odpowiedź zawiera nagłówki X-RateLimit-Remaining i X-Nubbo-Quota-Requests-Remaining, a w Ustawienia › API widzisz zużycie w danym okresie.

Jeśli coś pójdzie nie tak
API_KEY_INVALID,API_KEY_REVOKEDlubAPI_KEY_EXPIRED: klucz jest nieprawidłowy, unieważniony albo wygasł. Sprawdź nagłówek lub utwórz nowy klucz.API_PLAN_REQUIRED: przestrzeń klucza nie ma dostępu do API. Jest ono dostępne w planach Pro i Zespoły.API_KEY_READ_ONLY: klucz ma tylko odczyt. Utwórz klucz z dostępem Odczyt i zapis.API_RATE_LIMITED: za dużo żądań z tym kluczem. Odczekaj liczbę sekund zRetry-Afteri spróbuj ponownie.API_QUOTA_EXCEEDED: przestrzeń wykorzystała miesięczny limit.details.resetsAtmówi, kiedy się odnowi.
Każdy błąd zawiera requestId. Podaj go, jeśli do nas piszesz.
Więcej o API Nubbo. Aby korzystać z niego bez pisania kodu, skorzystaj z poradnika dla Zapiera, n8n lub Make. Aby korzystać z niego w asystencie AI, zobacz, jak połączyć Nubbo z Claude, ChatGPT lub Cursorem.
Najczęściej zadawane pytania
Które plany obejmują API?
Pro i Zespoły. W planie Bezpłatny lub Personal żądania zwracają API_PLAN_REQUIRED.
Czy mogę odczytywać zaszyfrowane pliki przez API?
Nie. Zaszyfrowana zawartość pojawia się bez nazwy, ścieżki, rozmiaru i typu, a każda jej zmiana jest odrzucana z kodem API_ENCRYPTED_CONTENT.
Co się stanie, jeśli powtórzę żądanie po błędzie sieci?
Wysyłaj nagłówek Idempotency-Key w żądaniach POST i PATCH. Przez 24 godziny powtórzenie tego samego żądania zwraca pierwszą odpowiedź i nic nie powstaje dwa razy.
Czy API zmieni się bez ostrzeżenia?
Nie. Zmiana, która coś psuje, trafia do /v2, a /v1 działa jeszcze co najmniej 12 miesięcy, z nagłówkami Deprecation i Sunset.
Źródła
Kroki sprawdzone na tych stronach.