Folder

Folder mengatur file yang Anda unggah di dashboard. Secara default folder hanya berupa metadata — file tetap memiliki CID masing-masing dan tidak dipindahkan di IPFS — tetapi Anda juga dapat snapshot folder untuk mewujudkannya sebagai direktori UnixFS nyata dan mendapatkan satu CID untuk keseluruhan folder.

Kapan Anda perlu snapshot folder

Snapshot folder adalah satu CID direktori IPFS yang berisi setiap file dalam folder, dapat dialamatkan berdasarkan nama. Dengan itu Anda dapat:

• Membagikan seluruh folder melalui satu URL: https://ipfs.ninja/ipfs/{dirCid}/
• Meresolusi https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (atau gateway lainnya) secara langsung
• Memasukkan CID ke dalam ENS contenthash untuk meng-host situs statis
• Menggunakannya sebagai base CID koleksi NFT sehingga setiap token merujuk ke ipfs://{dirCid}/<id>.json
• Menyematkan direktori di mana pun — setiap gateway IPFS di dunia tahu cara meresolusi CID direktori UnixFS

Snapshot bersifat content-addressed: isi folder yang identik selalu menghasilkan CID yang sama. Melakukan snapshot ulang pada folder yang belum Anda ubah akan mengembalikan CID yang sama seperti sebelumnya. Menambah/menghapus/mengganti nama file menghasilkan CID baru; CID sebelumnya tetap disematkan dan dapat diresolusi selama Anda tidak menghapus file-filenya.

Buat folder

POST /folders

Parameter	Tipe	Wajib	Deskripsi
name	string	Ya	Nama tampilan.
parentFolderId	string | null	Tidak	ID folder induk untuk folder bersarang. Kosongkan untuk folder tingkat-root.

Contoh

curl -X POST https://api.ipfs.ninja/folders \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My NFT collection" }'

Mengembalikan:

{
  "folderId": "1f8e2c3a-…",
  "name": "My NFT collection",
  "parentFolderId": null,
  "createdAt": 1746360000000
}

Folder yang baru dibuat belum memiliki snapshot. Field latestSnapshot muncul pada folder setelah Anda memanggil POST /folders/{id}/snapshot (lihat di bawah) dan pada respons GET /folders berikutnya.

Daftar folder

GET /folders

Mengembalikan setiap folder di akun Anda, baik tingkat-root maupun bersarang, dengan CID snapshot terakhir untuk masing-masing (jika ada).

[
  {
    "folderId": "1f8e2c3a-…",
    "name": "My NFT collection",
    "parentFolderId": null,
    "createdAt": 1746360000000,
    "fileCount": 42,
    "latestSnapshot": {
      "cid": "QmRZx5…",
      "takenAt": 1746421000000,
      "fileCount": 42
    }
  }
]

fileCount mencerminkan isi folder saat ini; latestSnapshot.fileCount mencerminkan isi pada saat snapshot terakhir dibuat. Jika keduanya berbeda, CID snapshot tetap dapat diresolusi tetapi sudah usang — lakukan snapshot ulang untuk memperbaruinya.

Pindahkan file ke dalam folder

PUT /files/{cid}/move

Parameter	Tipe	Wajib	Deskripsi
folderId	string | null	Ya	ID folder tujuan, atau null untuk memindahkan file ke root.

curl -X PUT https://api.ipfs.ninja/files/Qm.../move \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "1f8e2c3a-…" }'

Snapshot folder (dapatkan CID direktori UnixFS)

POST /folders/{folderId}/snapshot

Wujudkan folder sebagai direktori UnixFS nyata pada kluster IPFS dan sematkan hasilnya. Mengembalikan satu CID untuk seluruh folder. Nama anak diambil dari fileName masing-masing file; duplikat diselesaikan secara otomatis.

Tidak diperlukan body permintaan; parameter path mengidentifikasi folder.

Contoh

curl -X POST https://api.ipfs.ninja/folders/1f8e2c3a-.../snapshot \
  -H "X-Api-Key: bws_your_api_key_here"

Mengembalikan:

{
  "ok": true,
  "folderId": "1f8e2c3a-…",
  "cid": "QmRZx5VgFHDsG7ECvaKkZBS4ydmkdAkDyaKyF71RYvh8",
  "fileCount": 42,
  "sizeBytes": 8421376,
  "takenAt": 1746421000000,
  "ipfsUrl": "https://ipfs.ninja/ipfs/QmRZx5.../"
}

CID juga disimpan secara permanen di baris folder, sehingga panggilan GET /folders berikutnya mengembalikannya sebagai latestSnapshot.cid tanpa perlu snapshot lagi.

Meresolusi snapshot

Setelah snapshot disematkan, CID direktori dapat diresolusi melalui gateway IPFS mana pun. Pola URL paling sederhana:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → that one file

Kluster menyematkan secara rekursif, sehingga anak-anaknya juga dapat diresolusi — bahkan jika Anda kemudian menghapus file asli dari akun Anda, salinan snapshot tetap ada karena itu adalah pin terpisah yang merekursi melalui direktori.

Snapshot ulang

Melakukan snapshot ulang pada folder yang tidak berubah mengembalikan CID yang sama — CID direktori bersifat content-addressed, sehingga isi yang identik selalu menghasilkan hash yang sama, dan panggilan pin kluster mengenali duplikat tersebut dan menjadi no-op di sisinya.

Catatan: jalur snapshot itu sendiri tidak gratis meskipun hasilnya adalah CID yang sama. Setiap panggilan membaca ulang byte setiap file dari IPFS dan mengunggahnya kembali sebagai multipart ke endpoint /add kluster — di situlah proses pembungkusan-dengan-direktori terjadi. Untuk folder umum (≤100 file kecil) ini masih selesai dalam beberapa detik; untuk folder yang sangat besar, sebaiknya panggil snapshot hanya ketika isinya benar-benar berubah.

Memanggil snapshot setelah Anda menambah atau menghapus file akan menghasilkan CID yang berbeda; CID sebelumnya terus dapat diresolusi selama Anda tidak menghapus file-file yang mendasarinya.

Batasan

• Folder harus berisi setidaknya satu file. Folder kosong mengembalikan 400 — folder is empty.
• Karakter nama file di-URL-encode dalam unggahan multipart yang diterima Kubo; URL gateway mungkin memerlukan percent-encoding untuk spasi atau karakter non-ASCII dalam nama file Anda.
• Snapshot diperhitungkan dalam total pin paket Anda tepat satu kali per CID unik — blok file dideduplikasi, sehingga snapshot sebagian besar hanya menambahkan node direktori kecil di atas file yang sudah Anda sematkan.

Perbarui folder

PUT /folders/{folderId}

Parameter	Tipe	Wajib	Deskripsi
name	string	Tidak	Nama tampilan baru.
parentFolderId	string | null	Tidak	Pindahkan folder ke induk lain. null memindahkannya ke root.

Hapus folder

DELETE /folders/{folderId}

Menghapus folder dan secara rekursif meluas ke setiap file dan subfolder di dalamnya. Tunduk pada guard keamanan CID-bersama yang sama seperti penghapusan file individual — jika pengguna lain masih menyematkan CID yang Anda unggah, unpin Anda tidak menghapusnya untuk mereka.

{
  "deleted": true,
  "filesDeleted": 42,
  "foldersDeleted": 3
}

Konfigurasi S3 CORS untuk folder / bucket

Folder yang diekspos melalui API yang kompatibel dengan S3 bertindak sebagai bucket. Jika Anda menjalankan API tersebut dari JavaScript browser, Anda memerlukan aturan CORS pada bucket agar preflight browser lolos. Dua permukaan yang setara menyimpan ke penyimpanan yang sama:

• PUT /folders/{folderId}/cors — endpoint REST ini, diautentikasi JWT (digunakan oleh dashboard)
• Subresource S3 PUT /{bucket}?cors — diautentikasi SigV4 (digunakan oleh AWS SDK, lihat s3-compatibility.md)

PUT pada endpoint ini juga mengklaim nama folder sebagai nama bucket unik secara global jika belum diklaim.

PUT /folders/{folderId}/cors

Atur aturan CORS untuk bucket S3 folder tersebut. Hingga 5 aturan per bucket, total 64 KB.

Parameter	Tipe	Wajib	Deskripsi
rules	CorsRule[]	Ya	Array aturan CORS berbentuk AWS (lihat di bawah). Tidak boleh kosong.
bucketName	string	Tidak	Nama bucket S3 eksplisit. Default ke nama tampilan folder. Jika nama yang diinginkan sudah diklaim secara global, teruskan alternatif di sini.

Setiap CorsRule:

Field	Tipe	Wajib	Deskripsi
AllowedOrigins	string[]	Ya	Origin yang diizinkan mengirim permintaan. Mendukung wildcard (https://*.myapp.com). Gunakan * untuk origin apa pun.
AllowedMethods	string[]	Ya	Satu atau lebih dari GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Tidak	Header yang boleh disertakan browser pada permintaan. Default: tidak ada. Gunakan ["*"] untuk mengizinkan semua (direkomendasikan untuk AWS SDK v3 yang mengirim Authorization, x-amz-*, dll.).
ExposeHeaders	string[]	Tidak	Header respons yang dapat dibaca oleh JavaScript browser. Sertakan ETag dan x-amz-meta-cid jika aplikasi Anda memerlukan CID yang dikembalikan.
MaxAgeSeconds	number	Tidak	Berapa lama browser meng-cache preflight. 0-86400. Default 3600.
ID	string	Tidak	Label bebas untuk aturan tersebut.

Contoh permintaan

curl -X PUT https://api.ipfs.ninja/folders/17f6dfd8-519c-4d0e-8f3a-5988a1d34ef2/cors \
  -H "Authorization: Bearer $COGNITO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"],
      "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      "MaxAgeSeconds": 3600
    }]
  }'

Respons 200 OK

{ "success": true, "rules": [ { "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"], "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"], "AllowedHeaders": ["*"], "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"], "MaxAgeSeconds": 3600 } ] }

GET /folders/{folderId}/cors

Mengembalikan aturan CORS saat ini beserta nama bucket (jika sudah diklaim).

{
  "rules": [ … ],
  "bucketName": "my-project"
}

DELETE /folders/{folderId}/cors

Menghapus semua aturan CORS. Preflight browser terhadap bucket akan gagal secara default sampai aturan baru diatur.

Alternatif dashboard

Di halaman File, menu aksi setiap folder memiliki entri S3 CORS yang membuka editor berbasis form. Penyimpanan yang mendasarinya sama dengan endpoint REST ini dan dengan PutBucketCors melalui API S3.