Pinning

Sematkan konten IPFS yang sudah ada ke akun Anda. Saat Anda menyematkan CID, kluster kami mengambil konten dari jaringan IPFS dan menjaganya tetap tersedia secara permanen.

Sematkan berdasarkan CID

POST /pin

Parameter	Tipe	Wajib	Deskripsi
cid	string	Ya	IPFS content identifier. Semua bentuk diterima: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, dan codec lainnya).
description	string	Tidak	Deskripsi singkat untuk referensi Anda.
metadata	object	Tidak	Pasangan kunci-nilai kustom untuk dilampirkan ke pin. Maks 10 kunci. Kunci harus alfanumerik atau garis bawah, 1-64 karakter. Nilai harus string, maks 256 karakter masing-masing. Total ukuran metadata tidak boleh melebihi 4 KB.
multiaddresses	string[]	Tidak	Hint swarm-connect opsional. Hingga 5 multiaddress libp2p milik peer yang menyimpan CID tersebut. Kluster kami menjalankan swarm connect terhadap masing-masing secara paralel sebelum pinning, sehingga konten pada peer privat / non-DHT dapat dijangkau tanpa menunggu penemuan DHT. Best-effort — koneksi yang gagal tidak menggagalkan pin. Lihat Pinning dari node privat.

Contoh permintaan

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

Respons 202 Accepted

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

Untuk DAG besar (>500 blok atau >50 MB), respons menyertakan 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 dari node privat

Jika CID yang ingin Anda sematkan berada pada peer yang tidak berpartisipasi dalam DHT publik — node staging privat, mesin self-hosted di VPN, atau workstation di belakang NAT — alur pin default tidak akan menemukannya. Meneruskan satu atau lebih multiaddresses memberitahu kluster kami persis di mana harus mencari.

Kami menjalankan ipfs swarm connect <multiaddr> untuk setiap hint secara paralel sebelum pin berjalan. Jika koneksi berhasil, pengambilan DAG untuk pin dapat berkomunikasi langsung dengan peer Anda alih-alih mencari melalui DHT. Jika gagal, pin tetap berlanjut terhadap jaringan publik (semantik best-effort).

Contoh: sematkan dari peer tertentu

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

Respons menyertakan status per hint

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

Bentuk multiaddress yang diterima

Bentuk umum didukung: transport /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokol /tcp atau /udp; upgrade opsional /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiaddress harus diakhiri dengan /p2p/<peerId>. Batas: hingga 5 hint per pin.

Mendapatkan multiaddress node Anda

Pada peer tempat Anda ingin menyematkan, jalankan ipfs id dan salin salah satu entri Addresses yang diakhiri dengan /p2p/<PeerID>. Utamakan alamat publik yang dapat dirutekan (/ip4/YOUR_PUBLIC_IP/…) atau berbasis DNS (/dnsaddr/your.domain/…) agar kluster kami dapat menjangkau peer tersebut dari AWS.

Menyematkan direktori yang sangat besar

POST /pin ditujukan untuk konten yang sudah berada di jaringan IPFS — kluster mengambil DAG blok demi blok dari peer, yang dapat memakan waktu beberapa menit untuk direktori dengan 1.000+ file. Selama jendela pengambilan tersebut, beberapa file anak mungkin belum tersedia secara lokal dan permintaan gateway ke file tersebut dapat timeout. Setelah status induk berubah menjadi pinned, setiap anak tersedia secara lokal dan dapat diakses melalui gateway Anda.

Jika Anda memiliki file secara lokal (bukan hanya CID), utamakan impor CAR untuk koleksi NFT atau dataset besar — ini mengunggah seluruh DAG ke IPFS Ninja dalam satu permintaan atomik, sehingga tidak ada jendela pengambilan atau status pin-parsial. Buat CAR dengan:

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

Kemudian impor melalui POST /upload/new dengan car: true.

TIP

Pinning bersifat asinkron. Respons dikembalikan segera dengan status pinning. Poll endpoint status untuk memeriksa kapan pinning selesai.

Periksa Status Pin

GET /pin/:cid

Parameter	Tipe	Wajib	Deskripsi
cid	string	Ya	CID yang Anda periksa.

Respons 200 OK

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

Nilai status

Status	Arti
pinning	Konten sedang diambil dari jaringan IPFS. Poll lagi dalam beberapa detik.
pinned	Konten telah disematkan dan tersedia melalui akun dan gateway Anda.
failed	Konten tidak dapat ditemukan di jaringan IPFS. CID mungkin tidak valid atau konten sudah tidak tersedia lagi.

Cara kerja pinning

1. Anda mengirimkan CID melalui POST /pin
2. Kluster IPFS kami mencari node di jaringan yang memiliki konten tersebut
3. Kluster mengunduh dan menyematkan konten secara lokal
4. Setelah disematkan, file muncul di daftar file Anda dan dapat diakses melalui gateway
5. Penggunaan penyimpanan dicatat saat pinning selesai

WARNING

Waktu pinning bergantung pada ukuran file dan ketersediaan jaringan. File kecil biasanya disematkan dalam hitungan detik. File besar atau konten yang jarang disematkan mungkin memerlukan beberapa menit.

Penyimpanan

Konten yang disematkan diperhitungkan dalam batas penyimpanan paket Anda. Ukuran file dicatat saat pinning selesai. Jika Anda mendekati batas penyimpanan, Anda dapat membebaskan ruang dengan menghapus file yang tidak digunakan atau meningkatkan paket untuk kapasitas lebih besar.