Documentation

Content Pinning

Putting content on the IPFS network does not keep it there. Nodes cache what passes through them and garbage collect it later, so an unpinned CID is a link that works today and fails next month. Pinning is the instruction to keep specific content. It is the difference between published and temporarily cached.

For research data this matters. A CID cited in a paper has to resolve for as long as the paper is read, which is longer than any grant cycle.

Pinning is part of the write

There is no separate pin call. The API adds every object through the cluster's IPFS proxy with pin=true, so IPFS Cluster pins the envelope on every peer the moment POST /api/upload returns a CID.

Ekayana APIKubo RPC dialectIPFS_API_URLPrivate IPFS cluster, swarm key, no public DHTCluster proxyadd, pin/rm cluster wideadd, pin/rmIPFS Cluster peersone CRDT pinset, x3pin on every peercat, key/gen, name/publish, name/resolveKubo peer 0fronted by the proxyKubo peer 1replicaKubo peer 2replicaswarm keyGateways :8080internal, envelopes onlyEvery add is pinned on all peers. IPNS keys live on the fronted peer. Nothing dials the public network.
The private IPFS cluster behind the API. The API speaks the Kubo RPC dialect to one endpoint, the IPFS Cluster proxy. Inside a closed network marked by a swarm key, the proxy sends adds and pin removals to the cluster peers, which keep one shared pinset and pin every CID on all three Kubo peers, and forwards reads, key generation and IPNS publishing to the peer it fronts. The gateways stay inside the network. No peer dials the public DHT.
bash
# Uploading pins. Nothing else to do.
curl -X POST https://api.ekayana.io/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@dataset.csv"

GET /api/pins lists everything you currently hold.

bash
curl https://api.ekayana.io/api/pins -H "Authorization: Bearer $TOKEN"
# -> ["bafybeig...", "bafybeih..."]

Three kinds of object are pinned this way.

  • Sealed payloads, one CID per upload. Because each upload is encrypted under a fresh key, a CID has exactly one owner even when two people upload the same file. See File Storage.
  • Metadata documents for DIDs. Creating a DID or changing its metadata pins a new metadata.json and unpins the previous one. The DID document points at the current CID.
  • IPNS revisions. Publishing a new version through POST /api/ipns/update stores the new payload like any upload. Earlier versions stay pinned, so a citation of version 1 still resolves.

Unpinning follows the records

POST /api/delete with { "cid": "..." } removes your record and unpins the envelope on every peer once no record references the CID. Retiring a DID that was never anchored unpins its metadata document. A deactivated anchored DID has its document unpinned when the API reconciles the record with the chain. The pin list is for auditing what you store, and nothing in between needs maintenance.

What pinning does and does not promise

A pin keeps the bytes on every peer of the platform's private cluster. The peers share a swarm key and never join the public network, so nothing outside the cluster holds a copy unless the operator adds a peer or a reader fetches through the API. How many peers the cluster runs is the operator's deployment decision, and the API does not expose it. The CID guarantees verifiability. Any copy, from any peer, either matches its hash or is rejected.

Unpinning cannot recall an envelope a reader already fetched, so erasure leans on encryption rather than unpinning alone. A mutable reference on top of immutable pinned content is IPNS.