Épinglage

Épinglez du contenu IPFS existant sur votre compte. Lorsque vous épinglez un CID, notre cluster récupère le contenu depuis le réseau IPFS et le maintient disponible en permanence.

Épingler par CID

POST /pin

Paramètre	Type	Requis	Description
cid	string	Oui	Identifiant de contenu IPFS. Toute forme est acceptée : CIDv0 (Qm…), CIDv1 en base32 (bafk…, bafy…, et autres codecs).
description	string	Non	Courte description pour votre référence.
metadata	object	Non	Paires clé-valeur personnalisées à attacher à l'épinglage. Maximum 10 clés. Les clés doivent être alphanumériques ou contenir des underscores, de 1 à 64 caractères. Les valeurs doivent être des chaînes, 256 caractères maximum chacune. La taille totale des métadonnées ne doit pas dépasser 4 Ko.
multiaddresses	string[]	Non	Indices optionnels de connexion au swarm. Jusqu'à 5 multiadresses libp2p de pairs hébergeant le CID. Notre cluster exécute swarm connect sur chacune en parallèle avant l'épinglage, afin que le contenu sur des pairs privés / non-DHT soit accessible sans attendre la découverte DHT. Meilleur effort — un échec de connexion n'échoue pas l'épinglage. Voir Épingler depuis un nœud privé.

Exemple de requête

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

Réponse 202 Accepted

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

Pour les DAG volumineux (>500 blocs ou >50 Mo), la réponse inclut un indicateur async: true :

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

Épingler depuis un nœud privé

Si le CID que vous souhaitez épingler se trouve sur un pair qui ne participe pas au DHT public — un nœud de staging privé, une machine auto-hébergée sur un VPN, ou un poste de travail derrière un NAT — le flux d'épinglage par défaut ne le trouvera pas. Passer une ou plusieurs multiaddresses indique à notre cluster exactement où chercher.

Nous exécutons ipfs swarm connect <multiaddr> pour chaque indice en parallèle avant l'exécution de l'épinglage. Si la connexion réussit, la récupération du DAG de l'épinglage peut communiquer directement avec votre pair au lieu de le rechercher via le DHT. En cas d'échec, l'épinglage se poursuit quand même contre le réseau public (sémantique de meilleur effort).

Exemple : épingler depuis un pair spécifique

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 réponse inclut le statut par indice

{
  "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": { … }
}

Formes de multiadresses acceptées

Les formes courantes sont prises en charge : transports /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr ; protocoles /tcp ou /udp ; surcouches optionnelles /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. La multiadresse doit se terminer par /p2p/<peerId>. Plafond : jusqu'à 5 indices par épinglage.

Obtenir la multiadresse de votre nœud

Sur le pair depuis lequel vous voulez épingler, exécutez ipfs id et copiez l'une des entrées Addresses se terminant par /p2p/<PeerID>. Préférez les adresses publiques routables (/ip4/YOUR_PUBLIC_IP/…) ou basées sur le DNS (/dnsaddr/your.domain/…) afin que notre cluster puisse joindre le pair depuis AWS.

Épingler de très gros répertoires

POST /pin est destiné au contenu déjà présent sur le réseau IPFS — le cluster récupère le DAG bloc par bloc auprès des pairs, ce qui peut prendre plusieurs minutes pour des répertoires de 1 000 fichiers et plus. Pendant cette fenêtre de récupération, certains fichiers enfants peuvent ne pas encore être disponibles localement et les requêtes de gateway vers ceux-ci peuvent expirer. Une fois que le status du parent passe à pinned, chaque enfant est disponible localement et accessible via votre gateway.

Si vous disposez des fichiers en local (plutôt que d'un simple CID), préférez l'import CAR pour les grandes collections de NFT ou les jeux de données — il téléverse le DAG entier vers IPFS Ninja en une seule requête atomique, sans fenêtre de récupération ni état d'épinglage partiel. Créez un CAR avec :

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

Puis importez-le via POST /upload/new avec car: true.

TIP

L'épinglage est asynchrone. La réponse est retournée immédiatement avec le statut pinning. Interrogez l'endpoint de statut pour vérifier quand l'épinglage est terminé.

Vérifier le statut d'épinglage

GET /pin/:cid

Paramètre	Type	Requis	Description
cid	string	Oui	Le CID que vous vérifiez.

Réponse 200 OK

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

Valeurs de statut

Statut	Signification
pinning	Le contenu est en cours de récupération depuis le réseau IPFS. Interrogez à nouveau dans quelques secondes.
pinned	Le contenu est épinglé et disponible via votre compte et votre gateway.
failed	Le contenu n'a pas pu être trouvé sur le réseau IPFS. Le CID peut être invalide ou le contenu n'est plus disponible.

Comment fonctionne l'épinglage

1. Vous soumettez un CID via POST /pin
2. Notre cluster IPFS recherche sur le réseau les nœuds qui possèdent le contenu
3. Le cluster télécharge et épingle le contenu localement
4. Une fois épinglé, le fichier apparaît dans votre liste de fichiers et est accessible via le gateway
5. L'utilisation du stockage est enregistrée une fois l'épinglage terminé

WARNING

Le temps d'épinglage dépend de la taille du fichier et de la disponibilité sur le réseau. Les petits fichiers s'épinglent généralement en quelques secondes. Les fichiers volumineux ou le contenu rarement épinglé peuvent prendre quelques minutes.

Stockage

Le contenu épinglé compte dans la limite de stockage de votre plan. La taille du fichier est enregistrée une fois l'épinglage terminé. Si vous approchez de votre limite de stockage, vous pouvez libérer de l'espace en supprimant des fichiers inutilisés ou passer à un plan supérieur pour plus de capacité.