A Nubbo API egy REST API, amellyel a saját kódodból dolgozhatsz a bucketjeiddel: fájlok, mappák, linkek, fájlkérések, galériák, címkék, projektek és automatizálások. Ebben az útmutatóban létrehozol egy kulcsot, és curllal elküldöd az első kéréseidet.
Mit kapsz
- A programjaidból kezelheted a Nubbo-teredet, olyan kulcsokkal, amelyek csak azt látják, amit kiválasztasz.
- Közvetlen feltöltés és letöltés a kódod és a tárhelyszolgáltatód között.
- Eseményindítókkal reagálhatsz új fájlokra, fájlkérésekbe érkező feltöltésekre és tevékenységre.
Mielőtt elkezdenéd
Kell egy Nubbo-fiók Pro vagy Csapatok csomaggal és egy terminál curllal. Csapatban az API-kulcsokat a tulajdonos vagy egy adminisztrátor hozza létre.
1. lépés: hozz létre egy kulcsot
A Nubbóban nyisd meg a Beállítások › API részt (csapatban a Csapat › API részt), és kattints az API-kulcs létrehozása gombra.
Adj neki nevet, és válaszd ki:
- Hozzáférés: Csak olvasás vagy Olvasás és írás.
- Hatókör: A teljes tér vagy Kiválasztott bucketek és projektek. A kulcs csak azt látja, amit itt kiválasztasz.
- Lejárat: 30 nap, 90 nap, 1 év vagy Nem jár le. A Nubbo 7 nappal előtte figyelmeztet.
Kattints a Kulcs létrehozása gombra. A Nubbo a jelszavadat kéri, hogy megerősítse, hogy te vagy. Ha be van kapcsolva a kétlépcsős ellenőrzés, a kódot is kéri.

Másold ki a kulcsot, és kattints az Elmentettem gombra.
nbk_előtaggal kezdődik, és csak most látod teljes egészében. Tárold a szerveren vagy abban az eszközben, amely használni fogja, soha ne egy weboldalon.

2. lépés: az első kérésed
Küldd a kulcsot minden kérés Authorization fejlécében. Kezdd a GET /v1/me kéréssel, amely nem fogyaszt kéréseket:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_a_kulcsod"
A válasz tartalmazza a teredet, a csomagodat, a havi kvótát és a kulcsot a hozzáférésével és a hatókörével. Ez egy részlet:
{
"workspace": { "id": "…", "name": "Északi Stúdió", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "Az első kulcsom",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Ezután listázd a bucketjeidet és egy mappa fájljait:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_a_kulcsod"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=szamlak/" \
-H "Authorization: Bearer nbk_a_kulcsod"
A listák data és nextCursor mezőt adnak vissza. A következő oldalhoz küldd el ezt az értéket a cursor paraméterben. Ha a nextCursor értéke null, nincs több.

3. lépés: a referencia
A Beállítások › API részben kattints a Dokumentáció megtekintése gombra, vagy nyisd meg az api.nubbo.app/v1/docs oldalt. Ott minden erőforrás megtalálható a mezőivel és példákkal. Az OpenAPI-dokumentum az api.nubbo.app/v1/openapi.json címen érhető el.

Feltöltés és letöltés
A fájlok nem mennek át a Nubbón. Feltöltéshez kérd a feltöltést a POST /v1/buckets/{bucketId}/uploads kéréssel, küldd a fájlt a visszakapott előre aláírt címre, és zárd le a POST /v1/uploads/{uploadId}/complete kéréssel. Letöltéshez kérj linket a POST /v1/files/{fileId}/download-link kéréssel, és töltsd le a fájlt a szolgáltatódtól.
Korlátok
| Pro | Csapatok | |
|---|---|---|
| Kérés percenként kulcsonként | 60 | 120 |
| Kérés havonta | 50 000 | 100 000 + 10 000 helyenként |
| Eseményindító-esemény havonta | 20 000 | 50 000 + 5 000 helyenként |
A kvóta a téré, és minden számlázási időszakkal megújul. A GET /v1/me, az eseményindítók lekérdezései és a 401, 429 és 5xx válaszok nem számítanak kérésnek. Minden esemény, amelyet egy eseményindító kézbesít, eseménynek számít. Minden válasz tartalmazza az X-RateLimit-Remaining és az X-Nubbo-Quota-Requests-Remaining fejlécet, a Beállítások › API részben pedig látod az időszak használatát.

Ha valami nem működik
API_KEY_INVALID,API_KEY_REVOKEDvagyAPI_KEY_EXPIRED: a kulcs érvénytelen, vissza lett vonva vagy lejárt. Ellenőrizd a fejlécet, vagy hozz létre egy új kulcsot.API_PLAN_REQUIRED: a kulcs terében nincs API. A Pro és a Csapatok csomagban érhető el.API_KEY_READ_ONLY: a kulcs csak olvasható. Hozz létre egyet Olvasás és írás hozzáféréssel.API_RATE_LIMITED: túl sok kérés ezzel a kulccsal. Várj aRetry-Afterszerinti másodpercig, és próbáld újra.API_QUOTA_EXCEEDED: a tér elhasználta a havi keretét. Adetails.resetsAtmegmondja, mikor újul meg.
Minden hiba tartalmaz egy requestId értéket. Add meg, ha írsz nekünk.
Többet erről: a Nubbo API. Kódírás nélküli használathoz kövesd a Zapier, az n8n vagy a Make útmutatóját. Ha az AI-asszisztensedből használnád, nézd meg, hogyan kapcsolhatod össze a Nubbót a Claude-dal, a ChatGPT-vel vagy a Cursorral.
Gyakori kérdések
Mely csomagok tartalmazzák az API-t?
A Pro és a Csapatok. Ingyenes vagy Personal csomaggal a kérések API_PLAN_REQUIRED választ adnak.
Olvashatok titkosított fájlokat az API-val?
Nem. A titkosított tartalom név, útvonal, méret és típus nélkül jelenik meg, és a rendszer minden rajta végzett módosítást API_ENCRYPTED_CONTENT hibával elutasít.
Mi történik, ha hálózati hiba miatt megismétlek egy kérést?
Küldd el az Idempotency-Key fejlécet a POST és PATCH kéréseidben. 24 órán át ugyanannak a kérésnek a megismétlése az első választ adja vissza, és semmit sem hoz létre kétszer.
Változhat az API előzetes értesítés nélkül?
Nem. Egy visszafelé nem kompatibilis változás /v2-ként érkezik, a /v1 pedig legalább 12 hónapig megmarad, a Deprecation és a Sunset fejlécekkel.
Források
A lépéseket ezekkel az oldalakkal ellenőriztük.