Ordner

Ordner organisieren Ihre hochgeladenen Dateien im Dashboard. Sie sind standardmäßig reine Metadaten — Dateien behalten ihre eigenen CIDs und werden auf IPFS nicht verschoben —, aber Sie können einen Ordner auch snapshotten, um ihn als echtes UnixFS-Verzeichnis zu materialisieren und einen einzigen CID für das Ganze zu erhalten.

Wann Sie einen Ordner snapshotten sollten

Ein Ordner-Snapshot ist ein einzelner IPFS-Verzeichnis-CID, der jede Datei im Ordner enthält, adressierbar nach Name. Damit können Sie:

• Den gesamten Ordner über eine einzige URL teilen: https://ipfs.ninja/ipfs/{dirCid}/
• https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (oder jedes andere Gateway) direkt auflösen
• Den CID in einen ENS-Contenthash einfügen, um eine statische Website zu hosten
• Ihn als Basis-CID einer NFT-Sammlung verwenden, sodass jedes Token auf ipfs://{dirCid}/<id>.json verweist
• Das Verzeichnis anderswo pinnen — jedes IPFS-Gateway weltweit kann einen UnixFS-Verzeichnis-CID auflösen

Snapshots sind inhaltsadressiert: identischer Ordnerinhalt erzeugt immer denselben CID. Ein erneutes Snapshotten eines unveränderten Ordners liefert denselben CID wie zuvor. Das Hinzufügen/Entfernen/Umbenennen einer Datei erzeugt einen neuen CID; der vorherige CID bleibt gepinnt und auflösbar, solange Sie seine Dateien nicht löschen.

Ordner erstellen

POST /folders

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Anzeigename.
parentFolderId	string | null	Nein	ID des übergeordneten Ordners für verschachtelte Ordner. Weglassen für einen Ordner auf oberster Ebene.

Beispiel

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

Antwort:

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

Neu erstellte Ordner haben noch keinen Snapshot. Das Feld latestSnapshot erscheint auf dem Ordner, sobald Sie POST /folders/{id}/snapshot aufrufen (siehe unten), und in nachfolgenden GET /folders-Antworten.

Ordner auflisten

GET /folders

Gibt jeden Ordner in Ihrem Konto zurück, sowohl auf oberster Ebene als auch verschachtelt, mit dem letzten Snapshot-CID für jeden (falls vorhanden).

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

fileCount spiegelt den aktuellen Inhalt des Ordners wider; latestSnapshot.fileCount spiegelt den Inhalt zum Zeitpunkt des letzten Snapshots wider. Wenn sie voneinander abweichen, löst der Snapshot-CID zwar weiterhin auf, ist aber veraltet — snapshotten Sie erneut, um zu aktualisieren.

Datei in einen Ordner verschieben

PUT /files/{cid}/move

Parameter	Typ	Erforderlich	Beschreibung
folderId	string | null	Ja	Ziel-Ordner-ID, oder null, um die Datei in das Stammverzeichnis zu verschieben.

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

Ordner snapshotten (einen UnixFS-Verzeichnis-CID erhalten)

POST /folders/{folderId}/snapshot

Materialisiert den Ordner als echtes UnixFS-Verzeichnis auf dem IPFS-Cluster und pinnt das Ergebnis. Gibt einen CID für den gesamten Ordner zurück. Die Namen der Kindelemente stammen aus dem fileName jeder Datei; Duplikate werden automatisch aufgelöst.

Es ist kein Anfragekörper erforderlich; der Pfadparameter identifiziert den Ordner.

Beispiel

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

Antwort:

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

Der CID wird zudem in der Ordnerzeile gespeichert, sodass nachfolgende GET /folders-Aufrufe ihn als latestSnapshot.cid zurückgeben, ohne einen weiteren Snapshot zu benötigen.

Einen Snapshot auflösen

Sobald ein Snapshot gepinnt ist, löst der Verzeichnis-CID über jedes IPFS-Gateway auf. Das einfachste URL-Muster:

https://ipfs.ninja/ipfs/{dirCid}/         → Verzeichnisauflistung
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → genau diese Datei

Der Cluster pinnt rekursiv, sodass Kindelemente ebenfalls auflösbar sind — selbst wenn Sie später die ursprüngliche Datei aus Ihrem Konto löschen, überlebt die Kopie des Snapshots, weil sie ein separater Pin ist, der durch das Verzeichnis rekursiert.

Erneutes Snapshotten

Ein erneutes Snapshotten eines unveränderten Ordners gibt denselben CID zurück — Verzeichnis-CIDs sind inhaltsadressiert, sodass identischer Inhalt immer denselben Hash erzeugt, und der Pin-Aufruf des Clusters erkennt das Duplikat und ist auf seiner Seite ein No-op.

Hinweis: Der Snapshot-Vorgang selbst ist nicht kostenlos, auch wenn das Ergebnis derselbe CID ist. Jeder Aufruf liest die Bytes jeder Datei erneut von IPFS und lädt sie als Multipart an den /add-Endpunkt des Clusters hoch — dort findet das Einwickeln in ein Verzeichnis statt. Bei typischen Ordnern (≤100 kleine Dateien) ist dies weiterhin in wenigen Sekunden abgeschlossen; bei sehr großen Ordnern sollten Sie den Snapshot nur dann aufrufen, wenn sich der Inhalt tatsächlich geändert hat.

Ein Snapshot-Aufruf, nachdem Sie Dateien hinzugefügt oder entfernt haben, erzeugt einen anderen CID; der vorherige löst weiterhin auf, solange Sie die zugrunde liegenden Dateien nicht löschen.

Limits

• Der Ordner muss mindestens eine Datei enthalten. Leere Ordner geben 400 — folder is empty zurück.
• Zeichen in Dateinamen werden im Multipart-Upload, den Kubo entgegennimmt, URL-kodiert; Gateway-URLs benötigen für Leerzeichen oder Nicht-ASCII-Zeichen in Ihren Dateinamen unter Umständen eine Prozent-Kodierung.
• Snapshots zählen genau einmal pro eindeutigem CID zum Pin-Gesamtwert Ihres Plans — Dateiblöcke werden dedupliziert, sodass der Snapshot größtenteils nur einen winzigen Verzeichnisknoten zu Dateien hinzufügt, die Sie bereits pinnen.

Ordner aktualisieren

PUT /folders/{folderId}

Parameter	Typ	Erforderlich	Beschreibung
name	string	Nein	Neuer Anzeigename.
parentFolderId	string | null	Nein	Ordner neu zuordnen. null verschiebt ihn in das Stammverzeichnis.

Ordner löschen

DELETE /folders/{folderId}

Löscht den Ordner und kaskadiert rekursiv durch jede darin enthaltene Datei und jeden Unterordner. Unterliegt derselben Shared-CID-Sicherheitsprüfung wie einzelne Datei-Löschungen — wenn andere Benutzer einen von Ihnen hochgeladenen CID weiterhin pinnen, entfernt Ihr Unpin ihn für sie nicht.

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

S3-CORS für einen Ordner / Bucket konfigurieren

Ordner, die über die S3-kompatible API freigegeben werden, fungieren als Buckets. Wenn Sie diese API aus Browser-JavaScript heraus ansteuern, benötigen Sie CORS-Regeln für den Bucket, damit Browser-Preflights durchgehen. Zwei gleichwertige Oberflächen schreiben in denselben Speicher:

• PUT /folders/{folderId}/cors — dieser REST-Endpunkt, JWT-authentifiziert (vom Dashboard verwendet)
• S3-Subresource PUT /{bucket}?cors — SigV4-authentifiziert (von AWS SDKs verwendet, siehe s3-compatibility.md)

Das PUT auf diesen Endpunkt beansprucht zudem den Namen des Ordners als global eindeutigen Bucket-Namen, sofern dieser noch nicht beansprucht wurde.

PUT /folders/{folderId}/cors

Legt die CORS-Regeln für den S3-Bucket des Ordners fest. Bis zu 5 Regeln pro Bucket, insgesamt 64 KB.

Parameter	Typ	Erforderlich	Beschreibung
rules	CorsRule[]	Ja	Array von AWS-förmigen CORS-Regeln (siehe unten). Nicht leer.
bucketName	string	Nein	Expliziter S3-Bucket-Name. Standardmäßig der Anzeigename des Ordners. Falls der gewünschte Name bereits global beansprucht ist, übergeben Sie hier eine Alternative.

Jede CorsRule:

Feld	Typ	Erforderlich	Beschreibung
AllowedOrigins	string[]	Ja	Origins, die Anfragen senden dürfen. Unterstützt Wildcards (https://*.myapp.com). Verwenden Sie * für jeden Origin.
AllowedMethods	string[]	Ja	Eine oder mehrere von GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nein	Header, die Browser bei Anfragen einbeziehen dürfen. Standard: keine. Verwenden Sie ["*"], um alle zuzulassen (empfohlen für AWS SDK v3, das Authorization, x-amz-* usw. sendet).
ExposeHeaders	string[]	Nein	Antwort-Header, die für Browser-JavaScript lesbar gemacht werden. Fügen Sie ETag und x-amz-meta-cid hinzu, falls Ihre App den zurückgegebenen CID benötigt.
MaxAgeSeconds	number	Nein	Wie lange Browser das Preflight zwischenspeichern. 0-86400. Standard 3600.
ID	string	Nein	Freitext-Bezeichnung für die Regel.

Beispielanfrage

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

Antwort 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

Gibt die aktuellen CORS-Regeln sowie den Bucket-Namen zurück (falls beansprucht).

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

DELETE /folders/{folderId}/cors

Entfernt alle CORS-Regeln. Browser-Preflights gegen den Bucket schlagen fehl (fail closed), bis neue Regeln festgelegt werden.

Alternative über das Dashboard

Auf der Dateien-Seite hat das Aktionsmenü jedes Ordners einen S3 CORS-Eintrag, der einen formularbasierten Editor öffnet. Gleicher zugrunde liegender Speicher wie dieser REST-Endpunkt und wie PutBucketCors über die S3 API.