Pin by CID on IPFS Without Re-Uploading Your Files

Pin by CID on IPFS means asking a pinning service to fetch content that already exists on the network and keep it, so you never upload the file again. On AIOZ Pin you send the CID to the pinByHash endpoint, and the service retrieves the blocks itself.

TL;DR:

• Pin by CID sends a CID instead of a file, and the service has to find the blocks on the IPFS network before it can store and pin them
• On AIOZ Pin the call is POST /pinning/pinByHash with hash_to_pin in the body, and the docs also show a Pinning Service API route for ipfs pin remote
• The CID you pin is the CID you keep, while a re-upload can produce a different CID if the import settings differ
• If no node on the network can serve the blocks, the pin stays on Pinning and can end as Failed
• The pinByHash docs list no size limit, error codes, or timing, so check a new pin with the status endpoint instead of waiting

What Does Pin by CID Do?

A normal pin starts with a file: you upload it, the service splits it into blocks, computes the CID, and stores the blocks. Pin by CID skips the upload: you already have the CID, so you hand it over and the service goes looking for the content.

That moves the waiting elsewhere. The IPFS Pinning Service API spec says a pin in the pinning state typically means the data is being fetched from the IPFS network at large, which may take time, so the network matters more than your upload speed.

You would reach for it to move files from your own node to a provider, to keep the same CIDs when you switch providers, or to rely on a public dataset that someone else pinned.

How Do You Pin a CID on AIOZ Pin?

The AIOZ Pin API reference lists one endpoint for this: POST https://api.aiozpin.network/api/pinning/pinByHash. You send your two keys as the pinning_api_key and pinning_secret_key headers, plus a JSON body whose only required field is hash_to_pin. An optional metadata object can carry a name, and our API keys guide shows how to create the keys.

This TypeScript helper comes from the AIOZ Pin LLM docs, and I didn't run it because it needs a funded account.

const BASE = 'https://api.aiozpin.network/api'
const PIN_HEADERS = {
  'pinning_api_key': process.env.AIOZ_PIN_API_KEY!,
  'pinning_secret_key': process.env.AIOZ_PIN_SECRET_KEY!
}

async function pinByCid(cid: string, name?: string) {
  const res = await fetch(`${BASE}/pinning/pinByHash`, {
    method: 'POST',
    headers: { ...PIN_HEADERS, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      hash_to_pin: cid,
      metadata: name ? { name } : undefined
    })
  })
  return res.json()
}

const result = await pinByCid('Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs', 'my-pin')
// result.data.cid
// result.data.id

The response is wrapped in data, and the docs list id, cid, root_hash, pinned, is_pin_by_hash, is_dir, metadata, and status among its fields. The docs example shows is_pin_by_hash as true, which marks these pins apart from uploads. Keep the id too, since the status and unpin calls need it.

On 2026-10-16 I sent two requests to the endpoint without valid keys, to see what your client would get back:

# Without a trailing slash
curl -i -X POST https://api.aiozpin.network/api/pinning/pinByHash -d '{}'
# HTTP/2 307, location: /api/pinning/pinByHash/

# With the trailing slash and a made-up key
curl -X POST https://api.aiozpin.network/api/pinning/pinByHash/ \
  -H "pinning_api_key: invalid" -H "pinning_secret_key: invalid" \
  -d '{"hash_to_pin":"Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs"}'
# {"message":"API key not found","status":"fail"}  (HTTP 401)

The path redirects to the trailing-slash form with a 307, so a client that doesn't follow redirects sees an empty reply. A bad key returns a 401 straight away.

The Pinning Service API route

If you already run Kubo, you can skip the HTTP code. AIOZ Pin documents a Pinning Service API endpoint at https://api.aiozpin.network/api/psa/, and these commands come from the same docs. I didn't run them, because this machine has no IPFS binary.

ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_AUTH_JWT
ipfs pin remote add --service=pin --name=<human-readable-name> YOUR_CID
ipfs pin remote ls --service=pin --status=queued,pinning,failed

The JWT comes from an email login flow that the docs page describes, and our Pinning Service API explainer covers the standard itself.

Pin by CID Versus Re-Uploading

Pin by CID and a re-upload differ in two ways. The first is the CID: when you pin by CID, the CID you send is the one you keep. A re-upload chunks and hashes the file again, and different import settings can give the same bytes a different CID, as why IPFS used to give different CIDs for the same file explains. Any token URI or contract that points at the old CID only keeps working if the CID stays the same.

The second is the dependency: a re-upload needs only the file on your disk. Pin by CID works only while some node still holds the blocks and can be found, and that dependency is the first thing to check when a pin stalls.

Why Does a Pin by CID Stay on Pinning?

AIOZ Pin's docs define three statuses: Pinning (in the queue), Pinned (stored and pinned), and Failed (the upload failed or the graph of data is incomplete). Our post on what each pin status means walks through them. For a pin by CID, a long Pinning status usually points at one of these causes:

• No provider is online: the node that held the content went offline, or the original pin was removed and garbage collection deleted the blocks, as our unpinning article explains.
• Nobody announces the content: provider records expire and have to be renewed, so a node that stays offline too long stops being found, as the provider records article describes.
• The content is large: AIOZ Pin's docs warn that a very large upload, such as a 10K-file NFT drop, may show Pinning for a long time, and a large CID can plausibly behave the same way.
• The CID is wrong: a typo, or a CID that was never added anywhere, will never resolve.

Check the pin first and the content second. For the pin, call GET /pinning/{pinId} and read the status and pinned fields. For the content, run your CID through the IPFS retrieval checker, which reports whether any provider can serve it. If you control the original node, bring it back online. The steps in IPFS gateway not working apply here too, since a missing provider causes both symptoms.

The AIOZ Pin docs state no timeout or retry policy for a stuck pin. If it stays on Pinning after you have confirmed the content is reachable, contact the team with the pin ID and the CID.

How Other Pinning Services Handle It

Pinata's pin-by-CID endpoint accepts up to five hostNodes, which are multiaddresses of nodes that already store the content, and its docs say only such nodes can serve as hosts. The Pinning Service API spec has a similar idea in an optional origins list of up to 20 multiaddresses. The AIOZ Pin pinByHash docs list neither field, only hash_to_pin and metadata, so the service has to find the content on its own.

The spec also returns a new requestid each time you pin the same CID and describes a replace call. The AIOZ Pin docs I read don't say whether pinByHash follows either rule, so test before you build on them.

Checking and Managing the Pin

Fetch the CID through a gateway to confirm it loads, within the gateway rate limits. List your pins with GET /pinning/pins/ and filter on pinned, and remove one with DELETE /pinning/unpin/{pinId}.

Anyone who has the CID can fetch the content from the public network, so only pin by CID what you are happy to share. Privacy on IPFS explains why encryption has to happen before the data goes in. The pinByHash docs don't say how this content is billed, so read the pricing breakdown and confirm with the team before you move a large collection.

A super intelligence assistant can run the same operation through the pin-by-cid tool on the AIOZ Pin MCP server, which our MCP setup guide covers.

Frequently Asked Questions

Can I pin a CID I did not upload?

Yes. Pin by CID takes any CID the network can serve, so you only need to be able to reach the content.

Does the CID change when I pin by CID?

No. The service stores the blocks under the CID you sent, so the same CID resolves afterwards.

How long does a pin by CID take?

The AIOZ Pin docs give no time, and the spec only says fetching from the network may take time, depending on the number of blocks and how easy they are to find.

What happens if nobody has the content?

The pin stays on Pinning and can end as Failed. The service cannot create blocks that no node holds, so bring a node that has them back online.

Do I need an IPFS node to pin by CID on AIOZ Pin?

No. The HTTP call works with plain fetch or curl, and you only need Kubo if you prefer the ipfs pin remote commands.

Related Reading

• IPFS Pin Stuck on Pinning? What Each Pin Status Means - reading a pin's real state
• IPFS Pinning Service API: What It Is, Why It Matters - the standard behind ipfs pin remote
• Why IPFS Used to Give You Different CIDs for the Same File - why a re-upload can change the CID
• How Multi-Node Pinning Services Replicate Content - what happens after the pin lands
• IPFS Gateway Not Working? Diagnose It in This Order - when the content will not load

References

• AIOZ Pin Docs: Pin by CID
• AIOZ Pin Docs: LLM Docs, pinning section
• AIOZ Pin Docs: Pinning Services API
• IPFS Pinning Service API specification
• Pinata Docs: Pin By CID
• IPFS Retrieval Checker