Ръководства

Първи стъпки с API на Nubbo

От нула до първата ви заявка за няколко минути. Създайте ключ и започнете да управлявате хранилището си от собствения си код.

API на Nubbo е REST API за работа с вашите bucket-и от собствения ви код: файлове, папки, връзки, заявки за файлове, галерии, етикети, проекти и автоматизации. В това ръководство създавате ключ и изпращате първите си заявки с curl.

Какво получавате

  • Управлявате пространството си в Nubbo от своите програми, с ключове, които виждат само това, което изберете.
  • Качвате и изтегляте директно между кода си и доставчика на хранилище.
  • Реагирате на нови файлове, качвания в заявки за файлове и активност чрез тригерите.

Преди да започнете

Нужни са ви акаунт в Nubbo с план Pro или Екипи и терминал с curl. В екип API ключовете се създават от собственика или от администратор.

Стъпка 1: създайте ключ

  1. В Nubbo отворете Настройки › API (или Екип › API в екип) и натиснете Създаване на API ключ.

  2. Дайте му име и изберете:

    • Достъп: Само четене или Четене и запис.
    • Обхват: Цялото пространство или Избрани bucket-и и проекти. Ключът вижда само това, което изберете тук.
    • Изтичане: 30 дни, 90 дни, 1 година или Без изтичане. Nubbo ви напомня 7 дни по-рано.

    Натиснете Създаване на ключ. Nubbo ви пита за паролата, за да потвърди, че сте вие. Ако имате включена двуетапна проверка, ви пита и за кода.

    Прозорец Създаване на API ключ с достъпа, обхвата и изтичането Прозорец Създаване на API ключ с достъпа, обхвата и изтичането
  3. Копирайте ключа и натиснете Запазих го. Започва с nbk_ и това е единственият път, когато ще го видите изцяло. Пазете го на сървъра или в инструмента, който ще го използва, никога в уеб страница.

    Прозорец Вашият API ключ с ключа, готов за копиране Прозорец Вашият API ключ с ключа, готов за копиране

Стъпка 2: първата ви заявка

Изпращайте ключа в заглавката Authorization на всяка заявка. Започнете с GET /v1/me, която не изразходва заявки:

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

Отговорът съдържа вашето пространство, плана ви, квотата за месеца и ключа с неговия достъп и обхват. Ето откъс:

{
  "workspace": { "id": "…", "name": "Студио Север", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Моят първи ключ",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

След това покажете bucket-ите си и файловете в дадена папка:

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

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

Списъците връщат data и nextCursor. За следващата страница изпратете тази стойност в cursor. Когато nextCursor е null, няма повече.

Терминал със заявката GET /v1/me и нейния отговор Терминал със заявката GET /v1/me и нейния отговор

Стъпка 3: справочникът

В Настройки › API натиснете Преглед на документацията или отворете api.nubbo.app/v1/docs. Там е всеки ресурс с полетата и примерите му. Документът OpenAPI е на api.nubbo.app/v1/openapi.json.

Справочник на API на Nubbo с примера с curl Справочник на API на Nubbo с примера с curl

Качвания и изтегляния

Файловете не минават през Nubbo. За да качите файл, започнете качването с POST /v1/buckets/{bucketId}/uploads, изпратете файла на предварително подписания адрес, който получавате, и завършете с POST /v1/uploads/{uploadId}/complete. За изтегляне поискайте връзка с POST /v1/files/{fileId}/download-link и изтеглете файла от доставчика си.

Лимити

ProЕкипи
Заявки в минута на ключ60120
Заявки на месец50 000100 000 + 10 000 на място
Събития от тригери на месец20 00050 000 + 5 000 на място

Квотата е на пространството и се подновява с всеки период на фактуриране. GET /v1/me, проверките на тригерите и отговорите 401, 429 и 5xx не се броят за заявки. Всяко събитие, което тригер доставя, се брои за събитие от тригер. Всеки отговор съдържа заглавките X-RateLimit-Remaining и X-Nubbo-Quota-Requests-Remaining, а в Настройки › API виждате използването за периода.

Използване на API за периода в настройките на Nubbo Използване на API за периода в настройките на Nubbo

Ако нещо не работи

  • API_KEY_INVALID, API_KEY_REVOKED или API_KEY_EXPIRED: ключът не е валиден, отменен е или е изтекъл. Проверете заглавката или създайте друг ключ.
  • API_PLAN_REQUIRED: пространството на ключа не включва API. То е част от плановете Pro и Екипи.
  • API_KEY_READ_ONLY: ключът е само за четене. Създайте ключ с Четене и запис.
  • API_RATE_LIMITED: твърде много заявки с този ключ. Изчакайте секундите от Retry-After и опитайте отново.
  • API_QUOTA_EXCEEDED: пространството е изразходвало месечния си лимит. details.resetsAt показва кога се подновява.

Всяка грешка съдържа requestId. Посочете го, ако ни пишете.

Повече за API на Nubbo. За да го използвате, без да пишете код, следвайте ръководството за Zapier, за n8n или за Make. За да го използвате от своя AI асистент, вижте как да свържете Nubbo с Claude, ChatGPT или Cursor.

Често задавани въпроси

Кои планове включват API?

Pro и Екипи. С Безплатен или Personal заявките връщат API_PLAN_REQUIRED.

Мога ли да чета криптирани файлове чрез API?

Не. Криптираните елементи се показват без име, път, размер и тип, а всяка промяна по тях се отказва с API_ENCRYPTED_CONTENT.

Какво става, ако повторя заявка след мрежова грешка?

Изпращайте заглавката Idempotency-Key при заявките POST и PATCH. В продължение на 24 часа повтарянето на същата заявка връща първия отговор и нищо не се създава два пъти.

Ще се промени ли API без предупреждение?

Не. Несъвместима промяна излиза като /v2, а /v1 остава поне 12 месеца със заглавките Deprecation и Sunset.

Източници

Стъпките са проверени по тези страници.