Mga Folder

Inaayos ng mga folder ang iyong mga na-upload na file sa dashboard. Metadata-only sila bilang default — pinapanatili ng mga file ang sarili nilang mga CID at hindi inililipat sa IPFS — ngunit maaari mo ring i-snapshot ang isang folder para gawin itong isang tunay na UnixFS directory at makakuha ng iisang CID para sa buong bagay.

Kailan mo dapat i-snapshot ang isang folder

Ang folder snapshot ay isang solong IPFS directory CID na naglalaman ng bawat file sa folder, na maa-address ayon sa pangalan. Dito, maaari mong:

• Ibahagi ang buong folder sa pamamagitan ng isang URL: https://ipfs.ninja/ipfs/{dirCid}/
• I-resolve ang https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (o anumang ibang gateway) nang direkta
• Ilagay ang CID sa isang ENS contenthash para mag-host ng static site
• Gamitin ito bilang base CID ng isang NFT collection para tumukoy ang bawat token sa ipfs://{dirCid}/<id>.json
• I-pin ang directory kahit saan pa — alam ng bawat IPFS gateway sa mundo kung paano i-resolve ang isang UnixFS dir CID

Ang mga snapshot ay content-addressed: palaging gumagawa ng parehong CID ang magkaparehong laman ng folder. Ang muling pag-snapshot sa isang folder na hindi mo binago ay nagbabalik ng parehong CID na naibalik na noon. Ang pagdagdag/pagtanggal/pagpapalit ng pangalan ng isang file ay gumagawa ng bagong CID; nananatiling naka-pin at resolvable ang naunang CID hangga't hindi mo binubura ang mga file nito.

Gumawa ng folder

POST /folders

Parameter	Uri	Kinakailangan	Paglalarawan
name	string	Oo	Display name.
parentFolderId	string | null	Hindi	Parent folder ID para sa mga nested na folder. Iwan itong blangko para sa isang root-level na folder.

Halimbawa

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

Nagbabalik ng:

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

Ang mga bagong ginawang folder ay walang snapshot. Lumalabas ang field na latestSnapshot sa folder kapag tinawag mo na ang POST /folders/{id}/snapshot (tingnan sa ibaba) at sa mga susunod na response ng GET /folders.

Ilista ang mga folder

GET /folders

Nagbabalik ng bawat folder sa iyong account, root-level man o nested, kasama ang huling snapshot CID para sa bawat isa (kung mayroon).

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

Sinasalamin ng fileCount ang kasalukuyang laman ng folder; sinasalamin ng latestSnapshot.fileCount ang laman noong panahon ng huling snapshot. Kung magkaiba ang mga ito, nag-resolve pa rin ang snapshot CID ngunit luma na — mag-snapshot ulit para i-refresh.

Ilipat ang isang file sa isang folder

PUT /files/{cid}/move

Parameter	Uri	Kinakailangan	Paglalarawan
folderId	string | null	Oo	Target folder ID, o null para ilipat ang file sa 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-…" }'

I-snapshot ang isang folder (kumuha ng UnixFS dir CID)

POST /folders/{folderId}/snapshot

Gawing tunay na UnixFS directory ang folder sa IPFS cluster at i-pin ang resulta. Nagbabalik ng iisang CID para sa buong folder. Nagmumula ang mga pangalan ng mga child sa fileName ng bawat file; awtomatikong nire-resolve ang mga duplicate.

Hindi kailangan ng request body; ang path parameter ang tumutukoy sa folder.

Halimbawa

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

Nagbabalik ng:

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

Nakaimbak din ang CID sa row ng folder, kaya ang mga susunod na tawag ng GET /folders ay ibabalik ito bilang latestSnapshot.cid nang hindi na kailangan ng isa pang snapshot.

Pag-resolve ng snapshot

Kapag naka-pin na ang isang snapshot, nire-resolve ang directory CID sa pamamagitan ng anumang IPFS gateway. Ang pinakasimpleng URL pattern:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → ang isang file na iyon

Pina-pin ng cluster nang recursive, kaya resolvable din ang mga child — kahit na burahin mo mamaya ang orihinal na file mula sa iyong account, mananatili ang kopya ng snapshot dahil ito ay hiwalay na pin na umiikot sa buong directory.

Muling pag-snapshot

Ang muling pag-snapshot sa isang hindi binagong folder ay nagbabalik ng parehong CID — ang mga directory CID ay content-addressed, kaya palaging gumagawa ng parehong hash ang magkaparehong laman, at kinikilala ng pin call ng cluster ang duplicate at isang no-op na lang ito sa kanilang dulo.

Tandaan: hindi libre ang snapshot path mismo kahit na pareho ang naging resulta na CID. Bawat tawag ay bumabasa muli ng bytes ng bawat file mula sa IPFS at nire-upload muli ang mga ito bilang multipart sa /add endpoint ng cluster — doon nangyayari ang wrap-with-directory na wrapping. Para sa karaniwang mga folder (≤100 maliliit na file) natatapos pa rin ito sa loob ng ilang segundo; para sa napakalaking mga folder, mas mainam na tumawag ng snapshot lang kapag talagang nagbago ang laman.

Ang pagtawag ng snapshot pagkatapos mong magdagdag o magtanggal ng mga file ay gumagawa ng ibang CID; ang naunang isa ay patuloy na nire-resolve hangga't hindi mo binubura ang mga underlying na file nito.

Mga Limitasyon

• Ang folder ay dapat magkaroon ng kahit isang file. Ang mga blangkong folder ay nagbabalik ng 400 — folder is empty.
• Ang mga character sa pangalan ng file ay URL-encoded sa multipart upload na tinatanggap ng Kubo; maaaring kailanganin ng percent-encoding ang mga gateway URL para sa mga espasyo o non-ASCII na character sa iyong mga filename.
• Ang mga snapshot ay binibilang sa kabuuang pin ng iyong plan nang isang beses lang bawat natatanging CID — ang mga file block ay deduplicated, kaya karamihan sa idinaragdag ng snapshot ay isang maliit na directory node sa ibabaw ng mga file na na-pin mo na.

I-update ang isang folder

PUT /folders/{folderId}

Parameter	Uri	Kinakailangan	Paglalarawan
name	string	Hindi	Bagong display name.
parentFolderId	string | null	Hindi	Baguhin ang parent ng folder. Ililipat ito ng null sa root.

Burahin ang isang folder

DELETE /folders/{folderId}

Binubura ang folder at recursive na kina-cascade sa bawat file at subfolder na taglay nito. Sakop ng parehong shared-CID safety guard tulad ng mga indibidwal na pagbura ng file — kung may ibang user pa ring nag-pin ng CID na in-upload mo, hindi ito aalisin ng iyong unpin para sa kanila.

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

I-configure ang S3 CORS para sa isang folder / bucket

Ang mga folder na exposed sa pamamagitan ng S3-compatible API ay kumikilos bilang mga bucket. Kung dini-drive mo ang API na iyon mula sa browser JavaScript, kailangan mo ng mga CORS rules sa bucket para makapasa ang mga browser preflight. May dalawang katumbas na surface na nagse-save sa parehong store:

• PUT /folders/{folderId}/cors — ang REST endpoint na ito, JWT-authed (ginagamit ng dashboard)
• S3 subresource PUT /{bucket}?cors — SigV4-authed (ginagamit ng mga AWS SDK, tingnan ang s3-compatibility.md)

Ang PUT sa endpoint na ito ay inaangkin din ang pangalan ng folder bilang globally-unique na bucket kung hindi pa ito naaangkin.

PUT /folders/{folderId}/cors

Itakda ang CORS rules para sa S3 bucket ng folder. Hanggang 5 rules bawat bucket, 64 KB kabuuan.

Parameter	Uri	Kinakailangan	Paglalarawan
rules	CorsRule[]	Oo	Array ng AWS-shaped na mga CORS rule (tingnan sa ibaba). Hindi maaaring blangko.
bucketName	string	Hindi	Tahasang pangalan ng S3 bucket. Default sa display name ng folder. Kung naangkin na globally ang gustong pangalan, magpasa ng alternatibo dito.

Bawat CorsRule:

Field	Uri	Kinakailangan	Paglalarawan
AllowedOrigins	string[]	Oo	Mga origin na pinapayagang magpadala ng mga request. Sinusuportahan ang mga wildcard (https://*.myapp.com). Gamitin ang * para sa anumang origin.
AllowedMethods	string[]	Oo	Isa o higit pa sa GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Hindi	Mga header na maaaring isama ng mga browser sa mga request. Default: wala. Gamitin ang ["*"] para payagan ang lahat (inirerekomenda para sa AWS SDK v3 na nagpapadala ng Authorization, x-amz-*, atbp.).
ExposeHeaders	string[]	Hindi	Mga response header na magiging readable sa browser JavaScript. Isama ang ETag at x-amz-meta-cid kung kailangan ng iyong app ang naibalik na CID.
MaxAgeSeconds	number	Hindi	Gaano katagal i-cache ng mga browser ang preflight. 0-86400. Default 3600.
ID	string	Hindi	Free-text na label para sa rule.

Halimbawang request

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

Response 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

Nagbabalik ng kasalukuyang mga CORS rule at ang pangalan ng bucket (kung naangkin).

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

DELETE /folders/{folderId}/cors

Inaalis ang lahat ng CORS rules. Mabibigo ang mga browser preflight laban sa bucket hanggang sa may bagong itakdang rules.

Alternatibong Dashboard

Sa Files page, ang action menu ng bawat folder ay may S3 CORS na entry na nagbubukas ng form-based na editor. Parehong underlying store tulad ng REST endpoint na ito at ng PutBucketCors sa pamamagitan ng S3 API.