Cartelle

Le cartelle organizzano i tuoi file caricati nella dashboard. Per impostazione predefinita sono solo metadati — i file mantengono i propri CID e non vengono spostati su IPFS — ma puoi anche fare lo snapshot di una cartella per materializzarla come una vera directory UnixFS e ottenere un unico CID per l'intero contenuto.

Quando fare lo snapshot di una cartella

Uno snapshot di cartella è un singolo CID di directory IPFS che contiene ogni file della cartella, indirizzabile per nome. Con esso puoi:

• Condividere l'intera cartella tramite un solo URL: https://ipfs.ninja/ipfs/{dirCid}/
• Risolvere https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (o qualsiasi altro gateway) direttamente
• Inserire il CID in un contenthash ENS per ospitare un sito statico
• Usarlo come CID base di una collezione NFT, così che ogni token faccia riferimento a ipfs://{dirCid}/<id>.json
• Pinnare la directory altrove — ogni gateway IPFS al mondo sa come risolvere un CID di directory UnixFS

Gli snapshot sono content-addressed: contenuti di cartella identici producono sempre lo stesso CID. Rifare lo snapshot di una cartella che non hai modificato restituisce lo stesso CID restituito in precedenza. Aggiungere/rimuovere/rinominare un file produce un nuovo CID; il CID precedente rimane pinnato e risolvibile finché non elimini i suoi file.

Creare una cartella

POST /folders

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome visualizzato.
parentFolderId	string | null	No	ID della cartella padre per cartelle annidate. Ometti per una cartella a livello radice.

Esempio

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

Restituisce:

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

Le cartelle appena create non hanno snapshot. Il campo latestSnapshot compare sulla cartella una volta chiamato POST /folders/{id}/snapshot (vedi sotto) e nelle successive risposte di GET /folders.

Elencare le cartelle

GET /folders

Restituisce ogni cartella del tuo account, a livello radice e annidata, con il CID dell'ultimo snapshot per ciascuna (se presente).

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

fileCount riflette il contenuto attuale della cartella; latestSnapshot.fileCount riflette il contenuto al momento dell'ultimo snapshot. Se differiscono, il CID dello snapshot si risolve comunque ma è obsoleto — rifai lo snapshot per aggiornarlo.

Spostare un file in una cartella

PUT /files/{cid}/move

Parametro	Tipo	Obbligatorio	Descrizione
folderId	string | null	Sì	ID della cartella di destinazione, oppure null per spostare il file alla radice.

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

Fare lo snapshot di una cartella (ottenere un CID di directory UnixFS)

POST /folders/{folderId}/snapshot

Materializza la cartella come una vera directory UnixFS sul cluster IPFS e pinna il risultato. Restituisce un unico CID per l'intera cartella. I nomi dei figli provengono dal fileName di ciascun file; i duplicati vengono de-collisi automaticamente.

Non è richiesto alcun corpo della richiesta; il parametro di percorso identifica la cartella.

Esempio

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

Restituisce:

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

Il CID viene anche persistito sulla riga della cartella, quindi le successive chiamate a GET /folders lo restituiscono come latestSnapshot.cid senza bisogno di un altro snapshot.

Risolvere uno snapshot

Una volta pinnato, il CID della directory si risolve tramite qualsiasi gateway IPFS. Lo schema di URL più semplice:

https://ipfs.ninja/ipfs/{dirCid}/         → elenco della directory
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → quel singolo file

Il cluster pinna in modo ricorsivo, quindi anche i figli sono risolvibili — anche se in seguito elimini il file originale dal tuo account, la copia dello snapshot sopravvive perché è un pin separato che ricorre attraverso la directory.

Rifare lo snapshot

Rifare lo snapshot di una cartella invariata restituisce lo stesso CID — i CID di directory sono content-addressed, quindi contenuti identici producono sempre lo stesso hash, e la chiamata di pin del cluster riconosce il duplicato e non ha effetto dal suo lato.

Nota: il percorso di snapshot in sé non è gratuito anche quando il risultato è lo stesso CID. Ogni chiamata rilegge i byte di ogni file da IPFS e li ricarica come multipart verso l'endpoint /add del cluster — è lì che avviene il wrapping con la directory. Per cartelle tipiche (≤100 file di piccole dimensioni) questo si completa comunque in pochi secondi; per cartelle molto grandi è preferibile chiamare lo snapshot solo quando il contenuto è effettivamente cambiato.

Chiamare lo snapshot dopo aver aggiunto o rimosso file produce un CID diverso; quello precedente continua a risolversi finché non elimini i file sottostanti.

Limiti

• La cartella deve contenere almeno un file. Le cartelle vuote restituiscono 400 — folder is empty.
• I caratteri del nome file vengono codificati URL nel caricamento multipart accettato da Kubo; gli URL del gateway potrebbero richiedere una codifica percentuale per spazi o caratteri non ASCII nei nomi dei tuoi file.
• Gli snapshot contano ai fini del totale pin del tuo piano esattamente una volta per ogni CID univoco — i blocchi dei file sono deduplicati, quindi lo snapshot aggiunge per lo più un piccolo nodo di directory sopra i file che già pinni.

Aggiornare una cartella

PUT /folders/{folderId}

Parametro	Tipo	Obbligatorio	Descrizione
name	string	No	Nuovo nome visualizzato.
parentFolderId	string | null	No	Cambia la cartella padre. null la sposta alla radice.

Eliminare una cartella

DELETE /folders/{folderId}

Elimina la cartella e propaga ricorsivamente attraverso ogni file e sottocartella che contiene. Soggetta alla stessa protezione di sicurezza per CID condivisi delle eliminazioni di singoli file — se altri utenti pinnano ancora un CID che hai caricato, il tuo unpin non lo rimuove per loro.

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

Configurare il CORS S3 per una cartella / bucket

Le cartelle esposte tramite l'API compatibile S3 si comportano come bucket. Se stai pilotando quell'API da JavaScript lato browser, hai bisogno di regole CORS sul bucket affinché i preflight del browser passino. Due superfici equivalenti persistono sullo stesso store:

• PUT /folders/{folderId}/cors — questo endpoint REST, autenticato con JWT (usato dalla dashboard)
• Sottorisorsa S3 PUT /{bucket}?cors — autenticato con SigV4 (usato dagli SDK AWS, vedi s3-compatibility.md)

Il PUT su questo endpoint rivendica anche il nome della cartella come nome di bucket univoco a livello globale, se non è già stato rivendicato.

PUT /folders/{folderId}/cors

Imposta le regole CORS per il bucket S3 della cartella. Fino a 5 regole per bucket, 64 KB totali.

Parametro	Tipo	Obbligatorio	Descrizione
rules	CorsRule[]	Sì	Array di regole CORS in formato AWS (vedi sotto). Non vuoto.
bucketName	string	No	Nome esplicito del bucket S3. Il valore predefinito è il nome visualizzato della cartella. Se il nome desiderato è già rivendicato globalmente, passa qui un'alternativa.

Ogni CorsRule:

Campo	Tipo	Obbligatorio	Descrizione
AllowedOrigins	string[]	Sì	Origini autorizzate a inviare richieste. Supporta i caratteri jolly (https://*.myapp.com). Usa * per qualsiasi origine.
AllowedMethods	string[]	Sì	Uno o più tra GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	No	Header che i browser possono includere nelle richieste. Predefinito: nessuno. Usa ["*"] per consentirli tutti (consigliato per AWS SDK v3, che invia Authorization, x-amz-*, ecc.).
ExposeHeaders	string[]	No	Header di risposta resi leggibili al JavaScript del browser. Includi ETag e x-amz-meta-cid se la tua app ha bisogno del CID restituito.
MaxAgeSeconds	number	No	Per quanto tempo i browser mettono in cache il preflight. 0-86400. Predefinito 3600.
ID	string	No	Etichetta in testo libero per la regola.

Esempio di richiesta

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

Risposta 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

Restituisce le regole CORS correnti più il nome del bucket (se rivendicato).

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

DELETE /folders/{folderId}/cors

Rimuove tutte le regole CORS. I preflight del browser verso il bucket falliranno per impostazione predefinita finché non vengono impostate nuove regole.

Alternativa dalla dashboard

Nella pagina Files, il menu azioni di ogni cartella ha una voce S3 CORS che apre un editor basato su form. Stesso store sottostante di questo endpoint REST e di PutBucketCors tramite l'API S3.