Carpetes

Les carpetes organitzen els vostres fitxers pujats al tauler de control. Per defecte només són metadata — els fitxers conserven els seus propis CID i no es mouen a IPFS — però també podeu fer un snapshot d'una carpeta per materialitzar-la com un directori UnixFS real i obtenir un sol CID per a tot el conjunt.

Quan fer un snapshot d'una carpeta

Un snapshot de carpeta és un únic CID de directori IPFS que conté tots els fitxers de la carpeta, adreçables pel seu nom. Amb ell podeu:

• Compartir tota la carpeta amb una sola URL: https://ipfs.ninja/ipfs/{dirCid}/
• Resoldre https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (o qualsevol altre gateway) directament
• Posar el CID en un contenthash d'ENS per allotjar un lloc web estàtic
• Utilitzar-lo com a CID base d'una col·lecció NFT perquè cada token faci referència a ipfs://{dirCid}/<id>.json
• Fixar el directori en qualsevol altre lloc — tots els gateways IPFS del món saben resoldre un CID de directori UnixFS

Els snapshots són adreçats per contingut: continguts de carpeta idèntics sempre produeixen el mateix CID. Tornar a fer un snapshot d'una carpeta que no heu modificat retorna el mateix CID que abans. Afegir/eliminar/canviar el nom d'un fitxer produeix un nou CID; el CID anterior es manté fixat i resoluble sempre que no elimineu els seus fitxers.

Crear carpeta

POST /folders

Paràmetre	Tipus	Requerit	Descripció
name	string	Sí	Nom a mostrar.
parentFolderId	string | null	No	ID de la carpeta pare per a carpetes imbricades. Ometeu-lo per a una carpeta d'arrel.

Exemple

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

Retorna:

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

Les carpetes acabades de crear no tenen snapshot. El camp latestSnapshot apareix a la carpeta un cop crideu POST /folders/{id}/snapshot (vegeu més avall) i en les respostes posteriors de GET /folders.

Llistar carpetes

GET /folders

Retorna totes les carpetes del vostre compte, tant les d'arrel com les imbricades, amb el CID del darrer snapshot per a cadascuna (si n'hi ha).

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

fileCount reflecteix el contingut actual de la carpeta; latestSnapshot.fileCount reflecteix el contingut en el moment del darrer snapshot. Si difereixen, el CID del snapshot encara es resol però està obsolet — torneu a fer un snapshot per actualitzar-lo.

Moure un fitxer a una carpeta

PUT /files/{cid}/move

Paràmetre	Tipus	Requerit	Descripció
folderId	string | null	Sí	ID de la carpeta de destinació, o null per moure el fitxer a l'arrel.

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

Fer un snapshot d'una carpeta (obtenir un CID de directori UnixFS)

POST /folders/{folderId}/snapshot

Materialitza la carpeta com un directori UnixFS real al clúster IPFS i fixa el resultat. Retorna un sol CID per a tota la carpeta. Els noms dels fills provenen del fileName de cada fitxer; els duplicats es desambigüen automàticament.

No cal cap cos de sol·licitud; el paràmetre de ruta identifica la carpeta.

Exemple

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

Retorna:

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

El CID també es persisteix a la fila de la carpeta, així que les crides posteriors a GET /folders el retornen com a latestSnapshot.cid sense necessitat d'un altre snapshot.

Resoldre un snapshot

Un cop un snapshot està fixat, el CID de directori es resol a través de qualsevol gateway IPFS. El patró d'URL més senzill:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → that one file

El clúster fixa recursivament, de manera que els fills també són resolubles — fins i tot si més tard elimineu el fitxer original del vostre compte, la còpia del snapshot sobreviu perquè és una fixació separada que recorre el directori.

Tornar a fer un snapshot

Tornar a fer un snapshot d'una carpeta sense canvis retorna el mateix CID — els CID de directori s'adrecen per contingut, així que continguts idèntics sempre produeixen el mateix hash, i la crida de fixació del clúster reconeix el duplicat i no fa res des de la seva banda.

Nota: el camí del snapshot en si no és gratuït encara que el resultat sigui el mateix CID. Cada crida llegeix els bytes de cada fitxer de tornada des d'IPFS i els torna a pujar com a multipart a l'endpoint /add del clúster — allà és on passa l'embolcallat amb el directori. Per a carpetes típiques (≤100 fitxers petits) això encara es completa en pocs segons; per a carpetes molt grans, és preferible cridar el snapshot només quan el contingut realment ha canviat.

Cridar el snapshot després d'afegir o eliminar fitxers produeix un CID diferent; l'anterior continua resolent-se sempre que no elimineu els seus fitxers subjacents.

Límits

• La carpeta ha de contenir com a mínim un fitxer. Les carpetes buides retornen 400 — folder is empty.
• Els caràcters del nom de fitxer es codifiquen com a URL a la pujada multipart que accepta Kubo; les URL del gateway poden necessitar codificació percentual per a espais o caràcters no ASCII als vostres noms de fitxer.
• Els snapshots compten per al total de fixacions del vostre pla exactament un cop per CID únic — els blocs de fitxer es desduplicen, així que el snapshot majoritàriament afegeix un petit node de directori sobre fitxers que ja teniu fixats.

Actualitzar una carpeta

PUT /folders/{folderId}

Paràmetre	Tipus	Requerit	Descripció
name	string	No	Nou nom a mostrar.
parentFolderId	string | null	No	Canvia la carpeta pare. null la mou a l'arrel.

Eliminar una carpeta

DELETE /folders/{folderId}

Elimina la carpeta i propaga recursivament a través de tots els fitxers i subcarpetes que conté. Subjecte a la mateixa protecció de seguretat de CID compartit que les eliminacions de fitxers individuals — si altres usuaris encara fixen un CID que vau pujar, el vostre desfixament no l'elimina per a ells.

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

Configurar S3 CORS per a una carpeta / bucket

Les carpetes exposades a través de l'API compatible amb S3 actuen com a buckets. Si crides aquesta API des de JavaScript al navegador, necessites regles CORS al bucket perquè els preflights del navegador passin. Dues superfícies equivalents persisteixen al mateix magatzem:

• PUT /folders/{folderId}/cors — aquest endpoint REST, autenticat amb JWT (utilitzat pel tauler de control)
• Subrecurs S3 PUT /{bucket}?cors — autenticat amb SigV4 (utilitzat pels AWS SDK, vegeu s3-compatibility.md)

El PUT en aquest endpoint també reclama el nom de la carpeta com a bucket únic globalment si encara no ha estat reclamat.

PUT /folders/{folderId}/cors

Estableix les regles CORS per al bucket S3 de la carpeta. Fins a 5 regles per bucket, 64 KB en total.

Paràmetre	Tipus	Requerit	Descripció
rules	CorsRule[]	Sí	Matriu de regles CORS amb la forma d'AWS (vegeu més avall). No pot ser buida.
bucketName	string	No	Nom explícit del bucket S3. Per defecte, el nom a mostrar de la carpeta. Si el nom desitjat ja està reclamat globalment, passeu-ne un altre aquí.

Cada CorsRule:

Camp	Tipus	Requerit	Descripció
AllowedOrigins	string[]	Sí	Orígens autoritzats a enviar sol·licituds. Admet comodins (https://*.myapp.com). Utilitzeu * per a qualsevol origen.
AllowedMethods	string[]	Sí	Un o més de GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	No	Capçaleres que els navegadors poden incloure a les sol·licituds. Per defecte: cap. Utilitzeu ["*"] per permetre-les totes (recomanat per a l'AWS SDK v3, que envia Authorization, x-amz-*, etc.).
ExposeHeaders	string[]	No	Capçaleres de resposta que es fan llegibles per al JavaScript del navegador. Inclou ETag i x-amz-meta-cid si la teva aplicació necessita el CID retornat.
MaxAgeSeconds	number	No	Quant de temps el navegador guarda en memòria cau el preflight. 0-86400. Per defecte 3600.
ID	string	No	Etiqueta de text lliure per a la regla.

Exemple de sol·licitud

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

Resposta 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

Retorna les regles CORS actuals més el nom del bucket (si ha estat reclamat).

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

DELETE /folders/{folderId}/cors

Elimina totes les regles CORS. Els preflights del navegador contra el bucket fallaran per defecte fins que s'estableixin noves regles.

Alternativa al tauler de control

A la pàgina de Fitxers, el menú d'accions de cada carpeta té una opció S3 CORS que obre un editor basat en formulari. Mateix magatzem subjacent que aquest endpoint REST i que PutBucketCors via l'API S3.