資料夾

資料夾用於在儀表板中組織您上傳的檔案。它們預設僅為中繼資料 — 檔案保留自己的 CID，且不會在 IPFS 上被移動 — 但您也可以對資料夾建立快照，將其實體化為真正的 UnixFS 目錄，並為整個資料夾取得一個 CID。

何時應為資料夾建立快照

資料夾快照是一個包含資料夾中每個檔案的 IPFS 目錄 CID，可依名稱定址。透過它您可以：

• 透過一個 URL 分享整個資料夾：https://ipfs.ninja/ipfs/{dirCid}/
• 直接解析 https://ipfs.ninja/ipfs/{dirCid}/photo.jpg（或任何其他閘道）
• 將 CID 放入 ENS contenthash 以託管靜態網站
• 將其作為 NFT 集合的基礎 CID，讓每個代幣參照 ipfs://{dirCid}/<id>.json
• 將該目錄固定在其他任何地方 — 世界上每個 IPFS 閘道都知道如何解析 UnixFS 目錄 CID

快照是內容定址的：相同的資料夾內容永遠會產生相同的 CID。對未變更的資料夾重新建立快照會傳回與先前相同的 CID。新增／移除／重新命名檔案會產生新的 CID；只要您不刪除其中的檔案，先前的 CID 仍會保持固定並可解析。

建立資料夾

POST /folders

參數	類型	必填	描述
name	string	是	顯示名稱。
parentFolderId	string | null	否	巢狀資料夾的父資料夾 ID。若為根層級資料夾則省略。

範例

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" }'

傳回：

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

新建立的資料夾沒有快照。當您呼叫 POST /folders/{id}/snapshot（見下文）後，latestSnapshot 欄位會出現在資料夾上，並在後續的 GET /folders 回應中出現。

列出資料夾

GET /folders

傳回您帳戶中的每個資料夾，包含根層級與巢狀資料夾，並附上每個資料夾最後的快照 CID（若有）。

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

fileCount 反映資料夾目前的內容；latestSnapshot.fileCount 反映上次快照時的內容。若兩者不同，快照 CID 仍可解析但已過期 — 重新建立快照以更新。

將檔案移入資料夾

PUT /files/{cid}/move

參數	類型	必填	描述
folderId	string | null	是	目標資料夾 ID，或 null 以將檔案移至根層級。

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-…" }'

為資料夾建立快照（取得 UnixFS 目錄 CID）

POST /folders/{folderId}/snapshot

將資料夾實體化為 IPFS 叢集上真正的 UnixFS 目錄，並固定結果。為整個資料夾傳回一個 CID。子項的名稱來自每個檔案的 fileName；重複名稱會自動去除衝突。

不需要請求主體；路徑參數即可識別資料夾。

範例

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

傳回：

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

該 CID 也會保存在資料夾記錄中，因此後續的 GET /folders 呼叫會將其作為 latestSnapshot.cid 傳回，無需再次建立快照。

解析快照

一旦快照被固定，目錄 CID 就可以透過任何 IPFS 閘道解析。最簡單的 URL 模式：

https://ipfs.ninja/ipfs/{dirCid}/         → 目錄列表
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → 該單一檔案

叢集會遞迴固定，因此子項也可解析 — 即使您之後從帳戶中刪除了原始檔案，快照的副本仍會存留，因為它是一個透過目錄遞迴的獨立固定。

重新建立快照

對未變更的資料夾重新建立快照會傳回相同的 CID — 目錄 CID 是內容定址的，因此相同的內容永遠會產生相同的雜湊，且叢集的固定呼叫會識別出重複並在其端視為無操作。

注意：即使結果為相同的 CID，快照本身的路徑並非免費。每次呼叫都會從 IPFS 讀回每個檔案的位元組，並以 multipart 重新上傳到叢集的 /add 端點 — 這就是包裝目錄（wrap-with-directory）發生的地方。對於典型的資料夾（≤100 個小檔案）這仍能在幾秒內完成；對於非常大的資料夾，建議僅在內容實際變更時才呼叫快照。

在新增或移除檔案後呼叫快照會產生不同的 CID；只要您不刪除其底層檔案，先前的 CID 會繼續可解析。

限制

• 資料夾必須至少包含一個檔案。空資料夾會傳回 400 — folder is empty。
• 檔名字元在 Kubo 所接受的 multipart 上傳中會進行 URL 編碼；如果您的檔名中包含空格或非 ASCII 字元，閘道 URL 可能需要百分比編碼。
• 快照每個唯一 CID 僅計入您方案的固定總數一次 — 檔案區塊會進行去重，因此快照大多只是在您已固定的檔案上再增加一個微小的目錄節點。

更新資料夾

PUT /folders/{folderId}

參數	類型	必填	描述
name	string	否	新的顯示名稱。
parentFolderId	string | null	否	重新指定資料夾的父層。null 會將其移至根層級。

刪除資料夾

DELETE /folders/{folderId}

刪除資料夾，並遞迴串聯刪除其中的每個檔案與子資料夾。與個別檔案刪除受相同的共享 CID 安全防護 — 如果其他使用者仍固定著您上傳的 CID，您的取消固定不會為他們移除該內容。

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

為資料夾／儲存桶設定 S3 CORS

透過 S3 相容 API 公開的資料夾會作為儲存桶（bucket）。如果您從瀏覽器 JavaScript 驅動該 API，則需要在儲存桶上設定 CORS 規則，以便瀏覽器的預檢請求能夠通過。兩個等效的介面會持久化到相同的儲存位置：

• PUT /folders/{folderId}/cors — 此 REST 端點，使用 JWT 驗證（供儀表板使用）
• S3 子資源 PUT /{bucket}?cors — 使用 SigV4 驗證（供 AWS SDK 使用，請參閱 s3-compatibility.md）

若資料夾的名稱尚未被宣告，此端點上的 PUT 也會將該資料夾的名稱宣告為全域唯一的儲存桶。

PUT /folders/{folderId}/cors

為資料夾的 S3 儲存桶設定 CORS 規則。每個儲存桶最多 5 條規則，總計 64 KB。

參數	類型	必填	描述
rules	CorsRule[]	是	AWS 樣式的 CORS 規則陣列（見下文）。不可為空。
bucketName	string	否	明確指定的 S3 儲存桶名稱。預設為資料夾的顯示名稱。如果所需名稱在全域範圍內已被宣告，請在此傳入替代名稱。

每個 CorsRule：

欄位	類型	必填	描述
AllowedOrigins	string[]	是	允許傳送請求的來源。支援萬用字元（https://*.myapp.com）。使用 * 表示任何來源。
AllowedMethods	string[]	是	GET、HEAD、PUT、POST、DELETE 中的一個或多個。
AllowedHeaders	string[]	否	瀏覽器可在請求中包含的標頭。預設：無。使用 ["*"] 以允許全部（建議用於會傳送 Authorization、x-amz-* 等的 AWS SDK v3）。
ExposeHeaders	string[]	否	可供瀏覽器 JavaScript 讀取的回應標頭。如果您的應用程式需要傳回的 CID，請包含 ETag 與 x-amz-meta-cid。
MaxAgeSeconds	number	否	瀏覽器快取預檢請求的時長。0-86400。預設 3600。
ID	string	否	規則的自由文字標籤。

範例請求

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
    }]
  }'

回應 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

傳回目前的 CORS 規則以及儲存桶名稱（若已宣告）。

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

DELETE /folders/{folderId}/cors

移除所有 CORS 規則。針對該儲存桶的瀏覽器預檢請求將會失敗關閉，直到設定新規則為止。

儀表板替代方案

在檔案頁面上，每個資料夾的操作選單都有一個 S3 CORS 項目，可開啟表單式編輯器。與此 REST 端點以及透過 S3 API 的 PutBucketCors 使用相同的底層儲存。