Папки

Папки організовують ваші завантажені файли в dashboard. За замовчуванням вони існують лише як метадані — файли зберігають власні CID і не переміщуються в IPFS — але ви також можете зробити знімок папки (snapshot), щоб матеріалізувати її як справжню директорію UnixFS та отримати один CID для всього вмісту.

Коли варто робити знімок папки

Знімок папки — це один directory CID в IPFS, що містить кожен файл папки, адресований за іменем. З ним ви можете:

• Поділитися всією папкою через одне посилання: https://ipfs.ninja/ipfs/{dirCid}/
• Розв'язати https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (або будь-який інший gateway) напряму
• Помістити CID у ENS contenthash для хостингу статичного сайту
• Використати його як базовий CID колекції NFT, щоб кожен токен посилався на ipfs://{dirCid}/<id>.json
• Закріпити директорію будь-де ще — кожен gateway IPFS у світі знає, як розв'язати directory CID UnixFS

Знімки є адресованими за вмістом: ідентичний вміст папки завжди дає той самий 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
}

Щойно створені папки не мають знімка. Поле latestSnapshot з'являється на папці після виклику POST /folders/{id}/snapshot (див. нижче) і в наступних відповідях 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-…" }'

Зробити знімок папки (отримати directory CID UnixFS)

POST /folders/{folderId}/snapshot

Матеріалізує папку як справжню директорію UnixFS у кластері IPFS та закріплює результат. Повертає один 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 без потреби робити ще один знімок.

Розв'язання знімка

Щойно знімок закріплений, directory CID розв'язується через будь-який gateway IPFS. Найпростіший шаблон URL:

https://ipfs.ninja/ipfs/{dirCid}/         → лістинг директорії
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → цей конкретний файл

Кластер закріплює рекурсивно, тому дочірні елементи теж розв'язуються — навіть якщо ви пізніше видалите оригінальний файл зі свого облікового запису, копія знімка виживає, оскільки це окремий пінінг, що рекурсивно проходить через директорію.

Повторний знімок

Повторний знімок незміненої папки повертає той самий CID — directory CID адресуються за вмістом, тому ідентичний вміст завжди дає той самий хеш, і виклик пінінгу кластера розпізнає дублікат і не виконує жодних дій на своєму боці.

Примітка: сам шлях знімка не є безкоштовним, навіть коли результат — той самий CID. Кожен виклик зчитує байти кожного файлу назад з IPFS і повторно завантажує їх як multipart на ендпоінт /add кластера — саме там відбувається обгортання директорією. Для типових папок (≤100 малих файлів) це все ще завершується за кілька секунд; для дуже великих папок надавайте перевагу виклику знімка лише тоді, коли вміст дійсно змінився.

Виклик знімка після додавання або видалення файлів створює інший CID; попередній продовжує розв'язуватися, доки ви не видалите його базові файли.

Ліміти

• Папка повинна містити хоча б один файл. Порожні папки повертають 400 — folder is empty.
• Символи імені файлу URL-кодуються в multipart-завантаженні, яке приймає Kubo; URL gateway можуть потребувати відсоткового кодування для пробілів або не-ASCII символів у назвах ваших файлів.
• Знімки враховуються у загальну кількість пінінгів вашого плану рівно один раз на унікальний CID — блоки файлів дедуплікуються, тому знімок здебільшого додає лише невеликий вузол директорії поверх файлів, які ви вже закріпили.

Оновити папку

PUT /folders/{folderId}

Параметр	Тип	Обов'язковий	Опис
name	string	Ні	Нова відображувана назва.
parentFolderId	string | null	Ні	Змінити батьківську папку. null переміщує її в корінь.

Видалити папку

DELETE /folders/{folderId}

Видаляє папку та рекурсивно каскадує через кожен файл і підпапку, які вона містить. Підлягає тому самому захисту спільного CID, що й видалення окремих файлів — якщо інші користувачі все ще закріплюють CID, який ви завантажили, ваше відкріплення не видаляє його для них.

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

Налаштування S3 CORS для папки / bucket'а

Папки, доступні через S3-сумісний API, виступають як bucket'и. Якщо ви керуєте цим API з браузерного JavaScript, вам потрібні правила CORS на bucket'і, щоб браузерні preflight-запити проходили успішно. Дві еквівалентні поверхні зберігають дані в одному й тому самому сховищі:

• PUT /folders/{folderId}/cors — цей REST-ендпоінт, автентифікований через JWT (використовується dashboard)
• Субресурс S3 PUT /{bucket}?cors — автентифікований через SigV4 (використовується AWS SDK, див. s3-compatibility.md)

PUT на цьому ендпоінті також закріплює назву папки як глобально унікальний bucket, якщо вона ще не була закріплена.

PUT /folders/{folderId}/cors

Встановлює правила CORS для S3-bucket'а папки. До 5 правил на bucket, загалом 64 КБ.

Параметр	Тип	Обов'язковий	Опис
rules	CorsRule[]	Так	Масив правил CORS у форматі AWS (див. нижче). Не порожній.
bucketName	string	Ні	Явна назва S3-bucket'а. За замовчуванням — відображувана назва папки. Якщо бажана назва вже зайнята глобально, передайте тут альтернативу.

Кожне CorsRule:

Поле	Тип	Обов'язковий	Опис
AllowedOrigins	string[]	Так	Джерела, яким дозволено надсилати запити. Підтримує wildcard-и (https://*.myapp.com). Використовуйте * для будь-якого джерела.
AllowedMethods	string[]	Так	Один або кілька з GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Ні	Заголовки, які браузери можуть включати в запити. За замовчуванням: жодного. Використовуйте ["*"], щоб дозволити всі (рекомендовано для AWS SDK v3, який надсилає Authorization, x-amz-* тощо).
ExposeHeaders	string[]	Ні	Заголовки відповіді, доступні для читання браузерному JavaScript. Додайте ETag та x-amz-meta-cid, якщо вашому додатку потрібен повернутий CID.
MaxAgeSeconds	number	Ні	Як довго браузери кешують preflight-запит. 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 плюс назву bucket'а (якщо закріплена).

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

DELETE /folders/{folderId}/cors

Видаляє всі правила CORS. Браузерні preflight-запити до bucket'а будуть провалюватися, доки не будуть встановлені нові правила.

Альтернатива через dashboard

На сторінці Files у меню дій кожної папки є пункт S3 CORS, що відкриває редактор на основі форми. Те саме сховище під капотом, що й у цього REST-ендпоінту та у PutBucketCors через S3 API.