Vastzetten

Zet bestaande IPFS-content vast op je account. Wanneer je een CID vastzet, haalt ons cluster de content op uit het IPFS-netwerk en houdt deze permanent beschikbaar.

CID vastzetten

POST /pin

Parameter	Type	Vereist	Beschrijving
cid	string	Ja	IPFS-content-identifier. Elke vorm wordt geaccepteerd: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, en andere codecs).
description	string	Nee	Korte beschrijving voor eigen referentie.
metadata	object	Nee	Aangepaste sleutel-waardeparen om aan de pin te koppelen. Max. 10 sleutels. Sleutels moeten alfanumeriek zijn of underscores bevatten, 1-64 tekens. Waarden moeten strings zijn, max. 256 tekens elk. Totale metadatagrootte mag niet groter zijn dan 4 KB.
multiaddresses	string[]	Nee	Optionele swarm-connect-hints. Tot 5 libp2p-multiaddressen van peers die de CID hosten. Ons cluster voert swarm connect parallel uit tegen elke hint vóór het vastzetten, zodat content op private/non-DHT-peers bereikbaar is zonder te wachten op DHT-discovery. Best-effort — een mislukte connect laat de pin niet mislukken. Zie Vastzetten vanaf een private node.

Voorbeeldverzoek

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

Voor grote DAG's (>500 blokken of >50 MB) bevat de respons een async: true-vlag:

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

Vastzetten vanaf een private node

Als de CID die je wilt vastzetten leeft op een peer die niet deelneemt aan de publieke DHT — een private staging-node, een zelf-gehoste machine op een VPN, of een werkstation achter NAT — vindt de standaard vastzetflow deze niet. Door een of meer multiaddresses mee te geven, vertel je ons cluster precies waar te zoeken.

We voeren ipfs swarm connect <multiaddr> uit voor elke hint, parallel, vóór het vastzetten. Als de connect slaagt, kan de DAG-fetch van de pin rechtstreeks met je peer praten in plaats van te zoeken via de DHT. Als het mislukt, gaat de pin toch door tegen het publieke netwerk (best-effort-semantiek).

Voorbeeld: vastzetten vanaf een specifieke 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"
    ]
  }'

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

Geaccepteerde multiaddress-vormen

Veelvoorkomende vormen worden ondersteund: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr-transports; /tcp- of /udp-protocollen; optionele /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct-upgrades. Het multiaddress moet eindigen op /p2p/<peerId>. Limiet: tot 5 hints per pin.

Het multiaddress van je node opvragen

Voer op de peer waarvan je wilt vastzetten ipfs id uit en kopieer een van de Addresses-items dat eindigt op /p2p/<PeerID>. Geef de voorkeur aan publiek routeerbare adressen (/ip4/YOUR_PUBLIC_IP/…) of DNS-gebaseerde adressen (/dnsaddr/your.domain/…), zodat ons cluster de peer vanaf AWS kan bereiken.

Zeer grote directory's vastzetten

POST /pin is bedoeld voor content die al op het IPFS-netwerk leeft — het cluster haalt de DAG blok voor blok op bij peers, wat voor directory's met 1.000+ bestanden meerdere minuten kan duren. Tijdens dat ophaalvenster zijn sommige onderliggende bestanden mogelijk nog niet lokaal beschikbaar en kunnen gateway-verzoeken ernaar time-outen. Zodra de status van de parent naar pinned springt, is elk onderliggend bestand lokaal beschikbaar en toegankelijk via je gateway.

Als je de bestanden lokaal hebt (in plaats van alleen een CID), geef dan de voorkeur aan CAR-import voor grote NFT-collecties of datasets — het uploadt de volledige DAG in één atomair verzoek naar IPFS Ninja, zodat er geen ophaalvenster en geen gedeeltelijke vastzetstatus is. Maak een CAR aan met:

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

Importeer het vervolgens via POST /upload/new met car: true.

TIP

Vastzetten is asynchroon. De respons keert onmiddellijk terug met status pinning. Poll het statusendpoint om te controleren wanneer het vastzetten voltooid is.

Vastzetstatus controleren

GET /pin/:cid

Parameter	Type	Vereist	Beschrijving
cid	string	Ja	De CID die je controleert.

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

Statuswaarden

Status	Betekenis
pinning	Content wordt opgehaald uit het IPFS-netwerk. Poll opnieuw na een paar seconden.
pinned	Content is vastgezet en beschikbaar via je account en gateway.
failed	Content kon niet worden gevonden op het IPFS-netwerk. De CID is mogelijk ongeldig of de content is niet meer beschikbaar.

Hoe vastzetten werkt

1. Je dient een CID in via POST /pin
2. Ons IPFS-cluster doorzoekt het netwerk naar nodes die de content hebben
3. Het cluster downloadt en zet de content lokaal vast
4. Zodra vastgezet, verschijnt het bestand in je bestandslijst en is het toegankelijk via de gateway
5. Opslaggebruik wordt geregistreerd zodra het vastzetten voltooid is

WARNING

De duur van het vastzetten hangt af van de bestandsgrootte en netwerkbeschikbaarheid. Kleine bestanden worden meestal in seconden vastgezet. Grote bestanden of zelden vastgezette content kan minuten duren.

Opslag

Vastgezette content telt mee voor de opslaglimiet van je plan. De bestandsgrootte wordt geregistreerd zodra het vastzetten voltooid is. Als je je opslaglimiet nadert, kun je ruimte vrijmaken door ongebruikte bestanden te verwijderen of upgraden voor meer capaciteit.