File

Carica, elenca e recupera file su IPFS.

Caricare un File

POST /upload/new

Carica qualsiasi file su IPFS. Il file viene pinnato e viene restituito un CID permanente.

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
content	string | object	Sì	Oggetto/array JSON, oppure dati di file codificati in base64 (immagini, PDF, HTML o qualsiasi altro tipo di file). Per le importazioni CAR, file CAR codificato in base64.
car	boolean	No	Imposta su true per importare un file CAR (DAG import). Preserva i CID esatti.
description	string	No	Breve descrizione del contenuto caricato.
metadata	object	No	Coppie chiave-valore personalizzate da allegare al file. Massimo 10 chiavi. Le chiavi devono essere alfanumeriche o underscore, 1-64 caratteri. I valori devono essere stringhe, massimo 256 caratteri ciascuno. La dimensione totale dei metadati non deve superare i 4 KB.

Esempio di richiesta

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

Caricare un'immagine (base64)

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: image,
    description: "Profile photo"
  })
});

Risposta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

CIDv1 di default

I nuovi caricamenti restituiscono CID moderni in formato CIDv1 (bafk… per contenuti di piccole dimensioni a blocco singolo, bafy… per file e directory più grandi) secondo il profilo IPIP-0499 unixfs-v1-2025 — chunk da 1 MiB con raw leaves. I CID legacy Qm… dei caricamenti precedenti restano completamente risolvibili e continuano a funzionare con tutti gli endpoint.

Alternativa dashboard

La pagina /upload della dashboard accetta il trascinamento (drag-and-drop) di file, cartelle (impacchettate in una directory UnixFS direttamente nel browser) e archivi .car — tutto instradato attraverso questo stesso endpoint. Consulta CAR Import per i dettagli sul percorso CAR.

Rinominare un File

PUT /files/:cid/name

Aggiorna il nome visualizzato di un file. Il CID non cambia — è un hash del contenuto — cambia solo l'etichetta che vedi nel tuo elenco file.

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nuovo nome visualizzato. 1-200 caratteri. Non deve contenere separatori di percorso (/, \). I nomi composti solo da spazi vengono rifiutati.

Esempio di richiesta

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

Risposta 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

Dashboard

La pagina File ha una voce Rinomina nel menu azioni di ogni riga file (pulsante a tre puntini). Stesso effetto, senza bisogno di codice.

Elencare i File

GET /upload/list

Recupera un elenco dei tuoi file IPFS caricati entro un intervallo di tempo.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
from	number	Sì	Inizio dell'intervallo di tempo, timestamp Unix in millisecondi.
to	number	Sì	Fine dell'intervallo di tempo, timestamp Unix in millisecondi.

Esempio di richiesta

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

Risposta 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

Recuperare un File

GET /file/:cid

Recupera i metadati di un file caricato specifico usando il suo CID.

Parametri di percorso

Parametro	Tipo	Obbligatorio	Descrizione
cid	string	Sì	L'identificatore di contenuto IPFS del file.

Esempio di richiesta

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Risposta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}