API-ul Nubbo este un API REST pentru a lucra cu bucketurile tale din propriul cod: fișiere, dosare, linkuri, cereri de fișiere, galerii, etichete, proiecte și automatizări. În acest ghid creezi o cheie și trimiți primele cereri cu curl.
Ce obții
- Gestionezi spațiul tău Nubbo din propriile programe, cu chei care văd doar ce alegi tu.
- Încarci și descarci direct între codul tău și providerul tău de stocare.
- Reacționezi la fișiere noi, încărcări în cereri de fișiere și activitate cu ajutorul declanșatoarelor.
Înainte să începi
Ai nevoie de un cont Nubbo cu planul Pro sau Echipe și de un terminal cu curl. Într-o echipă, cheile API le creează proprietarul sau un administrator.
Pasul 1: creează o cheie
În Nubbo, deschide Setări › API (sau Echipă › API într-o echipă) și apasă Creează cheie API.
Dă-i un nume și alege:
- Acces: Doar citire sau Citire și scriere.
- Domeniu: Tot spațiul sau Bucketuri și proiecte alese. Cheia vede doar ce alegi aici.
- Expirare: 30 de zile, 90 de zile, 1 an sau Fără expirare. Nubbo te anunță cu 7 zile înainte.
Apasă Creează cheia. Nubbo îți cere parola ca să confirme că ești tu. Dacă ai verificarea în doi pași activată, îți cere și codul.

Copiază cheia și apasă Am salvat-o. Începe cu
nbk_și este singura dată când o vezi întreagă. Păstreaz-o pe server sau în instrumentul care o va folosi, niciodată într-o pagină web.

Pasul 2: prima ta cerere
Trimite cheia în antetul Authorization al fiecărei cereri. Începe cu GET /v1/me, care nu consumă cereri:
curl https://api.nubbo.app/v1/me \
-H "Authorization: Bearer nbk_cheia_ta"
Răspunsul conține spațiul tău, planul tău, cota lunii și cheia cu accesul și domeniul ei. Iată un extras:
{
"workspace": { "id": "…", "name": "Studio Nord", "kind": "PERSONAL" },
"plan": "PRO",
"key": {
"name": "Prima mea cheie",
"prefix": "nbk_3jKF3m",
"access": "READ",
"allResources": true
},
"quota": {
"requests": { "used": 0, "limit": 50000, "remaining": 50000 },
"events": { "used": 0, "limit": 20000, "remaining": 20000 },
"ratePerMinute": 60
}
}
Apoi listează bucketurile tale și fișierele dintr-un dosar:
curl https://api.nubbo.app/v1/buckets \
-H "Authorization: Bearer nbk_cheia_ta"
curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=facturi/" \
-H "Authorization: Bearer nbk_cheia_ta"
Listele întorc data și nextCursor. Pentru pagina următoare, trimite acea valoare în cursor. Când nextCursor este null, nu mai există nimic.

Pasul 3: documentația
În Setări › API, apasă Vezi documentația sau deschide api.nubbo.app/v1/docs. Acolo găsești fiecare resursă cu câmpurile și exemplele ei. Documentul OpenAPI este la api.nubbo.app/v1/openapi.json.

Încărcări și descărcări
Fișierele nu trec prin Nubbo. Ca să încarci unul, cere încărcarea cu POST /v1/buckets/{bucketId}/uploads, trimite fișierul la adresa presemnată pe care o primești și termină cu POST /v1/uploads/{uploadId}/complete. Ca să descarci, cere un link cu POST /v1/files/{fileId}/download-link și descarcă fișierul de la providerul tău.
Limite
| Pro | Echipe | |
|---|---|---|
| Cereri pe minut per cheie | 60 | 120 |
| Cereri pe lună | 50.000 | 100.000 + 10.000 per loc |
| Evenimente de declanșator pe lună | 20.000 | 50.000 + 5.000 per loc |
Cota aparține spațiului și se reînnoiește la fiecare perioadă de facturare. GET /v1/me, interogările declanșatoarelor și răspunsurile 401, 429 și 5xx nu se numără drept cereri. Fiecare eveniment livrat de un declanșator se numără drept eveniment. Fiecare răspuns conține antetele X-RateLimit-Remaining și X-Nubbo-Quota-Requests-Remaining, iar în Setări › API vezi consumul din perioadă.

Dacă ceva nu merge
API_KEY_INVALID,API_KEY_REVOKEDsauAPI_KEY_EXPIRED: cheia nu este validă, a fost revocată sau a expirat. Verifică antetul sau creează altă cheie.API_PLAN_REQUIRED: spațiul cheii nu are API-ul. Este inclus în planurile Pro și Echipe.API_KEY_READ_ONLY: cheia este doar pentru citire. Creează una cu Citire și scriere.API_RATE_LIMITED: prea multe cereri cu această cheie. Așteaptă secundele dinRetry-Afterși încearcă din nou.API_QUOTA_EXCEEDED: spațiul și-a folosit limita lunară.details.resetsAtîți spune când se reînnoiește.
Fiecare eroare conține un requestId. Include-l dacă ne scrii.
Mai multe despre API-ul Nubbo. Ca să-l folosești fără să scrii cod, urmează ghidul pentru Zapier, cel pentru n8n sau cel pentru Make. Ca să-l folosești din asistentul tău AI, vezi cum să conectezi Nubbo la Claude, ChatGPT sau Cursor.
Întrebări frecvente
Ce planuri includ API-ul?
Pro și Echipe. Cu Gratuit sau Personal, cererile răspund cu API_PLAN_REQUIRED.
Pot citi fișiere criptate prin API?
Nu. Conținutul criptat apare fără nume, cale, dimensiune sau tip, iar orice modificare asupra lui este respinsă cu API_ENCRYPTED_CONTENT.
Ce se întâmplă dacă repet o cerere după o eroare de rețea?
Trimite antetul Idempotency-Key în cererile POST și PATCH. Timp de 24 de ore, repetarea aceleiași cereri întoarce primul răspuns și nu creează nimic de două ori.
Se va schimba API-ul fără anunț?
Nu. O schimbare care strică ceva vine ca /v2, iar /v1 rămâne cel puțin 12 luni, cu antetele Deprecation și Sunset.
Surse
Pași verificați cu aceste pagini.