Φάκελοι

Οι φάκελοι οργανώνουν τα αρχεία που έχετε ανεβάσει μέσα στο dashboard. Είναι μόνο μεταδεδομένα από προεπιλογή — τα αρχεία διατηρούν τα δικά τους CID και δεν μετακινούνται στο IPFS — αλλά μπορείτε επίσης να δημιουργήσετε στιγμιότυπο (snapshot) ενός φακέλου ώστε να τον υλοποιήσετε ως πραγματικό UnixFS directory και να αποκτήσετε ένα CID για ολόκληρο το σύνολο.

Πότε να δημιουργήσετε στιγμιότυπο ενός φακέλου

Ένα στιγμιότυπο φακέλου είναι ένα ενιαίο IPFS directory CID που περιέχει κάθε αρχείο του φακέλου, προσβάσιμο βάσει ονόματος. Με αυτό μπορείτε να:

• Μοιραστείτε ολόκληρο τον φάκελο μέσω ενός URL: https://ipfs.ninja/ipfs/{dirCid}/
• Αναλύσετε (resolve) το https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (ή σε οποιοδήποτε άλλο gateway) απευθείας
• Τοποθετήσετε το CID σε ένα ENS contenthash για να φιλοξενήσετε έναν στατικό ιστότοπο
• Το χρησιμοποιήσετε ως το βασικό CID μιας συλλογής NFT, ώστε κάθε token να αναφέρεται στο ipfs://{dirCid}/<id>.json
• Καρφιτσώσετε το directory οπουδήποτε αλλού — κάθε IPFS gateway στον κόσμο ξέρει πώς να αναλύσει ένα UnixFS dir CID

Τα στιγμιότυπα είναι content-addressed: το ίδιο περιεχόμενο φακέλου παράγει πάντα το ίδιο 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 του στιγμιότυπου εξακολουθεί να αναλύεται αλλά είναι μη ενημερωμένο (stale) — δημιουργήστε νέο στιγμιότυπο για ανανέωση.

Μετακίνηση αρχείου σε φάκελο

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

Υλοποιεί τον φάκελο ως πραγματικό UnixFS directory στο cluster IPFS και καρφιτσώνει το αποτέλεσμα. Επιστρέφει ένα CID για ολόκληρο τον φάκελο. Τα ονόματα των παιδιών (children) προέρχονται από το fileName κάθε αρχείου· τυχόν διπλότυπα αποσυγκρούονται (de-collided) αυτόματα.

Δεν απαιτείται σώμα αιτήματος (request body)· η παράμετρος διαδρομής προσδιορίζει τον φάκελο.

Παράδειγμα

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 χωρίς να χρειάζεται νέο στιγμιότυπο.

Ανάλυση (resolving) ενός στιγμιότυπου

Μόλις καρφιτσωθεί ένα στιγμιότυπο, το directory CID αναλύεται μέσω οποιουδήποτε IPFS gateway. Το απλούστερο μοτίβο URL:

https://ipfs.ninja/ipfs/{dirCid}/         → λίστα περιεχομένων directory
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → εκείνο το ένα αρχείο

Το cluster καρφιτσώνει αναδρομικά, οπότε τα παιδιά (children) είναι επίσης προσβάσιμα — ακόμα κι αν αργότερα διαγράψετε το αρχικό αρχείο από τον λογαριασμό σας, το αντίγραφο του στιγμιότυπου επιβιώνει επειδή αποτελεί ξεχωριστό pin που ανατρέχει αναδρομικά μέσα από το directory.

Επανάληψη στιγμιότυπου

Η επανάληψη στιγμιότυπου σε αμετάβλητο φάκελο επιστρέφει το ίδιο CID — τα directory CID είναι content-addressed, οπότε το ίδιο περιεχόμενο παράγει πάντα το ίδιο hash, και η κλήση pin του cluster αναγνωρίζει το διπλότυπο και δεν κάνει τίποτα (no-op) στο δικό της άκρο.

Σημείωση: η ίδια η διαδρομή στιγμιότυπου δεν είναι δωρεάν ακόμα κι όταν το αποτέλεσμα είναι το ίδιο CID. Κάθε κλήση διαβάζει ξανά τα bytes κάθε αρχείου από το IPFS και τα ξανα-ανεβάζει ως multipart στο endpoint /add του cluster — εκεί συμβαίνει το wrap-with-directory. Για τυπικούς φακέλους (≤100 μικρά αρχεία) αυτό ολοκληρώνεται σε λίγα δευτερόλεπτα· για πολύ μεγάλους φακέλους προτιμήστε να καλείτε το snapshot μόνο όταν το περιεχόμενο έχει πράγματι αλλάξει.

Η κλήση snapshot αφού έχετε προσθέσει ή αφαιρέσει αρχεία παράγει διαφορετικό CID· το προηγούμενο συνεχίζει να αναλύεται όσο δεν διαγράφετε τα υποκείμενα αρχεία του.

Όρια

• Ο φάκελος πρέπει να περιέχει τουλάχιστον ένα αρχείο. Οι κενοί φάκελοι επιστρέφουν 400 — folder is empty.
• Οι χαρακτήρες των ονομάτων αρχείων γίνονται URL-encoded στο multipart upload που δέχεται το Kubo· τα URL του gateway ενδέχεται να χρειάζονται percent-encoding για κενά ή μη ASCII χαρακτήρες στα ονόματα αρχείων σας.
• Τα στιγμιότυπα προσμετρώνται στο σύνολο pin του πλάνου σας ακριβώς μία φορά ανά μοναδικό CID — τα blocks αρχείων γίνονται deduplicated, οπότε το στιγμιότυπο κατά κύριο λόγο προσθέτει έναν μικρό directory κόμβο πάνω από αρχεία που ήδη καρφιτσώνετε.

Ενημέρωση φακέλου

PUT /folders/{folderId}

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
name	string	Όχι	Νέο όνομα εμφάνισης.
parentFolderId	string | null	Όχι	Επαναπροσδιορισμός γονικού φακέλου. Το null το μετακινεί στη ρίζα.

Διαγραφή φακέλου

DELETE /folders/{folderId}

Διαγράφει τον φάκελο και ανατρέχει αναδρομικά (cascade) σε κάθε αρχείο και υποφάκελο που περιέχει. Υπόκειται στην ίδια δικλείδα ασφαλείας κοινόχρηστου CID (shared-CID) όπως και οι μεμονωμένες διαγραφές αρχείων — αν άλλοι χρήστες εξακολουθούν να καρφιτσώνουν ένα CID που ανεβάσατε, το unpin σας δεν το αφαιρεί για εκείνους.

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

Ρύθμιση S3 CORS για φάκελο / bucket

Οι φάκελοι που εκτίθενται μέσω του S3-compatible API λειτουργούν ως buckets. Αν οδηγείτε αυτό το API από JavaScript browser, χρειάζεστε κανόνες CORS στο bucket ώστε τα preflight αιτήματα του browser να περνούν. Δύο ισοδύναμες επιφάνειες αποθηκεύουν στο ίδιο store:

• PUT /folders/{folderId}/cors — αυτό το REST endpoint, με JWT authentication (χρησιμοποιείται από το dashboard)
• S3 subresource PUT /{bucket}?cors — με SigV4 authentication (χρησιμοποιείται από τα AWS SDK, δείτε s3-compatibility.md)

Το PUT σε αυτό το endpoint διεκδικεί επίσης το όνομα του φακέλου ως παγκοσμίως-μοναδικό bucket, εφόσον δεν έχει ήδη διεκδικηθεί.

PUT /folders/{folderId}/cors

Ορίστε τους κανόνες CORS για το S3 bucket του φακέλου. Έως 5 κανόνες ανά bucket, 64 KB συνολικά.

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
rules	CorsRule[]	Ναι	Πίνακας κανόνων CORS σε μορφή AWS (δείτε παρακάτω). Μη κενός.
bucketName	string	Όχι	Ρητό όνομα S3 bucket. Προεπιλογή το όνομα εμφάνισης του φακέλου. Αν το επιθυμητό όνομα έχει ήδη διεκδικηθεί παγκοσμίως, περάστε εδώ μια εναλλακτική τιμή.

Κάθε CorsRule:

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
AllowedOrigins	string[]	Ναι	Origins που επιτρέπεται να στέλνουν αιτήματα. Υποστηρίζει wildcards (https://*.myapp.com). Χρησιμοποιήστε * για οποιοδήποτε origin.
AllowedMethods	string[]	Ναι	Ένα ή περισσότερα από GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Όχι	Headers που οι browsers μπορούν να συμπεριλάβουν στα αιτήματα. Προεπιλογή: κανένα. Χρησιμοποιήστε ["*"] για να επιτρέψετε όλα (συνιστάται για το AWS SDK v3 που στέλνει Authorization, x-amz-*, κ.λπ.).
ExposeHeaders	string[]	Όχι	Headers απάντησης που γίνονται αναγνώσιμα από τη browser JavaScript. Συμπεριλάβετε ETag και x-amz-meta-cid αν η εφαρμογή σας χρειάζεται το επιστρεφόμενο CID.
MaxAgeSeconds	number	Όχι	Πόσο καιρό οι browsers κρατούν στην cache το 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 αιτήματα του browser προς το bucket θα αποτυγχάνουν κλειστά (fail closed) μέχρι να οριστούν νέοι κανόνες.

Εναλλακτική στο Dashboard

Στη σελίδα Files, το μενού ενεργειών κάθε φακέλου έχει μια καταχώρηση S3 CORS που ανοίγει έναν επεξεργαστή βασισμένο σε φόρμα. Χρησιμοποιεί το ίδιο υποκείμενο store με αυτό το REST endpoint και με το PutBucketCors μέσω του S3 API.