Pinning

Pin existing IPFS content to your account. When you pin a CID, our cluster fetches the content from the IPFS network and keeps it permanently available.

Pin by CID

POST /pin

Parameter	Type	Required	Description
cid	string	Yes	IPFS content identifier (starts with Qm or bafy).
description	string	No	Short description for your reference.
metadata	object	No	Custom key-value pairs to attach to the pin. Max 10 keys. Keys must be alphanumeric or underscore, 1-64 characters. Values must be strings, max 256 characters each. Total metadata size must not exceed 4 KB.

Example 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": "QmXk7VRz4qoG5Dg8sFL4bYWHpKe4F",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Response 202 Accepted

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

TIP

Pinning is asynchronous. The response returns immediately with status pinning. Poll the status endpoint to check when pinning completes.

Check Pin Status

GET /pin/:cid

Parameter	Type	Required	Description
cid	string	Yes	The CID you're checking.

Response 200 OK

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

Status values

Status	Meaning
pinning	Content is being fetched from the IPFS network. Poll again in a few seconds.
pinned	Content is pinned and available through your account and gateway.
failed	Content could not be found on the IPFS network. The CID may be invalid or the content is no longer available.

How pinning works

1. You submit a CID via POST /pin
2. Our IPFS cluster searches the network for nodes that have the content
3. The cluster downloads and pins the content locally
4. Once pinned, the file appears in your file list and is accessible via the gateway
5. Storage usage is recorded when pinning completes

WARNING

Pinning time depends on file size and network availability. Small files typically pin in seconds. Large files or rarely-pinned content may take minutes.

Storage

Pinned content counts toward your plan's storage limit. The file size is recorded when pinning completes — you can initiate a pin even if your storage is near the limit, but further uploads will be blocked if the pin causes you to exceed it.