Priečinky

Priečinky organizujú vaše nahrané súbory v ovládacom paneli. Predvolene obsahujú iba metadáta — súbory si zachovávajú vlastné CID a nie sú presúvané na IPFS — ale môžete tiež vytvoriť snímku priečinka, aby ste ho zhmotnili ako skutočný UnixFS adresár a získali jedno CID pre celok.

Kedy vytvoriť snímku priečinka

Snímka priečinka je jediné CID IPFS adresára, ktoré obsahuje každý súbor v priečinku, adresovateľný podľa názvu. S ním môžete:

• Zdieľať celý priečinok cez jednu URL: https://ipfs.ninja/ipfs/{dirCid}/
• Priamo rozpoznať https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (alebo akúkoľvek inú gateway)
• Vložiť CID do ENS contenthash pre hosting statického webu
• Použiť ho ako základné CID NFT kolekcie, aby každý token odkazoval na ipfs://{dirCid}/<id>.json
• Pripnúť adresár kdekoľvek inde — každá IPFS gateway na svete vie rozpoznať CID UnixFS adresára

Snímky sú adresované podľa obsahu: identický obsah priečinka vždy produkuje rovnaké CID. Opätovné vytvorenie snímky nezmeneného priečinka vráti rovnaké CID ako predtým. Pridanie/odstránenie/premenovanie súboru produkuje nové CID; predchádzajúce CID zostáva pripnuté a rozpoznateľné, pokiaľ nevymažete jeho súbory.

Vytvorenie priečinka

POST /folders

Parameter	Typ	Povinný	Popis
name	string	Áno	Zobrazovaný názov.
parentFolderId	string | null	Nie	ID nadradeného priečinka pre vnorené priečinky. Vynechajte pre priečinok na koreňovej úrovni.

Príklad

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

Vráti:

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

Novo vytvorené priečinky nemajú žiadnu snímku. Pole latestSnapshot sa objaví na priečinku po zavolaní POST /folders/{id}/snapshot (pozri nižšie) a v následných odpovediach GET /folders.

Zoznam priečinkov

GET /folders

Vráti každý priečinok vo vašom účte, na koreňovej úrovni aj vnorený, s CID poslednej snímky pre každý z nich (ak existuje).

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

fileCount odráža aktuálny obsah priečinka; latestSnapshot.fileCount odráža obsah v čase poslednej snímky. Ak sa líšia, CID snímky sa stále rozpoznáva, ale je zastarané — vytvorte novú snímku na obnovenie.

Presunutie súboru do priečinka

PUT /files/{cid}/move

Parameter	Typ	Povinný	Popis
folderId	string | null	Áno	ID cieľového priečinka, alebo null na presunutie súboru do koreňa.

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

Vytvorenie snímky priečinka (získanie CID UnixFS adresára)

POST /folders/{folderId}/snapshot

Zhmotnite priečinok ako skutočný UnixFS adresár na IPFS clusteri a pripnite výsledok. Vráti jedno CID pre celý priečinok. Názvy vnorených položiek pochádzajú z fileName každého súboru; duplicity sa automaticky rozlišujú.

Telo požiadavky nie je potrebné; priečinok identifikuje parameter cesty.

Príklad

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

Vráti:

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

CID sa tiež uloží k záznamu priečinka, takže následné volania GET /folders ho vrátia ako latestSnapshot.cid bez potreby ďalšej snímky.

Rozpoznávanie snímky

Po pripnutí snímky sa CID adresára rozpoznáva cez ľubovoľnú IPFS gateway. Najjednoduchší vzor URL:

https://ipfs.ninja/ipfs/{dirCid}/         → zoznam obsahu adresára
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → daný jeden súbor

Cluster pripína rekurzívne, takže aj vnorené položky sú rozpoznateľné — aj keď neskôr vymažete pôvodný súbor zo svojho účtu, kópia v snímke prežije, pretože ide o samostatné pripnutie, ktoré rekurzívne prechádza adresárom.

Opätovné vytvorenie snímky

Opätovné vytvorenie snímky nezmeneného priečinka vráti rovnaké CID — CID adresárov sú adresované podľa obsahu, takže identický obsah vždy produkuje rovnaký hash a volanie pripnutia na strane clustera rozpozná duplicitu a na jeho konci je bezúčinné.

Poznámka: samotná cesta snímky nie je zadarmo, ani keď je výsledkom rovnaké CID. Každé volanie prečíta bajty každého súboru späť z IPFS a znova ich nahrá ako multipart na endpoint /add clustera — práve tam prebieha zabalenie do adresára. Pre typické priečinky (≤100 malých súborov) sa to stále dokončí za pár sekúnd; pre veľmi veľké priečinky uprednostnite volanie snímky iba vtedy, keď sa obsah skutočne zmenil.

Vytvorenie snímky po pridaní alebo odstránení súborov produkuje odlišné CID; predchádzajúce naďalej zostáva rozpoznateľné, pokiaľ nevymažete jeho podkladové súbory.

Limity

• Priečinok musí obsahovať aspoň jeden súbor. Prázdne priečinky vracajú 400 — folder is empty.
• Znaky v názvoch súborov sú URL-kódované v multipart nahrávaní, ktoré prijíma Kubo; URL gateway môžu potrebovať percentuálne kódovanie pre medzery alebo neASCII znaky vo vašich názvoch súborov.
• Snímky sa počítajú do celkového limitu pripnutí vášho plánu presne raz na jedinečné CID — bloky súborov sú deduplikované, takže snímka väčšinou pridáva iba malý uzol adresára navrch súborov, ktoré už pripínate.

Aktualizácia priečinka

PUT /folders/{folderId}

Parameter	Typ	Povinný	Popis
name	string	Nie	Nový zobrazovaný názov.
parentFolderId	string | null	Nie	Zmena nadradeného priečinka. null presunie priečinok do koreňa.

Vymazanie priečinka

DELETE /folders/{folderId}

Vymaže priečinok a rekurzívne prejde všetkými súbormi a podpriečinkami, ktoré obsahuje. Podlieha rovnakej ochrane zdieľaného CID ako mazanie jednotlivých súborov — ak iní používatelia stále pripínajú CID, ktoré ste nahrali, vaše odpnutie im ho neodstráni.

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

Konfigurácia S3 CORS pre priečinok / bucket

Priečinky sprístupnené cez S3-kompatibilné API fungujú ako buckety. Ak toto API ovládate z prehliadačového JavaScriptu, potrebujete na bucket-e CORS pravidlá, aby prehliadačové preflight požiadavky prešli. Dve rovnocenné rozhrania zapisujú do rovnakého úložiska:

• PUT /folders/{folderId}/cors — tento REST endpoint, autentifikovaný JWT (používaný ovládacím panelom)
• S3 subresource PUT /{bucket}?cors — autentifikovaný SigV4 (používaný AWS SDK, pozri s3-compatibility.md)

PUT na tomto endpointe tiež zaberie názov priečinka ako globálne jedinečný názov bucketu, ak ešte nebol zabraný.

PUT /folders/{folderId}/cors

Nastavte CORS pravidlá pre S3 bucket priečinka. Až 5 pravidiel na bucket, 64 KB celkovo.

Parameter	Typ	Povinný	Popis
rules	CorsRule[]	Áno	Pole CORS pravidiel v tvare AWS (pozri nižšie). Nesmie byť prázdne.
bucketName	string	Nie	Explicitný názov S3 bucketu. Predvolene zobrazovaný názov priečinka. Ak je požadovaný názov už globálne zabraný, zadajte tu alternatívu.

Každé CorsRule:

Field	Typ	Povinný	Popis
AllowedOrigins	string[]	Áno	Pôvody, ktoré môžu odosielať požiadavky. Podporuje zástupné znaky (https://*.myapp.com). Použite * pre ľubovoľný pôvod.
AllowedMethods	string[]	Áno	Jedna alebo viac z GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nie	Hlavičky, ktoré prehliadače môžu zahrnúť v požiadavkách. Predvolené: žiadne. Použite ["*"] na povolenie všetkých (odporúčané pre AWS SDK v3, ktoré odosiela Authorization, x-amz-* atď.).
ExposeHeaders	string[]	Nie	Hlavičky odpovede sprístupnené prehliadačovému JavaScriptu na čítanie. Zahrňte ETag a x-amz-meta-cid, ak vaša aplikácia potrebuje vrátené CID.
MaxAgeSeconds	number	Nie	Ako dlho prehliadače ukladajú preflight do medzipamäte. 0-86400. Predvolene 3600.
ID	string	Nie	Voľný textový popisok pravidla.

Príklad požiadavky

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

Vráti aktuálne CORS pravidlá plus názov bucketu (ak je zabraný).

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

DELETE /folders/{folderId}/cors

Odstráni všetky CORS pravidlá. Prehliadačové preflight požiadavky voči bucketu budú zlyhávať (fail closed), kým sa nenastavia nové pravidlá.

Dashboard alternative

Na stránke Súbory má ponuka akcií každého priečinka položku S3 CORS, ktorá otvorí formulárový editor. Rovnaké podkladové úložisko ako tento REST endpoint aj ako PutBucketCors cez API S3.