Mappar

Mappar organiserar dina uppladdade filer i instrumentpanelen. De är endast metadata som standard — filer behåller sina egna CID:n och flyttas inte på IPFS — men du kan också ta en ögonblicksbild av en mapp för att materialisera den som en riktig UnixFS-katalog och få en CID för det hela.

När du skulle ta en ögonblicksbild av en mapp

En mappögonblicksbild är en enskild IPFS-katalog-CID som innehåller varje fil i mappen, adresserbar via namn. Med den kan du:

• Dela hela mappen via en URL: https://ipfs.ninja/ipfs/{dirCid}/
• Slå upp https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (eller vilken annan gateway som helst) direkt
• Släppa in CID:n i en ENS contenthash för att hosta en statisk webbplats
• Använda den som bas-CID för en NFT-samling så att varje token refererar till ipfs://{dirCid}/<id>.json
• Fästa katalogen någon annanstans — varje IPFS-gateway i världen vet hur man löser upp en UnixFS-katalog-CID

Ögonblicksbilder är innehållsadresserade: identiskt mappinnehåll ger alltid samma CID. Att ta en ny ögonblicksbild av en mapp du inte har ändrat returnerar samma CID som tidigare. Att lägga till/ta bort/döpa om en fil ger en ny CID; den tidigare CID:n förblir fäst och upplösningsbar så länge du inte tar bort dess filer.

Skapa mapp

POST /folders

Parameter	Typ	Obligatorisk	Beskrivning
name	string	Ja	Visningsnamn.
parentFolderId	string | null	Nej	Överordnat mapp-ID för nästlade mappar. Utelämna för en mapp på rotnivå.

Exempel

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

Returnerar:

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

Nyskapade mappar har ingen ögonblicksbild. Fältet latestSnapshot dyker upp på mappen när du anropar POST /folders/{id}/snapshot (se nedan) och i efterföljande GET /folders-svar.

Lista mappar

GET /folders

Returnerar varje mapp i ditt konto, både på rotnivå och nästlade, med den senaste ögonblicksbildens CID för var och en (om någon).

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

fileCount speglar mappens aktuella innehåll; latestSnapshot.fileCount speglar innehållet vid tidpunkten för den senaste ögonblicksbilden. Om de skiljer sig löser ögonblicksbildens CID fortfarande upp men är inaktuell — ta en ny ögonblicksbild för att uppdatera.

Flytta en fil till en mapp

PUT /files/{cid}/move

Parameter	Typ	Obligatorisk	Beskrivning
folderId	string | null	Ja	Mål-mapp-ID, eller null för att flytta filen till roten.

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

Ta en ögonblicksbild av en mapp (få en UnixFS-katalog-CID)

POST /folders/{folderId}/snapshot

Materialisera mappen som en riktig UnixFS-katalog på IPFS-klustret och fäst resultatet. Returnerar en CID för hela mappen. Namnen på barnen kommer från varje fils fileName; dubbletter avkolliderar automatiskt.

Ingen begärandekropp behövs; sökvägsparametern identifierar mappen.

Exempel

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

Returnerar:

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

CID:n persisteras också på mappraden, så efterföljande GET /folders-anrop returnerar den som latestSnapshot.cid utan att behöva ta en ny ögonblicksbild.

Upplösning av en ögonblicksbild

När en ögonblicksbild är fäst löses katalog-CID:n upp via vilken IPFS-gateway som helst. Det enklaste URL-mönstret:

https://ipfs.ninja/ipfs/{dirCid}/         → kataloglistning
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → just den filen

Klustret fäster rekursivt, så barn är också upplösningsbara — även om du senare tar bort originalfilen från ditt konto överlever ögonblicksbildens kopia eftersom det är en separat fästning som rekurserar genom katalogen.

Att ta en ny ögonblicksbild

Att ta en ny ögonblicksbild av en oförändrad mapp returnerar samma CID — katalog-CID:n är innehållsadresserade, så identiskt innehåll ger alltid samma hash, och klustrets pin-anrop känner igen dubbletten och blir en no-op på dess sida.

Obs: själva ögonblicksbildsvägen är inte gratis även när resultatet är samma CID. Varje anrop läser varje fils bytes från IPFS och laddar upp dem igen som en multipart till klustrets /add-endpoint — det är där wrap-with-directory-inpackningen sker. För typiska mappar (≤100 små filer) slutförs detta fortfarande på några sekunder; för mycket stora mappar är det bäst att bara anropa ögonblicksbilden när innehållet faktiskt har ändrats.

Att anropa ögonblicksbild efter att du lagt till eller tagit bort filer ger en annan CID; den tidigare fortsätter att lösas upp så länge du inte tar bort dess underliggande filer.

Begränsningar

• Mappen måste innehålla minst en fil. Tomma mappar returnerar 400 — folder is empty.
• Filnamnstecken URL-kodas i multipart-uppladdningen som Kubo accepterar; gateway-URL:er kan behöva procentkodning för mellanslag eller icke-ASCII-tecken i dina filnamn.
• Ögonblicksbilder räknas mot din plans totala fästningar exakt en gång per unik CID — filblock deduplikeras, så ögonblicksbilden lägger mestadels bara till en liten katalognod ovanpå filer du redan fäster.

Uppdatera en mapp

PUT /folders/{folderId}

Parameter	Typ	Obligatorisk	Beskrivning
name	string	Nej	Nytt visningsnamn.
parentFolderId	string | null	Nej	Ändra överordnad mapp. null flyttar den till roten.

Ta bort en mapp

DELETE /folders/{folderId}

Tar bort mappen och kaskaderar rekursivt genom varje fil och undermapp den innehåller. Omfattas av samma delad-CID-säkerhetsspärr som borttagning av enskilda filer — om andra användare fortfarande fäster en CID du laddat upp, tar din avfästning inte bort den för dem.

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

Konfigurera S3 CORS för en mapp / bucket

Mappar som exponeras via S3-kompatibla API:et fungerar som buckets. Om du driver det API:et från webbläsar-JavaScript behöver du CORS-regler på bucketen så att webbläsarens preflights passerar. Två likvärdiga ytor persisterar till samma lagring:

• PUT /folders/{folderId}/cors — denna REST-endpoint, JWT-autentiserad (används av instrumentpanelen)
• S3-underresurs PUT /{bucket}?cors — SigV4-autentiserad (används av AWS SDK:er, se s3-compatibility.md)

PUT på denna endpoint gör också anspråk på mappens namn som en globalt unik bucket om det inte redan har gjorts anspråk på.

PUT /folders/{folderId}/cors

Ställ in CORS-reglerna för mappens S3-bucket. Upp till 5 regler per bucket, totalt 64 KB.

Parameter	Typ	Obligatorisk	Beskrivning
rules	CorsRule[]	Ja	Array med AWS-formade CORS-regler (se nedan). Icke-tom.
bucketName	string	Nej	Explicit S3-bucket-namn. Standardvärdet är mappens visningsnamn. Om det önskade namnet redan är taget globalt, ange ett alternativ här.

Varje CorsRule:

Fält	Typ	Obligatorisk	Beskrivning
AllowedOrigins	string[]	Ja	Origins som får skicka förfrågningar. Stöder jokertecken (https://*.myapp.com). Använd * för valfri origin.
AllowedMethods	string[]	Ja	En eller flera av GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Nej	Headers som webbläsare får inkludera i förfrågningar. Standard: ingen. Använd ["*"] för att tillåta alla (rekommenderas för AWS SDK v3 som skickar Authorization, x-amz-*, etc.).
ExposeHeaders	string[]	Nej	Svarsheaders som görs läsbara för webbläsar-JavaScript. Inkludera ETag och x-amz-meta-cid om din app behöver den returnerade CID:n.
MaxAgeSeconds	number	Nej	Hur länge webbläsare cachar preflighten. 0-86400. Standard 3600.
ID	string	Nej	Fritextetikett för regeln.

Exempelbegäran

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

Svar 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

Returnerar de aktuella CORS-reglerna plus bucket-namnet (om det gjorts anspråk på).

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

DELETE /folders/{folderId}/cors

Tar bort alla CORS-regler. Webbläsarens preflights mot bucketen kommer att misslyckas tills nya regler är inställda.

Alternativ i instrumentpanelen

På Files-sidan har varje mapps åtgärdsmeny en S3 CORS-post som öppnar en formulärbaserad editor. Samma underliggande lagring som denna REST-endpoint och som PutBucketCors via S3-API:et.