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

For large DAGs (>500 blocks or >50 MB), the response includes an async: true flag:

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

Pinning very large directories

POST /pin is for content that already lives on the IPFS network — the cluster fetches the DAG block-by-block from peers, which can take several minutes for directories with 1,000+ files. During that fetch window, some child files may not yet be locally available and gateway requests to them may time out. Once the parent's status flips to pinned, every child is locally available and accessible via your gateway.

If you have the files locally (instead of just a CID), prefer CAR import for large NFT collections or datasets — it uploads the entire DAG to IPFS Ninja in one atomic request, so there's no fetch window and no partial-pin state. Create a CAR with:

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

Then import it via POST /upload/new with car: true.

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. If you approach your storage limit, you can free space by deleting unused files or upgrade for more capacity.