Pinning

How files persist on the IPFS network and why pinning matters.

The garbage collection problem

IPFS nodes have limited storage. To manage disk space, they periodically run garbage collection — a process that removes cached data that hasn't been explicitly marked as important. Without intervention, a file you uploaded could be cleared from the network within hours.

Pinning tells an IPFS node: "keep this file permanently — don't garbage-collect it." A pinned file stays on the node's storage indefinitely, ensuring it remains available on the network.

Local pinning vs. remote pinning

Local pinning means running your own IPFS node and pinning files to it. You're responsible for uptime, storage, and network connectivity. If your node goes offline, your files become unavailable.

Remote pinning (what IPFS.NINJA provides) means a managed service pins your files on infrastructure that's always online. You get the permanence of pinning without running your own node.

TIP

Every file uploaded through IPFS.NINJA is automatically pinned to our IPFS cluster. No additional steps needed — your files are persistent from the moment of upload.

What happens when you unpin

If you delete a file from your IPFS.NINJA account, we unpin it from our nodes. The file may still be accessible if:

• Other IPFS nodes have cached or pinned the same CID
• An IPFS gateway has the file in its cache
• Another user uploaded the same content (same CID = same file)

Over time, without any node pinning the CID, the file will be garbage-collected from the network entirely.

Pinning best practices

• Pin early — Upload and pin your content before referencing the CID in smart contracts, NFT metadata, or external systems.
• Don't rely on caching — IPFS gateway caches are temporary. Only pinned content is guaranteed to persist.
• Keep your account active — Files remain pinned as long as your IPFS.NINJA account is active, even on the free tier.

Pinning existing content

You don't have to upload a file through IPFS.NINJA to pin it. If content already exists on the IPFS network — uploaded by someone else, or by you through another service — you can pin it to your account by providing its CID.

When you pin an existing CID, our cluster:

1. Searches the IPFS network for nodes that have the content
2. Downloads the content from the nearest available node
3. Pins it locally on our infrastructure
4. Makes it accessible through your account and gateway

This is useful for:

• Preserving NFT assets — pin metadata and images from existing collections
• Backing up content — ensure important CIDs stay available even if the original pinner goes offline
• Migrating from another service — pin your existing CIDs without re-uploading the files

See the Pinning API docs for endpoint details.