Understanding IPFS Pinning Services

Understanding IPFS Pinning Services

An IPFS pinning service runs IPFS nodes for you and keeps your content pinned on them. Pinned data is exempt from garbage collection. Your files stay retrievable by CID while your own computer is offline, for as long as the pin and your account stay active.

Updated Nov 5, 2026: rewritten against the current IPFS docs. We removed the old "permanent storage" claims and added the Pinning Service API, a checklist for choosing a service, the limits of pinning, and how AIOZ Pin handles pins.

Illustration of a globe surrounded by a ring of servers and network lines, representing a decentralized network

What does pinning mean in IPFS?

IPFS nodes cache the blocks they fetch so they can serve them to other peers. That cache is not storage you can count on. Disk space is finite, and garbage collection deletes blocks the node no longer seems to need. A pin marks a CID as something the node must keep, so garbage collection skips it.

The IPFS pinning guide describes three kinds of pins. A recursive pin keeps a block and every block below it in the DAG. A direct pin keeps one block, and an indirect pin is what the children of a recursive pin become. In Kubo, ipfs add pins what you add recursively by default. Files you keep in the Mutable File System (MFS) are also protected from garbage collection without an explicit pin.

Kubo collects garbage when you run ipfs repo gc, or on a schedule if you start the daemon with --enable-gc. The Kubo config docs set that schedule to one hour by default, plus a run at 90% of Datastore.StorageMax (10GB by default). Automatic collection is off unless you enable it, but you have no say over nodes other people run.

Unpinning only makes the blocks on that one node eligible for removal, which is narrower than many people expect. If another node still pins the same CID, the content stays reachable. We cover the details in what unpinning does to a file on IPFS.

Local pinning vs remote pinning

Local pinning keeps data on a node you run. It costs nothing extra, but the content is only as available as that machine. If your laptop goes to sleep, peers that ask for your CID get no answer from you.

Remote pinning keeps the data on nodes that someone else operates. The IPFS docs on remote pinning list when that helps. Your node isn't always online, you need a backup of its files, or you are short on disk space. A pinning service is the managed, paid form of remote pinning, and you can also run your own because the API standard below is open.

How does an IPFS pinning service work?

A pinning service runs a set of IPFS nodes behind an API, a dashboard or both. You can upload a file, and the service adds it to IPFS, pins it and returns the CID. Or you can send a CID that already exists on the network, and the service fetches the blocks from whoever provides them before pinning.

Pinning by CID takes longer and can fail, because the service has to find a provider for every block in the DAG, connect to it and download the data. If the only node holding your content is offline, the request waits and may end as failed. Our guide to pinning an existing CID without re-uploading walks through that flow.

Once the blocks are pinned, the service announces the CID to the network. The IPFS lifecycle docs name the two routing systems used for this on IPFS Mainnet: the DHT and IPNI. After that, anyone with the CID can retrieve the content through a gateway URL or from an IPFS node.

A service can also keep the same pin on several of its nodes. IPFS Cluster, an open-source tool, does this by allocating, replicating and tracking a pinset across many IPFS daemons. Our explainer on how multi-node pinning services replicate content covers that pattern, though each service decides how many copies it keeps.

Diagram: unpinned IPFS blocks are removed by garbage collection, while a pinning service pins the DAG, announces the CID and serves it by CID
What happens to a CID with and without a pinning service. Sources: docs.ipfs.tech, the IPFS Pinning Service API spec and Kubo config docs.

The Pinning Service API standard

Besides each vendor's native API, there is a shared one. The IPFS Pinning Service API is an OpenAPI specification, version 1.0.0, that any service can implement. A client written against it works with every compatible service, so you don't have to learn each vendor's endpoints.

In the spec, you send a Pin object with a cid and an optional name, origins and meta. The service answers with a PinStatus that carries a requestid, a status and a list of delegates. The status moves from queued to pinning to pinned, or ends as failed. Origins are addresses of nodes that already hold your data, and delegates are the service's own nodes that will receive it.

Kubo 0.8 and later include a client. ipfs pin remote service add registers a service, and ipfs pin remote add pins a CID there by name. IPFS Desktop and the IPFS Web UI support compatible services too. The spec is now frozen and its repository is archived, so it won't gain new features, but Kubo still supports it. For more on the requests and fields, read what the Pinning Service API is and why it matters.

How do you choose an IPFS pinning service?

The IPFS docs warn that there is no guarantee a third-party pinning service will keep running. They advise you to research one before you trust it with your data, and these five checks cover most of that research.

Redundancy

Ask how many nodes hold each pin and whether they sit in different places. A pin on one node is one disk failure away from a re-upload.

Gateways

If your users load content in a browser, they will most likely go through an HTTP gateway. Check whether you get a dedicated gateway, what rate limits apply, which file types it serves, and whether it supports a custom domain. Free public gateways tend to be rate-limited, and ours is meant for testing only.

API and tooling

Look for Pinning Service API support, pin by CID, a way to list and filter your pins, SDKs for your language and published rate limits. Pin status should be easy to read, because a large directory can sit in the pinning state for a long time.

Pricing model

Services charge for data stored per month, bandwidth served, number of pinned files, or a flat plan with quotas. Work out the cost from your total size, monthly traffic and file count. On a free tier, read what happens to your pins and gateway when the balance or quota runs out.

Exit path

CIDs are portable, so to move you pin your CIDs on the new service by CID, wait for each to show pinned, and only then cancel the old one. Pinning by CID keeps every CID the same, while uploading again can change them, because the docs say identical content gives the same CID only with the same settings. You need a full export of your CID list, so check for a list endpoint first.

What pinning does not do

Pinning is not permanent storage. The IPFS persistence docs state that IPFS guarantees content on the network is discoverable, but not that it stays available. A pin lasts as long as someone pays for it or keeps the node running, and if that one sponsor stops, the content may be lost. For longer guarantees, the same docs point to Filecoin storage deals, where a provider agrees to keep the data for a set term and is checked periodically.

Pins are also public. The IPFS privacy docs describe IPFS as a public network where nodes advertise the CIDs they hold through publicly viewable DHTs. Anyone with a CID can fetch the content, so encrypt sensitive files before you pin them.

How AIOZ Pin handles pinning

AIOZ Pin is our IPFS pinning service, the top layer of AIOZ DePIN. The pinning API gives you two native ways in: POST /api/pinning uploads and pins a file or directory, and POST /api/pinning/pinByHash pins a CID that already exists. Both take a pinning API key and secret key in the request headers.

AIOZ Pin also implements the standard API at https://api.aiozpin.network/api/psa/. Its Pinning Services API page shows how to get a JWT through an email login code and register the endpoint with ipfs pin remote service add. Here is the docs' request for pinning an existing CID through the native API (not run here, copied from the AIOZ Pin docs):

curl --location --request POST 'https://api.aiozpin.network/api/pinning/pinByHash' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
"hash_to_pin": "Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs",
"metadata": {
    "name": "name-ipfs-hash"
}
}'

You can check a pin with GET /api/pinning/{pinId} or the Node.js SDK's getPinByID. The status reads Pinning, Pinned or Failed. The upload status guide warns that a very large upload, such as a 10,000-item NFT drop, may show Pinning indefinitely because the graph is too large to validate right away. To remove a pin, you call DELETE /api/pinning/unpin/{pinId}.

The public gateway is for testing and low volume. The AIOZ Pin limits page caps it at 15 requests per minute per CID and 200 per minute per IP. Premium gateways have no predefined rate limits. Free-plan accounts get a limited premium gateway that serves single files such as images, video and audio, but not HTML or scripts. If your balance runs out, the premium gateway turns off and your pinned files stay reachable through the public gateway.

Billing is daily, from an AIOZ token wallet, and as of November 2026 the payment docs list $20 per TB per month for storage and $20 per TB of bandwidth. The first 40,000 pinned files are free, then $0.10 per 1,000 extra. The API allows 180 requests per minute, and listing pins through the PSA endpoint allows 60. For the full product picture, see how AIOZ Pin works, from pinning to gateways and NFT tools.

FAQ

Is an IPFS pinning service the same as permanent storage?

No. A pin keeps data available while the pin exists and the service keeps running. If the pin is removed or the account lapses, the blocks can be garbage-collected, so keep your own copy of anything you can't afford to lose.

Is there a free IPFS pinning service?

Some services give new users a free storage allowance, as the IPFS docs note. Free tiers usually limit storage, file count, bandwidth or gateway features. On AIOZ Pin, the first 40,000 pinned files carry no file fee, while storage and bandwidth are billed daily.

What happens to my file if I unpin it?

On that service, its blocks become candidates for garbage collection and are removed at some point. Copies pinned or cached on other nodes are not affected, so the CID may still resolve.

Can I pin the same CID on two pinning services?

Yes. Any service that supports pin by CID can pin a CID another service already provides, and using two providers removes a single point of failure. You pay each provider for its copy.

Do I need to run my own IPFS node to use a pinning service?

No. You can upload through a service's dashboard or API without running a node. A local Kubo node helps if you want to compute CIDs yourself or manage pins with ipfs pin remote.

Why does my pin stay in the pinning state?

The service is still finding providers or downloading blocks. If no node that holds the data is online, the request waits and may fail, so keep your source node online until the status shows pinned.

AIOZ Network logo over a green circuit board with a processor chip

About the AIOZ Network

AIOZ Network is a DePIN for Web3 AI, Storage and Streaming.

AIOZ empowers a fast, secure and decentralized future.

Powered by a global network of DePINs, AIOZ rewards you for sharing your computational resources for storing, transcoding, and streaming digital media content and powering decentralized AI computation.

Find Us

Website | AIOZ Block Explorer | Twitter | Telegram