Pinning

Esegui il pin di contenuti IPFS esistenti sul tuo account. Quando pinni un CID, il nostro cluster recupera il contenuto dalla rete IPFS e lo mantiene disponibile permanentemente.

Pin per CID

POST /pin

Parametro	Tipo	Obbligatorio	Descrizione
cid	string	Sì	Identificatore di contenuto IPFS. Sono accettate tutte le forme: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, e altri codec).
description	string	No	Breve descrizione per tuo riferimento.
metadata	object	No	Coppie chiave-valore personalizzate da allegare al pin. Massimo 10 chiavi. Le chiavi devono essere alfanumeriche o underscore, da 1 a 64 caratteri. I valori devono essere stringhe, massimo 256 caratteri ciascuno. La dimensione totale dei metadati non deve superare 4 KB.
multiaddresses	string[]	No	Suggerimenti opzionali per lo swarm connect. Fino a 5 multiaddress libp2p di peer che ospitano il CID. Il nostro cluster esegue swarm connect verso ciascuno in parallelo prima del pin, così il contenuto su peer privati / non-DHT è raggiungibile senza dover attendere la scoperta via DHT. Best-effort — un connect fallito non fa fallire il pin. Vedi Pinning da un nodo privato.

Esempio di richiesta

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Risposta 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Per DAG di grandi dimensioni (>500 blocchi o >50 MB), la risposta include un flag async: true:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Pinning da un nodo privato

Se il CID che vuoi pinnare risiede su un peer che non partecipa alla DHT pubblica — un nodo di staging privato, una macchina self-hosted su una VPN o una workstation dietro NAT — il flusso di pin predefinito non lo troverà. Passare uno o più multiaddresses indica al nostro cluster esattamente dove cercare.

Eseguiamo ipfs swarm connect <multiaddr> per ogni suggerimento in parallelo prima che il pin venga eseguito. Se il connect ha successo, il recupero del DAG del pin può parlare direttamente con il tuo peer invece di cercarlo tramite la DHT. Se fallisce, il pin procede comunque sulla rete pubblica (semantica best-effort).

Esempio: pin da un peer specifico

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

La risposta include lo stato per ogni suggerimento

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Formati di multiaddress accettati

Sono supportati i formati comuni: trasporti /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocolli /tcp o /udp; upgrade opzionali /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Il multiaddress deve terminare con /p2p/<peerId>. Limite: fino a 5 suggerimenti per pin.

Ottenere il multiaddress del tuo nodo

Sul peer da cui vuoi pinnare, esegui ipfs id e copia una delle voci Addresses che termina in /p2p/<PeerID>. Preferisci indirizzi pubblici instradabili (/ip4/YOUR_PUBLIC_IP/…) o basati su DNS (/dnsaddr/your.domain/…) così il nostro cluster può raggiungere il peer da AWS.

Pinning di directory molto grandi

POST /pin è pensato per contenuti già presenti sulla rete IPFS — il cluster recupera il DAG blocco per blocco dai peer, il che può richiedere diversi minuti per directory con oltre 1.000 file. Durante questa finestra di recupero, alcuni file figli potrebbero non essere ancora disponibili localmente e le richieste al gateway per essi potrebbero andare in timeout. Una volta che lo status del genitore passa a pinned, ogni figlio è disponibile localmente e accessibile tramite il tuo gateway.

Se hai i file in locale (invece di avere solo un CID), preferisci l'importazione CAR per grandi collezioni NFT o dataset — carica l'intero DAG su IPFS Ninja in un'unica richiesta atomica, quindi non c'è finestra di recupero né stato di pin parziale. Crea un CAR con:

npx ipfs-car pack ./my-collection -o collection.car

Poi importalo tramite POST /upload/new con car: true.

TIP

Il pinning è asincrono. La risposta viene restituita immediatamente con stato pinning. Interroga l'endpoint di stato per verificare quando il pinning è completo.

Verifica lo Stato del Pin

GET /pin/:cid

Parametro	Tipo	Obbligatorio	Descrizione
cid	string	Sì	Il CID che stai verificando.

Risposta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Valori di stato

Stato	Significato
pinning	Il contenuto è in fase di recupero dalla rete IPFS. Interroga di nuovo tra qualche secondo.
pinned	Il contenuto è pinnato ed è disponibile tramite il tuo account e il gateway.
failed	Il contenuto non è stato trovato sulla rete IPFS. Il CID potrebbe non essere valido oppure il contenuto potrebbe non essere più disponibile.

Come funziona il pinning

1. Invii un CID tramite POST /pin
2. Il nostro cluster IPFS cerca sulla rete i nodi che hanno il contenuto
3. Il cluster scarica e pinna il contenuto localmente
4. Una volta pinnato, il file appare nella tua lista file ed è accessibile tramite il gateway
5. L'utilizzo dello storage viene registrato al completamento del pinning

WARNING

Il tempo di pinning dipende dalla dimensione del file e dalla disponibilità sulla rete. I file piccoli vengono generalmente pinnati in pochi secondi. I file di grandi dimensioni o i contenuti raramente pinnati possono richiedere minuti.

Archiviazione

Il contenuto pinnato conta ai fini del limite di archiviazione del tuo piano. La dimensione del file viene registrata al completamento del pinning. Se ti avvicini al limite di archiviazione, puoi liberare spazio eliminando i file inutilizzati oppure passare a un piano superiore per maggiore capacità.