Pin API

January 23, 2020 ยท View on GitHub

pin.add

Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able).

ipfs.pin.add(hash, [options])

Where:

  • hash is an IPFS multihash.
  • options is an object that can contain the following keys
    • recursive (boolean) - Recursively pin the object linked. Type: bool. Default: true
    • timeout (number|string) - Throw an error if the request does not complete within the specified milliseconds timeout. If timeout is a string, the value is parsed as a human readable duration. There is no timeout by default.

Returns

TypeDescription
Promise<{ cid: CID }>An array of objects that represent the files that were pinned

an array of objects is returned, each of the form:

{
  cid: CID('QmHash')
}

Example:

const pinset = await ipfs.pin.add('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')
console.log(pinset)
// Logs:
// [ { cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u') } ]

A great source of examples can be found in the tests for this API.

pin.ls

List all the objects pinned to local storage or under a specific hash.

ipfs.pin.ls([cid], [options])

Where:

  • cid - a CID instance or CID as a string or an array of CIDs.
  • options - is an object that can contain the following keys:
    • type - filter by this type of pin ("recursive", "direct" or "indirect")

Returns

TypeDescription
AsyncIterable<{ cid: CID, type: string }>An async iterable that yields currently pinned objects with cid and type properties. cid is a CID of the pinned node, type is the pin type ("recursive", "direct" or "indirect")

Example:

for await (const { cid, type } of ipfs.pin.ls()) {
  console.log({ cid, type })
}
// { cid: CID(Qmc5XkteJdb337s7VwFBAGtiaoj2QCEzyxtNRy3iMudc3E), type: 'recursive' }
// { cid: CID(QmZbj5ruYneZb8FuR9wnLqJCpCXMQudhSdWhdhp5U1oPWJ), type: 'indirect' }
// { cid: CID(QmSo73bmN47gBxMNqbdV6rZ4KJiqaArqJ1nu5TvFhqqj1R), type: 'indirect' }

A great source of examples can be found in the tests for this API.

pin.rm

Remove a hash from the pinset

ipfs.pin.rm(hash, [options])

Where:

  • hash is a multihash.
  • options is an object that can contain the following keys
    • 'recursive' - Recursively unpin the object linked. Type: bool. Default: true

Returns

TypeDescription
Promise<{ cid: CID }>An array of unpinned objects

Example:

const pinset = await ipfs.pin.rm('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')
console.log(pinset)
// prints the hashes that were unpinned
// [ { cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u') } ]

A great source of examples can be found in the tests for this API.