Руководства

Начало работы с 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_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
  }
}

Затем получите список bucket и файлы папки:

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

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=facturas/" \
  -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. Чтобы использовать API из своего 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.

Источники

Шаги проверены по этим страницам.