Návody

Začnite s API Nubbo

Od nuly k prvej požiadavke za pár minút. Vytvorte kľúč a začnite spravovať svoje úložisko z vlastného kódu.

API Nubbo je REST API na prácu s vašimi bucketmi z vlastného kódu: súbory, priečinky, odkazy, žiadosti o súbory, galérie, štítky, projekty a automatizácie. V tomto návode vytvoríte kľúč a pošlete prvé požiadavky cez curl.

Čo získate

  • Správu svojho priestoru Nubbo z vlastných programov, s kľúčmi, ktoré vidia iba to, čo vyberiete.
  • Nahrávanie a sťahovanie priamo medzi vaším kódom a vaším poskytovateľom úložiska.
  • Reakcie na nové súbory, nahrávania do žiadostí o súbory a aktivitu pomocou spúšťačov.

Skôr než začnete

Potrebujete účet Nubbo s plánom Pro alebo Tímy a terminál s curl. V tíme kľúče API vytvára vlastník alebo administrátor.

Krok 1: vytvorte kľúč

  1. V Nubbo otvorte Nastavenia › API (alebo Tím › API v tíme) a stlačte Vytvoriť kľúč API.

  2. Zadajte názov a vyberte:

    • Prístup: Iba čítanie alebo Čítanie a zápis.
    • Rozsah: Celý priestor alebo Vybrané buckety a projekty. Kľúč vidí iba to, čo tu vyberiete.
    • Platnosť: 30 dní, 90 dní, 1 rok alebo Bez expirácie. Nubbo vám to pripomenie 7 dní vopred.

    Stlačte Vytvoriť kľúč. Nubbo si vyžiada vaše heslo, aby potvrdilo, že ste to vy. Ak máte zapnuté dvojfaktorové overenie, vyžiada si aj kód.

    Okno Vytvoriť kľúč API s prístupom, rozsahom a platnosťou Okno Vytvoriť kľúč API s prístupom, rozsahom a platnosťou
  3. Skopírujte kľúč a stlačte Kľúč mám uložený. Začína sa na nbk_ a celý ho uvidíte iba teraz. Uložte ho na server alebo do nástroja, ktorý ho bude používať, nikdy nie do webovej stránky.

    Okno Váš kľúč API s kľúčom pripraveným na skopírovanie Okno Váš kľúč API s kľúčom pripraveným na skopírovanie

Krok 2: vaša prvá požiadavka

Posielajte kľúč v hlavičke Authorization každej požiadavky. Začnite s GET /v1/me, ktorá sa do požiadaviek nezapočítava:

curl https://api.nubbo.app/v1/me \
  -H "Authorization: Bearer nbk_vas_kluc"

Odpoveď obsahuje váš priestor, váš plán, kvótu mesiaca a kľúč s jeho prístupom a rozsahom. Toto je ukážka:

{
  "workspace": { "id": "…", "name": "Štúdio Sever", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Môj prvý kľúč",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Potom vypíšte svoje buckety a súbory jedného priečinka:

curl https://api.nubbo.app/v1/buckets \
  -H "Authorization: Bearer nbk_vas_kluc"

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=faktury/" \
  -H "Authorization: Bearer nbk_vas_kluc"

Zoznamy vracajú data a nextCursor. Pre ďalšiu stránku pošlite túto hodnotu v cursor. Keď je nextCursor rovné null, nič ďalšie už nie je.

Terminál s požiadavkou GET /v1/me a jej odpoveďou Terminál s požiadavkou GET /v1/me a jej odpoveďou

Krok 3: referencia

V Nastavenia › API stlačte Zobraziť dokumentáciu alebo otvorte api.nubbo.app/v1/docs. Nájdete tam každý zdroj s jeho poľami a príkladmi. Dokument OpenAPI je na api.nubbo.app/v1/openapi.json.

Referencia API Nubbo s príkladom v curl Referencia API Nubbo s príkladom v curl

Nahrávanie a sťahovanie

Súbory neprechádzajú cez Nubbo. Ak chcete súbor nahrať, začnite nahrávanie cez POST /v1/buckets/{bucketId}/uploads, pošlite súbor na predpodpísanú adresu, ktorú dostanete, a dokončite ho cez POST /v1/uploads/{uploadId}/complete. Na stiahnutie si vyžiadajte odkaz cez POST /v1/files/{fileId}/download-link a stiahnite súbor od svojho poskytovateľa.

Limity

ProTímy
Požiadavky za minútu na kľúč60120
Požiadavky za mesiac50 000100 000 + 10 000 za miesto
Udalosti spúšťačov za mesiac20 00050 000 + 5 000 za miesto

Kvóta patrí priestoru a obnovuje sa s každým fakturačným obdobím. GET /v1/me, dotazy spúšťačov a odpovede 401, 429 a 5xx sa do požiadaviek nezapočítavajú. Každá udalosť, ktorú spúšťač doručí, sa počíta ako udalosť spúšťača. Každá odpoveď obsahuje hlavičky X-RateLimit-Remaining a X-Nubbo-Quota-Requests-Remaining a v Nastavenia › API vidíte využitie za obdobie.

Využitie API za obdobie v nastaveniach Nubbo Využitie API za obdobie v nastaveniach Nubbo

Keď niečo zlyhá

  • API_KEY_INVALID, API_KEY_REVOKED alebo API_KEY_EXPIRED: kľúč nie je platný, bol zrušený alebo mu vypršala platnosť. Skontrolujte hlavičku alebo vytvorte nový kľúč.
  • API_PLAN_REQUIRED: priestor kľúča nemá API. Je súčasťou plánov Pro a Tímy.
  • API_KEY_READ_ONLY: kľúč je iba na čítanie. Vytvorte kľúč s prístupom Čítanie a zápis.
  • API_RATE_LIMITED: príliš veľa požiadaviek s týmto kľúčom. Počkajte toľko sekúnd, koľko uvádza Retry-After, a skúste to znova.
  • API_QUOTA_EXCEEDED: priestor vyčerpal mesačný limit. details.resetsAt uvádza, kedy sa obnoví.

Každá chyba obsahuje requestId. Uveďte ho, ak nám napíšete.

Viac o API Nubbo. Ak ho chcete používať bez písania kódu, postupujte podľa návodu pre Zapier, n8n alebo Make. Ak ho chcete používať zo svojho AI asistenta, pozrite si, ako prepojiť Nubbo s Claude, ChatGPT alebo Cursorom.

Časté otázky

Ktoré plány zahŕňajú API?

Pro a Tímy. S plánom Bezplatný alebo Personal odpovedajú požiadavky API_PLAN_REQUIRED.

Môžem cez API čítať zašifrované súbory?

Nie. Zašifrované položky sa zobrazujú bez názvu, cesty, veľkosti a typu a každá ich zmena sa odmietne s API_ENCRYPTED_CONTENT.

Čo sa stane, ak po výpadku siete zopakujem požiadavku?

Posielajte hlavičku Idempotency-Key v požiadavkách POST a PATCH. Počas 24 hodín vráti zopakovaná rovnaká požiadavka prvú odpoveď a nič nevytvorí dvakrát.

Zmení sa API bez upozornenia?

Nie. Zmena, ktorá niečo poruší, príde ako /v2 a /v1 zostane aspoň 12 mesiacov s hlavičkami Deprecation a Sunset.

Zdroje

Kroky sú overené podľa týchto stránok.