Panduan

Mulai dengan API Nubbo

Dari nol ke permintaan pertama Anda dalam beberapa menit. Buat kunci dan mulai kelola penyimpanan Anda dari kode Anda sendiri.

API Nubbo adalah API REST untuk bekerja dengan bucket Anda dari kode Anda sendiri: file, folder, tautan, permintaan file, galeri, label, proyek, dan otomatisasi. Dalam panduan ini Anda membuat kunci dan mengirim permintaan pertama dengan curl.

Yang Anda dapatkan

  • Mengelola ruang Nubbo Anda dari program Anda, dengan kunci yang hanya melihat apa yang Anda pilih.
  • Mengunggah dan mengunduh langsung antara kode Anda dan penyedia penyimpanan Anda.
  • Bereaksi terhadap file baru, unggahan ke permintaan file, dan aktivitas dengan pemicu.

Sebelum memulai

Anda memerlukan akun Nubbo dengan paket Pro atau Tim dan terminal dengan curl. Di sebuah tim, kunci API dibuat oleh pemilik atau admin.

Langkah 1: buat kunci

  1. Di Nubbo, buka Pengaturan › API (atau Tim › API di sebuah tim) dan tekan Buat kunci API.

  2. Beri nama dan pilih:

    • Akses: Hanya baca atau Baca dan tulis.
    • Cakupan: Seluruh ruang atau Bucket dan proyek yang dipilih. Kunci hanya melihat apa yang Anda pilih di sini.
    • Masa berlaku: 30 hari, 90 hari, 1 tahun, atau Tidak ada masa berlaku. Nubbo memberi tahu Anda 7 hari sebelumnya.

    Tekan Buat kunci. Nubbo meminta kata sandi Anda untuk memastikan bahwa ini Anda. Jika verifikasi dua langkah aktif, Nubbo juga meminta kodenya.

    Jendela Buat kunci API dengan akses, cakupan, dan masa berlaku Jendela Buat kunci API dengan akses, cakupan, dan masa berlaku
  3. Salin kuncinya dan tekan Sudah saya simpan. Kunci diawali nbk_ dan hanya kali ini Anda melihatnya secara utuh. Simpan di server atau di alat yang akan memakainya, jangan pernah di halaman web.

    Jendela Kunci API Anda dengan kunci siap disalin Jendela Kunci API Anda dengan kunci siap disalin

Langkah 2: permintaan pertama Anda

Kirim kunci di header Authorization pada setiap permintaan. Mulailah dengan GET /v1/me, yang tidak memakai permintaan:

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

Responsnya memuat ruang Anda, paket Anda, kuota bulan ini, dan kunci beserta akses dan cakupannya. Ini cuplikannya:

{
  "workspace": { "id": "…", "name": "Studio Utara", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Kunci pertama saya",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Lalu tampilkan bucket Anda dan file dalam sebuah folder:

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

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

Daftar mengembalikan data dan nextCursor. Untuk halaman berikutnya, kirim nilai itu di cursor. Jika nextCursor bernilai null, tidak ada lagi.

Terminal dengan permintaan GET /v1/me dan responsnya Terminal dengan permintaan GET /v1/me dan responsnya

Langkah 3: referensi

Di Pengaturan › API, tekan Lihat dokumentasi, atau buka api.nubbo.app/v1/docs. Di sana ada setiap resource beserta kolom dan contohnya. Dokumen OpenAPI ada di api.nubbo.app/v1/openapi.json.

Referensi API Nubbo dengan contoh curl Referensi API Nubbo dengan contoh curl

Unggahan dan unduhan

File tidak melewati Nubbo. Untuk mengunggah, minta unggahan dengan POST /v1/buckets/{bucketId}/uploads, kirim file ke alamat presigned yang dikembalikan, dan selesaikan dengan POST /v1/uploads/{uploadId}/complete. Untuk mengunduh, minta tautan dengan POST /v1/files/{fileId}/download-link dan unduh dari penyedia Anda.

Batasan

ProTim
Permintaan per menit per kunci60120
Permintaan per bulan50.000100.000 + 10.000 per kursi
Event pemicu per bulan20.00050.000 + 5.000 per kursi

Kuota milik ruang dan diperbarui setiap periode penagihan. GET /v1/me, pemeriksaan pemicu, serta respons 401, 429, dan 5xx tidak dihitung sebagai permintaan. Setiap event yang dikirim pemicu dihitung sebagai event. Setiap respons membawa header X-RateLimit-Remaining dan X-Nubbo-Quota-Requests-Remaining, dan di Pengaturan › API Anda melihat penggunaan periode ini.

Penggunaan API periode ini di pengaturan Nubbo Penggunaan API periode ini di pengaturan Nubbo

Jika ada masalah

  • API_KEY_INVALID, API_KEY_REVOKED, atau API_KEY_EXPIRED: kunci tidak valid, sudah dicabut, atau sudah kedaluwarsa. Periksa header-nya atau buat kunci baru.
  • API_PLAN_REQUIRED: ruang kunci ini tidak memiliki API. API tersedia di paket Pro dan Tim.
  • API_KEY_READ_ONLY: kunci ini hanya baca. Buat kunci dengan Baca dan tulis.
  • API_RATE_LIMITED: terlalu banyak permintaan dengan kunci ini. Tunggu sesuai detik di Retry-After dan coba lagi.
  • API_QUOTA_EXCEEDED: ruang sudah memakai batas bulanannya. details.resetsAt menunjukkan kapan diperbarui.

Setiap error membawa requestId. Sertakan jika Anda menghubungi kami.

Selengkapnya tentang API Nubbo. Untuk memakainya tanpa menulis kode, ikuti panduan Zapier, n8n, atau Make. Untuk memakainya dari asisten AI Anda, lihat cara menghubungkan Nubbo ke Claude, ChatGPT, atau Cursor.

Pertanyaan yang sering diajukan

Paket apa saja yang menyertakan API?

Pro dan Tim. Dengan Gratis atau Personal, permintaan menjawab API_PLAN_REQUIRED.

Bisakah saya membaca file terenkripsi dengan API?

Tidak. Konten terenkripsi tampil tanpa nama, path, ukuran, atau jenis, dan setiap perubahan padanya ditolak dengan API_ENCRYPTED_CONTENT.

Apa yang terjadi jika saya mengulang permintaan karena gangguan jaringan?

Kirim header Idempotency-Key di permintaan POST dan PATCH Anda. Selama 24 jam, mengulang permintaan yang sama mengembalikan respons pertama dan tidak membuat apa pun dua kali.

Apakah API akan berubah tanpa pemberitahuan?

Tidak. Perubahan yang merusak sesuatu hadir sebagai /v2, dan /v1 tetap tersedia setidaknya 12 bulan, dengan header Deprecation dan Sunset.

Sumber

Langkah-langkah ini sudah dicek dengan halaman berikut.