Foldery

Foldery organizują Twoje przesłane pliki w dashboardzie. Domyślnie są tylko metadanymi — pliki zachowują własne CID-y i nie są przenoszone w IPFS — ale możesz też zrobić migawkę folderu, aby zmaterializować go jako prawdziwy katalog UnixFS i uzyskać jeden CID dla całości.

Kiedy zrobić migawkę folderu

Migawka folderu to pojedynczy CID katalogu IPFS zawierający każdy plik w folderze, adresowalny po nazwie. Dzięki niej możesz:

• Udostępnić cały folder pod jednym URL-em: https://ipfs.ninja/ipfs/{dirCid}/
• Rozwiązać https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (lub dowolną inną bramkę) bezpośrednio
• Umieścić CID w contenthash ENS, aby hostować statyczną stronę
• Użyć go jako bazowego CID kolekcji NFT, tak aby każdy token odwoływał się do ipfs://{dirCid}/<id>.json
• Przypiąć katalog gdziekolwiek indziej — każda bramka IPFS na świecie wie, jak rozwiązać CID katalogu UnixFS

Migawki są adresowane treścią: identyczna zawartość folderu zawsze tworzy ten sam CID. Ponowne zrobienie migawki niezmienionego folderu zwraca ten sam CID co poprzednio. Dodanie/usunięcie/zmiana nazwy pliku tworzy nowy CID; poprzedni CID pozostaje przypięty i rozwiązywalny, dopóki nie usuniesz jego plików.

Utwórz folder

POST /folders

Parametr	Typ	Wymagany	Opis
name	string	Tak	Nazwa wyświetlana.
parentFolderId	string | null	Nie	ID folderu nadrzędnego dla zagnieżdżonych folderów. Pomiń dla folderu na poziomie głównym.

Przykład

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

Zwraca:

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

Nowo utworzone foldery nie mają migawki. Pole latestSnapshot pojawia się na folderze po wywołaniu POST /folders/{id}/snapshot (patrz poniżej) oraz w kolejnych odpowiedziach GET /folders.

Lista folderów

GET /folders

Zwraca każdy folder na Twoim koncie, zarówno na poziomie głównym, jak i zagnieżdżony, wraz z CID-em ostatniej migawki dla każdego (jeśli istnieje).

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

fileCount odzwierciedla bieżącą zawartość folderu; latestSnapshot.fileCount odzwierciedla zawartość w momencie ostatniej migawki. Jeśli się różnią, CID migawki nadal się rozwiązuje, ale jest nieaktualny — zrób migawkę ponownie, aby odświeżyć.

Przenieś plik do folderu

PUT /files/{cid}/move

Parametr	Typ	Wymagany	Opis
folderId	string | null	Tak	ID folderu docelowego lub null, aby przenieść plik do głównego poziomu.

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

Zrób migawkę folderu (uzyskaj CID katalogu UnixFS)

POST /folders/{folderId}/snapshot

Zmaterializuj folder jako prawdziwy katalog UnixFS na klastrze IPFS i przypnij wynik. Zwraca jeden CID dla całego folderu. Nazwy plików podrzędnych pochodzą z fileName każdego pliku; duplikaty są automatycznie rozróżniane.

Nie jest potrzebna treść żądania; parametr ścieżki identyfikuje folder.

Przykład

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

Zwraca:

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

CID jest również zapisywany w wierszu folderu, więc kolejne wywołania GET /folders zwracają go jako latestSnapshot.cid bez potrzeby kolejnej migawki.

Rozwiązywanie migawki

Po przypięciu migawki CID katalogu rozwiązuje się przez dowolną bramkę IPFS. Najprostszy wzorzec URL:

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

Klaster przypina rekurencyjnie, więc pliki podrzędne są również rozwiązywalne — nawet jeśli później usuniesz oryginalny plik ze swojego konta, kopia z migawki przetrwa, ponieważ jest oddzielnym przypięciem rekurencyjnie obejmującym katalog.

Ponowne robienie migawki

Ponowne zrobienie migawki niezmienionego folderu zwraca ten sam CID — CID-y katalogów są adresowane treścią, więc identyczna zawartość zawsze tworzy ten sam hash, a wywołanie przypinania klastra rozpoznaje duplikat i jest no-opem po jego stronie.

Uwaga: sama ścieżka migawki nie jest darmowa nawet gdy wynik to ten sam CID. Każde wywołanie odczytuje bajty każdego pliku z powrotem z IPFS i przesyła je ponownie jako multipart do endpointu /add klastra — tam właśnie zachodzi opakowywanie w katalog. Dla typowych folderów (≤100 małych plików) nadal kończy się to w ciągu kilku sekund; dla bardzo dużych folderów wywołuj migawkę tylko wtedy, gdy zawartość faktycznie się zmieniła.

Wywołanie migawki po dodaniu lub usunięciu plików tworzy inny CID; poprzedni nadal się rozwiązuje, dopóki nie usuniesz jego plików źródłowych.

Limity

• Folder musi zawierać co najmniej jeden plik. Puste foldery zwracają 400 — folder is empty.
• Znaki nazw plików są kodowane URL w multipart uploadzie akceptowanym przez Kubo; adresy URL bramki mogą wymagać kodowania procentowego dla spacji lub znaków spoza ASCII w nazwach plików.
• Migawki liczą się do łącznej liczby przypięć Twojego planu dokładnie raz na unikalny CID — bloki plików są deduplikowane, więc migawka głównie dodaje niewielki węzeł katalogu na wierzchu plików, które już przypinasz.

Zaktualizuj folder

PUT /folders/{folderId}

Parametr	Typ	Wymagany	Opis
name	string	Nie	Nowa nazwa wyświetlana.
parentFolderId	string | null	Nie	Zmień folder nadrzędny. null przenosi go do głównego poziomu.

Usuń folder

DELETE /folders/{folderId}

Usuwa folder i rekurencyjnie kaskaduje przez każdy zawarty w nim plik i podfolder. Podlega tej samej ochronie współdzielonych CID co usuwanie pojedynczych plików — jeśli inni użytkownicy nadal przypinają przesłany przez Ciebie CID, Twoje odpięcie nie usuwa go dla nich.

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

Konfiguracja CORS S3 dla folderu / bucketa

Foldery udostępniane przez API zgodne z S3 działają jako buckety. Jeśli obsługujesz to API z JavaScriptu w przeglądarce, potrzebujesz reguł CORS na buckecie, aby preflighty przeglądarki przechodziły. Dwie równoważne powierzchnie zapisują do tego samego magazynu:

• PUT /folders/{folderId}/cors — ten endpoint REST, uwierzytelniany JWT (używany przez dashboard)
• Podzasób S3 PUT /{bucket}?cors — uwierzytelniany SigV4 (używany przez AWS SDK, zobacz s3-compatibility.md)

PUT na tym endpoincie także zajmuje nazwę folderu jako globalnie unikalny bucket, jeśli nie została jeszcze zajęta.

PUT /folders/{folderId}/cors

Ustaw reguły CORS dla bucketa S3 folderu. Do 5 reguł na bucket, łącznie 64 KB.

Parametr	Typ	Wymagany	Opis
rules	CorsRule[]	Tak	Tablica reguł CORS w formacie AWS (patrz poniżej). Niepusta.
bucketName	string	Nie	Jawna nazwa bucketa S3. Domyślnie nazwa wyświetlana folderu. Jeśli żądana nazwa jest już zajęta globalnie, podaj tu alternatywę.

Każda CorsRule:

Pole	Typ	Wymagany	Opis
AllowedOrigins	string[]	Tak	Źródła, którym wolno wysyłać żądania. Obsługuje symbole wieloznaczne (https://*.myapp.com). Użyj * dla dowolnego źródła.
AllowedMethods	string[]	Tak	Jedna lub więcej z GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nie	Nagłówki, które przeglądarki mogą dołączać do żądań. Domyślnie: brak. Użyj ["*"], aby zezwolić na wszystkie (zalecane dla AWS SDK v3, który wysyła Authorization, x-amz-* itd.).
ExposeHeaders	string[]	Nie	Nagłówki odpowiedzi udostępnione do odczytu przez JavaScript w przeglądarce. Dołącz ETag i x-amz-meta-cid, jeśli Twoja aplikacja potrzebuje zwróconego CID.
MaxAgeSeconds	number	Nie	Jak długo przeglądarki buforują preflight. 0-86400. Domyślnie 3600.
ID	string	Nie	Dowolna etykieta tekstowa dla reguły.

Przykładowe żądanie

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

Odpowiedź 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

Zwraca bieżące reguły CORS wraz z nazwą bucketa (jeśli zajęta).

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

DELETE /folders/{folderId}/cors

Usuwa wszystkie reguły CORS. Preflighty przeglądarki dla bucketa będą kończyć się niepowodzeniem (fail closed), dopóki nie ustawisz nowych reguł.

Alternatywa: dashboard

Na stronie Pliki menu akcji każdego folderu ma pozycję S3 CORS, która otwiera edytor oparty na formularzu. Ten sam bazowy magazyn danych co ten endpoint REST i co PutBucketCors przez S3 API.