Mappen

Mappen organiseren je geüploade bestanden in het dashboard. Ze zijn standaard alleen-metadata — bestanden behouden hun eigen CID's en worden niet verplaatst op IPFS — maar je kunt ook een snapshot van een map maken om deze te materialiseren als een echte UnixFS-directory en één CID voor het geheel te krijgen.

Wanneer je een map zou snapshotten

Een mapsnapshot is één IPFS-directory-CID die elk bestand in de map bevat, adresseerbaar op naam. Hiermee kun je:

• De hele map delen via één URL: https://ipfs.ninja/ipfs/{dirCid}/
• https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (of elke andere gateway) direct oplossen
• De CID in een ENS-contenthash plaatsen om een statische site te hosten
• Het gebruiken als basis-CID van een NFT-collectie, zodat elke token verwijst naar ipfs://{dirCid}/<id>.json
• De directory ergens anders vastzetten — elke IPFS-gateway ter wereld weet hoe een UnixFS-directory-CID op te lossen

Snapshots zijn content-geadresseerd: identieke mapinhoud levert altijd dezelfde CID op. Het opnieuw snapshotten van een map die je niet hebt gewijzigd, geeft dezelfde CID terug als voorheen. Het toevoegen/verwijderen/hernoemen van een bestand levert een nieuwe CID op; de vorige CID blijft vastgezet en oplosbaar zolang je de bijbehorende bestanden niet verwijdert.

Map aanmaken

POST /folders

Parameter	Type	Vereist	Beschrijving
name	string	Ja	Weergavenaam.
parentFolderId	string | null	Nee	Bovenliggende map-ID voor geneste mappen. Weglaten voor een map op het hoogste niveau.

Voorbeeld

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

Retourneert:

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

Nieuw aangemaakte mappen hebben geen snapshot. Het veld latestSnapshot verschijnt op de map zodra je POST /folders/{id}/snapshot aanroept (zie hieronder), en in latere GET /folders-responsen.

Mappen oplijsten

GET /folders

Retourneert elke map in je account, zowel op het hoogste niveau als genest, met de meest recente snapshot-CID voor elk (indien aanwezig).

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

fileCount weerspiegelt de huidige inhoud van de map; latestSnapshot.fileCount weerspiegelt de inhoud op het moment van de laatste snapshot. Als deze verschillen, lost de snapshot-CID nog steeds op, maar is deze verouderd — snapshot opnieuw om bij te werken.

Een bestand naar een map verplaatsen

PUT /files/{cid}/move

Parameter	Type	Vereist	Beschrijving
folderId	string | null	Ja	Doelmap-ID, of null om het bestand naar de root te verplaatsen.

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

Snapshot van een map maken (een UnixFS-directory-CID verkrijgen)

POST /folders/{folderId}/snapshot

Materialiseer de map als een echte UnixFS-directory op het IPFS-cluster en zet het resultaat vast. Retourneert één CID voor de hele map. Namen van onderliggende items komen van de fileName van elk bestand; duplicaten worden automatisch gede-collideerd.

Er is geen verzoekinhoud nodig; de padparameter identificeert de map.

Voorbeeld

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

Retourneert:

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

De CID wordt ook opgeslagen op de maprij, zodat latere GET /folders-aanroepen deze teruggeven als latestSnapshot.cid zonder dat er een nieuwe snapshot nodig is.

Een snapshot oplossen

Zodra een snapshot is vastgezet, lost de directory-CID op via elke IPFS-gateway. Het eenvoudigste URL-patroon:

https://ipfs.ninja/ipfs/{dirCid}/         → directorylijst
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → dat ene bestand

Het cluster zet recursief vast, dus onderliggende items zijn ook oplosbaar — zelfs als je later het oorspronkelijke bestand uit je account verwijdert, overleeft de kopie in de snapshot omdat het een aparte pin is die recursief door de directory gaat.

Opnieuw snapshotten

Het opnieuw snapshotten van een ongewijzigde map geeft dezelfde CID terug — directory-CID's zijn content-geadresseerd, dus identieke inhoud levert altijd dezelfde hash op, en de pin-aanroep van het cluster herkent het duplicaat en is een no-op aan die kant.

Let op: het snapshot-pad zelf is niet gratis, zelfs als het resultaat dezelfde CID is. Elke aanroep leest de bytes van elk bestand terug van IPFS en uploadt ze opnieuw als multipart naar het /add-endpoint van het cluster — daar gebeurt de wrap-with-directory-verpakking. Voor typische mappen (≤100 kleine bestanden) is dit nog steeds binnen enkele seconden voltooid; voor zeer grote mappen kun je beter alleen een snapshot maken wanneer de inhoud daadwerkelijk is veranderd.

Het aanroepen van snapshot nadat je bestanden hebt toegevoegd of verwijderd, levert een andere CID op; de vorige blijft oplosbaar zolang je de onderliggende bestanden niet verwijdert.

Limieten

• De map moet ten minste één bestand bevatten. Lege mappen geven 400 — folder is empty terug.
• Bestandsnaamtekens worden URL-gecodeerd in de multipart-upload die Kubo accepteert; gateway-URL's kunnen percent-codering nodig hebben voor spaties of niet-ASCII-tekens in je bestandsnamen.
• Snapshots tellen precies één keer per unieke CID mee voor het totale aantal pins van je plan — bestandsblokken worden gededupliceerd, dus de snapshot voegt vooral een klein directory-node toe bovenop bestanden die je al vastzet.

Een map bijwerken

PUT /folders/{folderId}

Parameter	Type	Vereist	Beschrijving
name	string	Nee	Nieuwe weergavenaam.
parentFolderId	string | null	Nee	Verplaats de map naar een andere bovenliggende map. null verplaatst deze naar de root.

Een map verwijderen

DELETE /folders/{folderId}

Verwijdert de map en cascadeert recursief door elk bestand en elke submap erin. Onderhevig aan dezelfde shared-CID-veiligheidscontrole als individuele bestandsverwijderingen — als andere gebruikers een CID die jij hebt geüpload nog steeds vastzetten, verwijdert jouw unpin deze niet voor hen.

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

S3 CORS configureren voor een map/bucket

Mappen die worden blootgesteld via de S3-compatibele API fungeren als buckets. Als je die API aanstuurt vanuit browser-JavaScript, heb je CORS-regels op de bucket nodig zodat browser-preflights slagen. Twee gelijkwaardige interfaces bewaren naar dezelfde store:

• PUT /folders/{folderId}/cors — dit REST-endpoint, JWT-geauthenticeerd (gebruikt door het dashboard)
• S3-subresource PUT /{bucket}?cors — SigV4-geauthenticeerd (gebruikt door AWS SDK's, zie s3-compatibility.md)

De PUT op dit endpoint claimt ook de naam van de map als een wereldwijd unieke bucket als deze nog niet geclaimd is.

PUT /folders/{folderId}/cors

Stel de CORS-regels in voor de S3-bucket van de map. Tot 5 regels per bucket, 64 KB totaal.

Parameter	Type	Vereist	Beschrijving
rules	CorsRule[]	Ja	Array van AWS-gevormde CORS-regels (zie hieronder). Niet leeg.
bucketName	string	Nee	Expliciete S3-bucketnaam. Standaard de weergavenaam van de map. Als de gewenste naam al globaal geclaimd is, geef hier een alternatief op.

Elke CorsRule:

Veld	Type	Vereist	Beschrijving
AllowedOrigins	string[]	Ja	Origins die verzoeken mogen sturen. Ondersteunt wildcards (https://*.myapp.com). Gebruik * voor elke origin.
AllowedMethods	string[]	Ja	Een of meer van GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nee	Headers die browsers mogen meesturen bij verzoeken. Standaard: geen. Gebruik ["*"] om alles toe te staan (aanbevolen voor AWS SDK v3, dat Authorization, x-amz-*, enz. stuurt).
ExposeHeaders	string[]	Nee	Responsheaders die leesbaar worden gemaakt voor browser-JavaScript. Neem ETag en x-amz-meta-cid op als je app de geretourneerde CID nodig heeft.
MaxAgeSeconds	number	Nee	Hoelang browsers de preflight cachen. 0-86400. Standaard 3600.
ID	string	Nee	Vrij te kiezen label voor de regel.

Voorbeeldverzoek

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

Respons 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

Retourneert de huidige CORS-regels plus de bucketnaam (indien geclaimd).

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

DELETE /folders/{folderId}/cors

Verwijdert alle CORS-regels. Browser-preflights tegen de bucket zullen daarna standaard mislukken totdat nieuwe regels zijn ingesteld.

Dashboard-alternatief

Op de pagina Bestanden heeft het actiemenu van elke map een S3 CORS-item dat een formuliergebaseerde editor opent. Zelfde onderliggende store als dit REST-endpoint en als PutBucketCors via de S3 API.