Pinning

I-pin ang umiiral na IPFS content sa iyong account. Kapag nag-pin ka ng CID, kinukuha ng aming cluster ang nilalaman mula sa IPFS network at pinapanatili itong permanenteng available.

Pin gamit ang CID

POST /pin

Parameter	Uri	Kinakailangan	Paglalarawan
cid	string	Oo	IPFS content identifier. Tinatanggap ang anumang anyo: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, at iba pang codec).
description	string	Hindi	Maikling paglalarawan para sa iyong reference.
metadata	object	Hindi	Custom key-value pairs na ila-attach sa pin. Max 10 key. Ang mga key ay dapat alphanumeric o underscore, 1-64 character. Ang mga value ay dapat string, max 256 character bawat isa. Ang kabuuang laki ng metadata ay hindi dapat lumagpas sa 4 KB.
multiaddresses	string[]	Hindi	Opsyonal na swarm-connect hints. Hanggang 5 libp2p multiaddress ng mga peer na nag-host ng CID. Pinapatakbo ng aming cluster ang swarm connect laban sa bawat isa nang parallel bago ang pin, kaya ang nilalaman sa private / non-DHT na mga peer ay maaabot nang hindi na kailangang maghintay sa DHT discovery. Best-effort — ang bigong connect ay hindi nagpapabigo sa pin. Tingnan ang Pag-pin mula sa private node.

Halimbawang request

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

Response 202 Accepted

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

Para sa malalaking DAG (>500 blocks o >50 MB), kasama sa response ang async: true flag:

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

Pag-pin mula sa private node

Kung ang CID na gusto mong i-pin ay nasa isang peer na hindi kasali sa pampublikong DHT — isang private staging node, isang self-hosted na makina sa VPN, o isang workstation sa likod ng NAT — hindi ito mahahanap ng default na pin flow. Ang pagpasa ng isa o higit pang multiaddresses ay nagsasabi sa aming cluster kung saan eksaktong titingnan.

Pinapatakbo namin ang ipfs swarm connect <multiaddr> para sa bawat hint nang parallel bago tumakbo ang pin. Kung matagumpay ang connect, maaaring direktang makipag-usap ang DAG fetch ng pin sa iyong peer sa halip na maghanap sa buong DHT. Kung nabigo ito, magpapatuloy pa rin ang pin laban sa pampublikong network (best-effort semantics).

Halimbawa: mag-pin mula sa isang partikular na peer

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

Kasama sa response ang status ng bawat 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": { … }
}

Mga tinatanggap na anyo ng multiaddress

Sinusuportahan ang mga karaniwang anyo: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr na mga transport; /tcp o /udp na mga protocol; opsyonal na /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct na mga upgrade. Ang multiaddress ay dapat magtapos sa /p2p/<peerId>. Limitasyon: hanggang 5 hints bawat pin.

Pagkuha ng multiaddress ng iyong node

Sa peer na gusto mong pinagmulan ng pin, patakbuhin ang ipfs id at kopyahin ang alinman sa mga entry ng Addresses na nagtatapos sa /p2p/<PeerID>. Mas mainam ang mga pampublikong routable address (/ip4/YOUR_PUBLIC_IP/…) o mga DNS-based (/dnsaddr/your.domain/…) para maabot ng aming cluster ang peer mula sa AWS.

Pag-pin ng napakalalaking directory

Ang POST /pin ay para sa nilalaman na nasa IPFS network na — kinukuha ng cluster ang DAG block-by-block mula sa mga peer, na maaaring tumagal ng ilang minuto para sa mga directory na may 1,000+ na file. Sa panahon ng fetch window na iyon, maaaring hindi pa lokal na available ang ilang child file at maaaring mag-timeout ang mga gateway request sa mga ito. Kapag ang status ng parent ay naging pinned, lokal nang available ang bawat child at naa-access sa pamamagitan ng iyong gateway.

Kung nasa iyo na ang mga file nang lokal (sa halip na CID lamang), mas mainam ang CAR import para sa malalaking NFT collection o dataset — ini-upload nito ang buong DAG sa IPFS Ninja sa isang atomic request, kaya walang fetch window at walang partial-pin state. Gumawa ng CAR gamit ang:

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

Pagkatapos ay i-import ito sa pamamagitan ng POST /upload/new na may car: true.

TIP

Ang pinning ay asynchronous. Agad na nagbabalik ang response na may status na pinning. I-poll ang status endpoint para malaman kung tapos na.

Suriin ang Pin Status

GET /pin/:cid

Parameter	Uri	Kinakailangan	Paglalarawan
cid	string	Oo	Ang CID na sinusuri mo.

Response 200 OK

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

Mga Status value

Status	Kahulugan
pinning	Kinukuha ang nilalaman mula sa IPFS network. I-poll ulit sa ilang segundo.
pinned	Naka-pin na at available sa pamamagitan ng iyong account at gateway.
failed	Hindi nahanap ang nilalaman sa IPFS network. Maaaring invalid ang CID o hindi na available ang nilalaman.

Paano gumagana ang pinning

1. Isumite mo ang CID sa pamamagitan ng POST /pin
2. Hinahanap ng aming IPFS cluster ang network para sa mga node na may nilalaman
3. Dina-download at pina-pin ng cluster ang nilalaman nang lokal
4. Kapag na-pin na, lumalabas ang file sa iyong file list at naa-access sa pamamagitan ng gateway
5. Nire-record ang storage usage kapag natapos ang pinning

WARNING

Nakadepende ang oras ng pinning sa laki ng file at availability ng network. Karaniwang na-pin ang maliliit na file sa loob ng ilang segundo. Ang malalaking file o bihirang na-pin na nilalaman ay maaaring tumagal ng ilang minuto.

Storage

Ang naka-pin na nilalaman ay binibilang sa storage limit ng iyong plan. Nire-record ang laki ng file kapag natapos ang pinning. Kung malapit ka na sa iyong storage limit, maaari kang magpalaya ng espasyo sa pamamagitan ng pagtanggal ng mga hindi ginagamit na file o mag-upgrade para sa mas maraming kapasidad.