PIN.md

Pin API

• ipfs.pin.add(ipfsPath, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.addAll(source, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.ls([options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.rm(ipfsPath, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.rmAll(source, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.remote.service.add(name, options)
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.remote.service.ls([options])
  • Options
  • Returns
  • Example
• ipfs.pin.remote.service.rm(name, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.remote.add(cid, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pin.remote.ls(options)
  • Options
  • Returns
  • Example
• ipfs.pin.remote.rm(options)
  • Options
  • Returns
  • Example
• ipfs.pin.remote.rmAll(options)
  • Options
  • Returns
  • Example

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

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)

Parameters

Name	Type	Description
source	CID or string	A CID or IPFS Path to pin in your repo

Options

An optional object which may have the following keys:

Name	Type	Default	Description
recursive	boolean	true	Recursively pin all links contained by the object
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
CID	The CID that was pinned

Example

const cid of ipfs.pin.add(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))
console.log(cid)
// Logs:
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

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

ipfs.pin.addAll(source, [options])

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

Parameters

Name	Type	Description
source	AsyncIterable<{ cid: CID, path: string, recursive: boolean, comments: string }>	One or more CIDs or IPFS Paths to pin in your repo

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AsyncIterable<CID>	An async iterable that yields the CIDs that were pinned

Each yielded object has the form:

{
  cid: CID('QmHash')
}

Example

for await (const cid of ipfs.pin.addAll(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))) {
  console.log(cid)
}
// Logs:
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

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

ipfs.pin.ls([options])

List all the objects pinned to local storage

Parameters

Name	Type	Description

Options

An optional object which may have the following keys:

Name	Type	Default	Description
paths	CID or Array<CID> or string or Array<string>	CIDs or IPFS paths to search for in the pinset
type	string	undefined	Filter by this type of pin ("recursive", "direct" or "indirect")
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
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' }

for await (const { cid, type } of ipfs.pin.ls({
  paths: [ CID.parse('Qmc5..'), CID.parse('QmZb..'), CID.parse('QmSo..') ]
})) {
  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.

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

Unpin this block from your repo

Parameters

Name	Type	Description
ipfsPath	CID of string	Unpin this CID or IPFS Path

Options

An optional object which may have the following keys:

Name	Type	Default	Description
recursive	boolean	true	Recursively unpin the object linked
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
CID	The CIDs that was unpinned

Example

const cid of ipfs.pin.rm(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))
console.log(cid)
// prints the CID that was unpinned
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

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

ipfs.pin.rmAll(source, [options])

Unpin one or more blocks from your repo

Parameters

Name	Type	Description
source	CID, string or AsyncIterable<{ cid: CID, path: string, recursive: boolean }>	Unpin this CID

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AsyncIterable<CID>	An async iterable that yields the CIDs that were unpinned

Example

for await (const cid of ipfs.pin.rmAll(CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'))) {
  console.log(cid)
}
// prints the CIDs that were unpinned
// CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')

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

ipfs.pin.remote.service.add(name, options)

Registers remote pinning service with a given name. Errors if service with the given name is already registered.

Parameters

Name	Type	Description
name	string	Service name

Options

An object which must contain following fields:

Name	Type	Description
endpoint	string	Service endpoint URL
key	string	Service key

An object may have the following optional fields:

Name	Type	Default	Description
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise	Resolves if added successfully, or fails with error e.g. if service with such name is already registered

Example

await ipfs.pin.remote.service.add('pinata', {
  endpoint: new URL('https://api.pinata.cloud'),
  key: 'your-pinata-key'
})

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

ipfs.pin.remote.service.ls([options])

List registered remote pinning services.

Options

An object may have the following optional fields:

Name	Type	Default	Description
stat	boolean	false	If true will include service stats.
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<RemotePinService[]>	List of registered services

RemotePinService

Object contains following fields:

Name	Type	Description
service	string	Service name
endpoint	URL	Service endpoint URL
stat	Stat	Is included only when stat: true option was passed

Stat

If stats could not be fetched from service (e.g. endpoint was unreachable) object has following form:

Name	Type	Description
status	'invalid'	Service status

If stats were fetched from service successfully object has following form:

Name	Type	Description
status	'valid'	Service status
pinCount	PinCount	Pin counts

PinCount

Object has following fields:

Name	Type	Description
queued	number	Number of queued pins
pinning	number	Number of pins that are pinning
pinned	number	Number of pinned pins
failed	number	Number of faield pins

Example

await ipfs.pin.remote.service.ls()
// [{
//   service: 'pinata'
//   endpoint: new URL('https://api.pinata.cloud'),
// }]

await ipfs.pin.remote.service.ls({ stat: true })
// [{
//   service: 'pinata'
//   endpoint: new URL('https://api.pinata.cloud'),
//   stat: {
//      status: 'valid',
//      pinCount: {
//        queued: 0,
//        pinning: 0,
//        pinned: 1,
//        failed: 0,
//      }
//   }
// }]

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

ipfs.pin.remote.service.rm(name, [options])

Unregisteres remote pinning service with a given name (if service with such name is regisetered).

Parameters

Name	Type	Description
name	string	Service name

Options

An object may have the following optional fields:

Name	Type	Default	Description
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise	Resolves on completion

Example

await ipfs.pin.remote.service.rm('pinata')

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

ipfs.pin.remote.add(cid, [options])

Pin a content with a given CID to a remote pinning service

Parameters

Name	Type	Description
cid	CID	A CID to pin on a remote pinning service

Options

An object which must contain following fields:

Name	Type	Description
service	string	Name of the remote pinning service to use

An object may have the following optional fields:

Name	Type	Default	Description
name	string	undefined	Name for pinned data; can be used for lookups later (max 255 characters)
origins	Multiaddr[]	undefined	List of multiaddrs known to provide the data (max 20)
background	boolean	false	If true, will add to the queue on the remote service and return immediately. If false or omitted will wait until pinned on the remote service
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Pin	Pin Object

Pin

Object has following fields:

Type	Description
Status	Pin status
CID	CID of the content
`string	undefined`

Status

Status is one of the following string values:

'queued', 'pinning', 'pinned', 'failed'

Example

const cid = CID.parse('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u')
const pin = await ipfs.pin.remote.add(cid, {
  service: 'pinata',
  name: 'block-party'
})
console.log(pin)
// Logs:
// {
//    status: 'pinned',
//    cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'),
//    name: 'block-party'
// }

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

ipfs.pin.remote.ls(options)

Returns a list of matching pins on the remote pinning service.

Options

An object which must contain following fields:

Name	Type	Description
service	string	Name of the remote pinning service to use

An object may have the following optional fields:

Name	Type	Default	Description
cid	CID[]	undefined	If provided, will only include pin objects that have a CID from the given set.
name	string	undefined	If passed, will only include pin objects with names that have this name (case-sensitive, exact match).
status	Status[]	['pinned']	Return pin objects for pins that have one of the specified status values
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AysncIterable<Pin>	Pin Objects

Example

for await (const pin of ipfs.pin.remote.ls({ service: 'pinata' })) {
  console.log(pin)
}
// Logs:
// {
//    status: 'pinned',
//    cid: CID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u'),
//    name: 'block-party'
// }

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

ipfs.pin.remote.rm(options)

Removes a single matching pin object from the remote pinning service. Will error when multiple pins mtach, to remove all matches rmAll should be used instead.

Options

An object which must contain following fields:

Name	Type	Description
service	string	Name of the remote pinning service to use

An object may also contain following optional fields:

Name	Type	Default	Description
cid	CID[]	undefined	If provided, will match pin object(s) that have a CID from the given set.
name	string	undefined	If provided, will match pin object(s) with exact (case-sensitive) name.
status	Status[]	['pinned']	If provided, will match pin object(s) that have a status from the given set.
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise	Succeeds on completion

Example

await ipfs.pin.remote.rm({
  service: 'pinata',
  name: 'block-party'
})

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

ipfs.pin.remote.rmAll(options)

Removes all the matching pin objects from the remote pinning service.

Options

An object which must contain following fields:

Name	Type	Description
service	string	Name of the remote pinning service to use

An object may also contain following optional fields:

Name	Type	Default	Description
cid	CID[]	undefined	If provided, will match pin object(s) that have a CID from the given set.
name	string	undefined	If provided, will match pin object(s) with exact (case-sensitive) name.
status	Status[]	['pinned']	If provided, will match pin object(s) that have a status from the given set.
timeout	number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise	Succeeds on completion

Example

// Delete all non 'pinned' pins
await ipfs.pin.remote.rmAll({
  service: 'pinata',
  status: ['queued', 'pinning', 'failed']
})

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