फोल्डर

फोल्डर डैशबोर्ड में आपकी अपलोड की गई फाइलों को व्यवस्थित करते हैं। डिफ़ॉल्ट रूप से ये केवल मेटाडेटा होते हैं — फाइलें अपने स्वयं के CID रखती हैं और IPFS पर स्थानांतरित नहीं की जातीं — लेकिन आप किसी फोल्डर का स्नैपशॉट भी ले सकते हैं ताकि उसे एक वास्तविक UnixFS डायरेक्टरी के रूप में सामने ला सकें और पूरे फोल्डर के लिए एक ही CID प्राप्त कर सकें।

आप किसी फोल्डर का स्नैपशॉट कब लेंगे

फोल्डर स्नैपशॉट एक एकल IPFS डायरेक्टरी CID होता है जिसमें फोल्डर की हर फाइल शामिल होती है, और वह नाम से एड्रेस की जा सकती है। इससे आप कर सकते हैं:

• पूरे फोल्डर को एक URL से साझा करें: https://ipfs.ninja/ipfs/{dirCid}/
• https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (या किसी अन्य गेटवे) को सीधे रिज़ॉल्व करें
• स्टैटिक साइट होस्ट करने के लिए CID को ENS contenthash में डालें
• इसे किसी NFT कलेक्शन के बेस CID के रूप में उपयोग करें ताकि प्रत्येक टोकन ipfs://{dirCid}/<id>.json को संदर्भित करे
• डायरेक्टरी को कहीं और भी पिन करें — दुनिया का हर IPFS गेटवे UnixFS dir CID को रिज़ॉल्व करना जानता है

स्नैपशॉट कंटेंट-एड्रेस्ड होते हैं: समान फोल्डर कंटेंट हमेशा एक ही 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-…" }'

फोल्डर का स्नैपशॉट लें (UnixFS dir CID प्राप्त करें)

POST /folders/{folderId}/snapshot

फोल्डर को IPFS क्लस्टर पर एक वास्तविक UnixFS डायरेक्टरी के रूप में सामने लाएं और परिणाम को पिन करें। पूरे फोल्डर के लिए एक 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 के रूप में लौटाते हैं।

स्नैपशॉट को रिज़ॉल्व करना

एक बार स्नैपशॉट पिन हो जाने के बाद, डायरेक्टरी CID किसी भी IPFS गेटवे के माध्यम से रिज़ॉल्व होता है। सबसे सरल URL पैटर्न:

https://ipfs.ninja/ipfs/{dirCid}/         → डायरेक्टरी लिस्टिंग
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → वह एक फाइल

क्लस्टर पुनरावर्ती रूप से पिन करता है, इसलिए चाइल्ड भी रिज़ॉल्व होने योग्य हैं — भले ही आप बाद में मूल फाइल को अपने खाते से हटा दें, स्नैपशॉट की प्रति बची रहती है क्योंकि यह डायरेक्टरी के माध्यम से पुनरावर्ती एक अलग पिन है।

दोबारा स्नैपशॉट लेना

किसी अनबदले फोल्डर का दोबारा स्नैपशॉट लेने पर वही CID मिलता है — डायरेक्टरी CID कंटेंट-एड्रेस्ड हैं, इसलिए समान सामग्री हमेशा एक ही हैश उत्पन्न करती है, और क्लस्टर का पिन कॉल डुप्लिकेट को पहचानता है और उसकी ओर से एक नो-ऑप है।

नोट: स्नैपशॉट पथ स्वयं तब भी मुफ्त नहीं है जब परिणाम वही CID हो। प्रत्येक कॉल हर फाइल के बाइट्स को IPFS से वापस पढ़ता है और उन्हें क्लस्टर के /add एंडपॉइंट पर मल्टीपार्ट के रूप में पुनः अपलोड करता है — वहीं wrap-with-directory रैपिंग होती है। सामान्य फोल्डरों (≤100 छोटी फाइलें) के लिए यह अभी भी कुछ सेकंड में पूरा हो जाता है; बहुत बड़े फोल्डरों के लिए स्नैपशॉट केवल तभी कॉल करना पसंद करें जब सामग्री वास्तव में बदल गई हो।

फाइलें जोड़ने या हटाने के बाद स्नैपशॉट कॉल करने पर एक अलग CID उत्पन्न होता है; पिछला CID तब तक रिज़ॉल्व होता रहता है जब तक आप उसकी अंतर्निहित फाइलें नहीं हटाते।

सीमाएं

• फोल्डर में कम से कम एक फाइल होनी चाहिए। खाली फोल्डर 400 — folder is empty लौटाते हैं।
• फाइल-नाम के अक्षर मल्टीपार्ट अपलोड में URL-एन्कोडेड होते हैं जिन्हें Kubo स्वीकार करता है; गेटवे URLs को आपके फाइल नामों में स्पेस या नॉन-ASCII अक्षरों के लिए परसेंट-एन्कोडिंग की आवश्यकता हो सकती है।
• स्नैपशॉट आपकी योजना के पिन कुल में प्रति अद्वितीय CID केवल एक बार गिने जाते हैं — फाइल ब्लॉक डिडुप्लिकेट होते हैं, इसलिए स्नैपशॉट आमतौर पर आपकी पहले से पिन की गई फाइलों के ऊपर एक छोटा डायरेक्टरी नोड जोड़ता है।

फोल्डर अपडेट करें

PUT /folders/{folderId}

पैरामीटर	प्रकार	आवश्यक	विवरण
name	string	नहीं	नया प्रदर्शन नाम।
parentFolderId	string | null	नहीं	फोल्डर का पैरेंट बदलें। null इसे रूट पर ले जाता है।

फोल्डर हटाएं

DELETE /folders/{folderId}

फोल्डर को हटाता है और उसमें मौजूद हर फाइल और सबफोल्डर के माध्यम से पुनरावर्ती रूप से कैस्केड करता है। अलग-अलग फाइल डिलीट के समान साझा-CID सुरक्षा गार्ड के अधीन — यदि अन्य उपयोगकर्ता अभी भी आपके द्वारा अपलोड किए गए CID को पिन करते हैं, तो आपका अनपिन उनके लिए इसे नहीं हटाता।

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

किसी फोल्डर / बकेट के लिए S3 CORS कॉन्फ़िगर करें

S3-संगत API के माध्यम से एक्सपोज़ किए गए फोल्डर बकेट के रूप में कार्य करते हैं। यदि आप उस API को ब्राउज़र JavaScript से चला रहे हैं, तो आपको बकेट पर CORS नियमों की आवश्यकता है ताकि ब्राउज़र प्रीफ्लाइट पास हो सकें। दो समकक्ष सतहें एक ही स्टोर में सहेजी जाती हैं:

• PUT /folders/{folderId}/cors — यह REST एंडपॉइंट, JWT-प्रमाणित (डैशबोर्ड द्वारा उपयोग किया जाता है)
• S3 सबरिसोर्स PUT /{bucket}?cors — SigV4-प्रमाणित (AWS SDK द्वारा उपयोग किया जाता है, s3-compatibility.md देखें)

इस एंडपॉइंट पर PUT फोल्डर के नाम को विश्व-स्तर पर अद्वितीय बकेट के रूप में दावा भी करता है यदि उस पर अभी तक दावा नहीं किया गया है।

PUT /folders/{folderId}/cors

फोल्डर के S3 बकेट के लिए CORS नियम सेट करें। प्रति बकेट अधिकतम 5 नियम, कुल 64 KB।

पैरामीटर	प्रकार	आवश्यक	विवरण
rules	CorsRule[]	हां	AWS-आकार के CORS नियमों की सारणी (नीचे देखें)। खाली नहीं।
bucketName	string	नहीं	स्पष्ट S3 बकेट नाम। डिफ़ॉल्ट रूप से फोल्डर के प्रदर्शन नाम पर होता है। यदि वांछित नाम पहले से विश्व-स्तर पर दावा किया जा चुका है, तो यहां एक विकल्प पास करें।

प्रत्येक CorsRule:

फ़ील्ड	प्रकार	आवश्यक	विवरण
AllowedOrigins	string[]	हां	अनुरोध भेजने की अनुमति वाले ऑरिजिन। वाइल्डकार्ड का समर्थन करता है (https://*.myapp.com)। किसी भी ऑरिजिन के लिए * का उपयोग करें।
AllowedMethods	string[]	हां	GET, HEAD, PUT, POST, DELETE में से एक या अधिक।
AllowedHeaders	string[]	नहीं	ऐसे हेडर जो ब्राउज़र अनुरोधों में शामिल कर सकते हैं। डिफ़ॉल्ट: कोई नहीं। सभी की अनुमति देने के लिए ["*"] का उपयोग करें (AWS SDK v3 के लिए अनुशंसित जो Authorization, x-amz-* आदि भेजता है)।
ExposeHeaders	string[]	नहीं	ब्राउज़र JavaScript को पढ़ने योग्य बनाए गए रिस्पॉन्स हेडर। यदि आपके ऐप को लौटाए गए CID की आवश्यकता है तो ETag और x-amz-meta-cid शामिल करें।
MaxAgeSeconds	number	नहीं	ब्राउज़र प्रीफ्लाइट को कितनी देर तक कैश करते हैं। 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 नियम और बकेट नाम (यदि दावा किया गया है) लौटाता है।

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

DELETE /folders/{folderId}/cors

सभी CORS नियमों को हटाता है। बकेट के विरुद्ध ब्राउज़र प्रीफ्लाइट तब तक बंद रहेंगे जब तक नए नियम सेट नहीं किए जाते।

डैशबोर्ड विकल्प

Files पेज पर, प्रत्येक फोल्डर के एक्शन मेनू में एक S3 CORS प्रविष्टि होती है जो एक फॉर्म-आधारित एडिटर खोलती है। इस REST एंडपॉइंट और S3 API के माध्यम से PutBucketCors के समान अंतर्निहित स्टोर।