Посібники

Початок роботи з API Nubbo

Від нуля до першого запиту за кілька хвилин. Створіть ключ і керуйте своїм сховищем із власного коду.

API Nubbo є REST API для роботи з вашими бакетами з власного коду: файли, папки, посилання, запити на файли, галереї, мітки, проєкти й автоматизації. У цьому посібнику ви створите ключ і надішлете перші запити через curl.

Що ви отримуєте

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

Перед початком

Вам потрібні обліковий запис Nubbo на тарифі Pro або Команди і термінал із curl. У команді ключі API створює власник або адміністратор.

Крок 1: створіть ключ

  1. У Nubbo відкрийте Налаштування › API (або Команда › API в команді) і натисніть Створити ключ API.

  2. Дайте йому назву й виберіть:

    • Доступ: Лише читання або Читання і запис.
    • Область доступу: Увесь простір або Вибрані бакети й проєкти. Ключ бачить лише те, що ви тут виберете.
    • Термін дії: 30 днів, 90 днів, 1 рік або Без терміну дії. Nubbo нагадає вам за 7 днів.

    Натисніть Створити ключ. Nubbo попросить ваш пароль, щоб підтвердити, що це ви. Якщо у вас увімкнено двофакторну автентифікацію, Nubbo також попросить код.

    Вікно «Створити ключ API» з доступом, областю доступу й терміном дії Вікно «Створити ключ API» з доступом, областю доступу й терміном дії
  3. Скопіюйте ключ і натисніть Ключ збережено. Він починається з nbk_, і повністю ви бачите його лише цей раз. Зберігайте його на сервері або в інструменті, який його використовуватиме, і ніколи на вебсторінці.

    Вікно «Ваш ключ API» з ключем, готовим до копіювання Вікно «Ваш ключ API» з ключем, готовим до копіювання

Крок 2: перший запит

Надсилайте ключ у заголовку Authorization кожного запиту. Почніть із GET /v1/me, який не витрачає запитів:

curl https://api.nubbo.app/v1/me \
  -H "Authorization: Bearer nbk_vash_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
  }
}

Потім перегляньте свої бакети й файли папки:

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

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=rakhunky/" \
  -H "Authorization: Bearer nbk_vash_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. Щоб користуватися ним зі свого ШІ-асистента, подивіться, як підключити 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.

Джерела

Кроки перевірено за цими сторінками.