Riferimento API

Tutti gli endpoint, i parametri, i formati di richiesta/risposta e i codici di errore.

URL base

https://api.ipfs.ninja

Tutte le richieste richiedono una API key tramite l'header X-Api-Key. Consulta Autenticazione per i dettagli.

Endpoint

Metodo	Percorso	Descrizione	Pagina
POST	/upload/new	Carica un file su IPFS	File
GET	/upload/list	Elenca i file caricati	File
GET	/file/:cid	Ottieni metadati del file tramite CID	File
PUT	/files/:cid/name	Rinomina un file	File
PUT	/files/:cid/move	Sposta un file in una cartella	Cartelle
POST	/pin	Pinna un CID esistente dalla rete IPFS (supporta suggerimenti di swarm-connect)	Pinning
GET	/pin/:cid	Controlla lo stato del pin	Pinning
POST	/folders	Crea una cartella	Cartelle
GET	/folders	Elenca le cartelle	Cartelle
PUT	/folders/:folderId	Aggiorna una cartella	Cartelle
DELETE	/folders/:folderId	Elimina una cartella	Cartelle
POST	/folders/:folderId/snapshot	Crea uno snapshot di una cartella in un CID di directory	Cartelle
PUT	/folders/:folderId/cors	Imposta la configurazione CORS per bucket	Cartelle
GET	/folders/:folderId/cors	Ottieni la configurazione CORS per bucket	Cartelle
DELETE	/folders/:folderId/cors	Rimuovi la configurazione CORS per bucket	Cartelle
GET	/user/profile	Ottieni il profilo utente	Profilo
POST	/apikeys	Crea API key	API Keys
GET	/apikeys	Elenca le API key	API Keys
DELETE	/apikeys/:key	Elimina API key	API Keys
GET	/analytics	Analisi di utilizzo	Analytics
PUT	/gateway-settings	Aggiorna impostazioni gateway	Gateway
POST	/gateway-tokens	Crea token gateway	Gateway
GET	/gateway-tokens	Elenca i token gateway	Gateway
DELETE	/gateway-tokens/:prefix	Elimina token gateway	Gateway
POST	/upload/signed-url	Genera token di caricamento firmato	Token firmati
GET	/signed-tokens	Elenca i token firmati	Token firmati
DELETE	/signed-tokens/:tokenId	Revoca token firmato	Token firmati
GET	/image/:cid	Ottimizza immagine al volo	Ottimizzazione immagini

CIDv1 per impostazione predefinita

I caricamenti e i pin restituiscono CIDv1 moderni (bafk… per contenuti a blocco singolo di piccole dimensioni, bafy… per file e directory più grandi) seguendo il profilo IPIP-0499 unixfs-v1-2025. I CID legacy Qm… dei caricamenti precedenti restano completamente risolvibili ovunque — Qm… è un input valido per qualsiasi endpoint che accetta un CID.

API Compatibile con S3

Usa qualsiasi AWS SDK per caricare e gestire i file su IPFS Ninja. Punta il tuo client S3 a https://s3.ipfs.ninja usando la tua API key come credenziali.

https://s3.ipfs.ninja

Operazione S3	Descrizione
PutObject	Carica un file su IPFS
GetObject	Scarica un file
HeadObject	Ottieni metadati del file
DeleteObject	Rimuovi il pin ed elimina un file
ListObjectsV2	Elenca i file con filtro per prefisso
CreateMultipartUpload	Avvia un caricamento multipart (fino a 5 GB)
UploadPart	Carica una parte
CompleteMultipartUpload	Completa il caricamento multipart
ListBuckets	Elenca i tuoi gateway
CreateBucket	Crea un gateway (i nomi dei bucket sono univoci a livello globale — restituisce BucketAlreadyExists se già in uso)
DeleteBucket	Elimina un gateway
PutBucketCors	Configura le regole CORS per bucket (necessario per l'uso dell'SDK da browser)
GetBucketCors	Leggi la configurazione CORS corrente di un bucket
DeleteBucketCors	Rimuovi tutte le regole CORS da un bucket

Consulta Compatibilità S3 per la documentazione completa, esempi di codice e guide di migrazione.