Složky

Složky organizují vaše nahrané soubory v řídicím panelu. Ve výchozím stavu jde jen o metadata — soubory si zachovávají vlastní CID a na IPFS se nepřesouvají — ale můžete také vytvořit snapshot složky a materializovat ji jako skutečný UnixFS adresář a získat jedno CID pro celý obsah.

Kdy vytvořit snapshot složky

Snapshot složky je jedno adresářové CID na IPFS, které obsahuje každý soubor ve složce, adresovatelný podle názvu. S ním můžete:

• Sdílet celou složku jednou URL: https://ipfs.ninja/ipfs/{dirCid}/
• Rozřešit https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (nebo jakoukoli jinou gateway) přímo
• Vložit CID do ENS contenthash a hostovat statický web
• Použít ho jako základní CID NFT kolekce, takže každý token odkazuje na ipfs://{dirCid}/<id>.json
• Připnout adresář kdekoli jinde — každá IPFS gateway na světě umí rozřešit UnixFS adresářové CID

Snapshoty jsou adresovány obsahem: identický obsah složky vždy produkuje stejné CID. Opětovné vytvoření snapshotu nezměněné složky vrátí stejné CID jako předtím. Přidání/odebrání/přejmenování souboru produkuje nové CID; předchozí CID zůstává připnuté a rozřešitelné, dokud nesmažete jeho soubory.

Vytvoření složky

POST /folders

Parametr	Typ	Povinný	Popis
name	string	Ano	Zobrazovaný název.
parentFolderId	string | null	Ne	ID nadřazené složky pro vnořené složky. Vynechte pro složku na kořenové úrovni.

Pří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" }'

Vrací:

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

Nově vytvořené složky nemají žádný snapshot. Pole latestSnapshot se u složky objeví, jakmile zavoláte POST /folders/{id}/snapshot (viz níže), a poté i v následujících odpovědích GET /folders.

Seznam složek

GET /folders

Vrátí každou složku ve vašem účtu, na kořenové úrovni i vnořenou, s CID posledního snapshotu pro každou (pokud existuje).

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

fileCount odráží aktuální obsah složky; latestSnapshot.fileCount odráží obsah v okamžiku posledního snapshotu. Pokud se liší, CID snapshotu se stále rozřeší, ale je zastaralé — pro obnovu vytvořte nový snapshot.

Přesunutí souboru do složky

PUT /files/{cid}/move

Parametr	Typ	Povinný	Popis
folderId	string | null	Ano	ID cílové složky, nebo null pro přesun souboru do kořene.

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

Vytvoření snapshotu složky (získání UnixFS adresářového CID)

POST /folders/{folderId}/snapshot

Materializuje složku jako skutečný UnixFS adresář v IPFS clusteru a připne výsledek. Vrátí jedno CID pro celou složku. Názvy podřízených položek pocházejí z fileName každého souboru; duplicity se automaticky odliší.

Tělo požadavku není potřeba; parametr cesty identifikuje složku.

Příklad

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

Vrací:

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

CID je také uloženo přímo u záznamu složky, takže následná volání GET /folders ho vrací jako latestSnapshot.cid bez nutnosti dalšího snapshotu.

Rozřešení snapshotu

Jakmile je snapshot připnutý, adresářové CID se rozřeší přes libovolnou IPFS gateway. Nejjednodušší vzor URL:

https://ipfs.ninja/ipfs/{dirCid}/         → výpis obsahu adresáře
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → daný jeden soubor

Cluster připíná rekurzivně, takže podřízené položky jsou také rozřešitelné — i když později smažete původní soubor ze svého účtu, kopie ve snapshotu přežije, protože jde o samostatné připnutí procházející rekurzivně adresářem.

Opětovné vytvoření snapshotu

Opětovné vytvoření snapshotu nezměněné složky vrátí stejné CID — adresářová CID jsou adresována obsahem, takže identický obsah vždy produkuje stejný hash, a volání připnutí v clusteru rozpozná duplicitu a na jeho straně jde o no-op.

Poznámka: samotná cesta snapshotu není zdarma, ani když je výsledkem stejné CID. Každé volání načte bajty každého souboru zpět z IPFS a znovu je nahraje jako multipart na endpoint /add clusteru — tam dochází k obalení adresářem. U typických složek (≤100 malých souborů) to stále proběhne během několika sekund; u velmi velkých složek volejte snapshot pouze tehdy, když se obsah skutečně změnil.

Zavolání snapshotu poté, co jste přidali nebo odebrali soubory, produkuje jiné CID; předchozí i nadále funguje, dokud nesmažete jeho podkladové soubory.

Limity

• Složka musí obsahovat alespoň jeden soubor. Prázdné složky vrací 400 — folder is empty.
• Znaky v názvech souborů jsou v multipart nahrávání, které přijímá Kubo, URL-kódovány; URL gateway mohou vyžadovat procentuální kódování pro mezery nebo ne-ASCII znaky ve vašich názvech souborů.
• Snapshoty se počítají do celkového limitu připnutí vašeho plánu právě jednou na unikátní CID — bloky souborů jsou deduplikovány, takže snapshot ve většině případů přidává jen malý adresářový uzel navrch souborů, které již připínáte.

Aktualizace složky

PUT /folders/{folderId}

Parametr	Typ	Povinný	Popis
name	string	Ne	Nový zobrazovaný název.
parentFolderId	string | null	Ne	Změna nadřazené složky. null přesune složku do kořene.

Smazání složky

DELETE /folders/{folderId}

Smaže složku a rekurzivně smaže i každý soubor a podsložku, kterou obsahuje. Podléhá stejné ochraně sdíleného CID jako mazání jednotlivých souborů — pokud CID, který jste nahráli, stále připínají jiní uživatelé, vaše odpojení jim ho neodebere.

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

Konfigurace S3 CORS pro složku / bucket

Složky vystavené přes S3-kompatibilní API fungují jako buckety. Pokud toto API ovládáte z JavaScriptu v prohlížeči, potřebujete na bucketu CORS pravidla, aby prošly preflight požadavky prohlížeče. Dva ekvivalentní přístupy ukládají do téhož úložiště:

• PUT /folders/{folderId}/cors — tento REST endpoint, autentizovaný přes JWT (používá ho řídicí panel)
• S3 subresource PUT /{bucket}?cors — autentizovaný přes SigV4 (používají ho AWS SDK, viz s3-compatibility.md)

PUT na tomto endpointu také zabere název složky jako globálně jedinečný název bucketu, pokud ještě není zabraný.

PUT /folders/{folderId}/cors

Nastaví CORS pravidla pro S3 bucket dané složky. Až 5 pravidel na bucket, celkem 64 KB.

Parametr	Typ	Povinný	Popis
rules	CorsRule[]	Ano	Pole CORS pravidel ve tvaru AWS (viz níže). Nesmí být prázdné.
bucketName	string	Ne	Explicitní název S3 bucketu. Výchozí hodnota je zobrazovaný název složky. Pokud je požadovaný název již globálně zabraný, uveďte zde alternativu.

Každé CorsRule:

Pole	Typ	Povinný	Popis
AllowedOrigins	string[]	Ano	Originy, ze kterých je povoleno odesílat požadavky. Podporuje zástupné znaky (https://*.myapp.com). Použijte * pro libovolný origin.
AllowedMethods	string[]	Ano	Jedna nebo více z GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ne	Hlavičky, které prohlížeče mohou zahrnout do požadavků. Výchozí: žádné. Použijte ["*"] pro povolení všech (doporučeno pro AWS SDK v3, které posílá Authorization, x-amz-* atd.).
ExposeHeaders	string[]	Ne	Hlavičky odpovědi, které jsou čitelné pro JavaScript v prohlížeči. Zahrňte ETag a x-amz-meta-cid, pokud vaše aplikace potřebuje vrácené CID.
MaxAgeSeconds	number	Ne	Jak dlouho prohlížeče cachují preflight. 0-86400. Výchozí 3600.
ID	string	Ne	Volný textový popisek pro pravidlo.

Příklad požadavku

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átí aktuální CORS pravidla a název bucketu (pokud je zabraný).

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

DELETE /folders/{folderId}/cors

Odebere všechna CORS pravidla. Preflight požadavky prohlížeče vůči bucketu budou selhávat, dokud nenastavíte nová pravidla.

Alternativa přes řídicí panel

Na stránce Soubory má nabídka akcí každé složky položku S3 CORS, která otevře editor s formulářem. Stejné podkladové úložiště jako tento REST endpoint a jako PutBucketCors přes S3 API.