Pin Operations | IPFS

Two families: add/list/remove/update/verify manage pins on the connected Kubo daemon itself. remote* operations manage pins on an external Pinning Service API (PSA)-compliant provider that Kubo has been told about — a different concept from the cluster resource, which talks to a separate IPFS Cluster daemon.

add

Field	Type	Required	Default
`cid`	text	✓ Yes	—
`recursive`	bool	No	`true`
`pinName`	text	No	—

Missing cid → CFG_MISSING_CID. Response: { cid, recursive, pinName }.

list

Field	Type	Required	Default
`pinType`	select	No	`all` (`direct`/`indirect`/`recursive`/`all`)
`nameFilter`	text	No	—, exact match
`limit`	int	No	—

Response: array of { cid, type, name }, plus count.

limit is applied client-side. Kubo returns the full pin list; limit then truncates it after the fact rather than being sent to Kubo as a query parameter.

remove

Field	Type	Required	Default
`cid`	text	✓ Yes	—
`recursive`	bool	No	`true`

Missing cid → CFG_MISSING_CID. recursive must match the value the pin was originally added with. Response: { cid, recursive }.

update

Field	Type	Required	Default
`oldCid`	text	✓ Yes	—
`newCid`	text	✓ Yes	—
`unpin`	bool	No	`true`

Missing fields → CFG_MISSING_OLD_CID, then CFG_MISSING_NEW_CID. Requires oldCid already recursively pinned. Response: { oldCid, newCid, unpinned }.

verify

Field	Type	Required	Default
`verbose`	bool	No	`false`
`quiet`	bool	No	`true`

Response: { verified, count, badPins: [{ cid, reason }] }.

A failed verification is data, not an error. verified: false still routes to the success output port — it's a legitimate integrity-check result, not an execution failure.

remoteAdd

Field	Type	Required	Default
`cid`	text	✓ Yes	—
`remoteServiceName`	text	✓ Yes	—
`pinName`	text	No	—
`background`	bool	No	`false`

Missing fields → CFG_MISSING_CID, then CFG_MISSING_REMOTE_SERVICE. Blocks until a terminal pin status unless background=true. Response: { cid, remoteServiceName, pinName, remoteStatus }.

remoteList

Field	Type	Required	Default
`remoteServiceName`	text	✓ Yes	—
`nameFilter`	text	No	—, exact match
`cidFilter`	text	No	—, comma-separated CIDs
`statusFilter`	text	No	`pinned`, comma-separated statuses

Missing service → CFG_MISSING_REMOTE_SERVICE. Response: array of { cid, name, remoteStatus }, plus count.

remoteRemove

Field	Type	Required	Default
`remoteServiceName`	text	✓ Yes	—
`nameFilter`	text	No	—
`cidFilter`	text	No	—
`statusFilter`	text	No	`pinned`
`force`	bool	No	`false`

Missing service → CFG_MISSING_REMOTE_SERVICE. Kubo requires force=true when the filter matches more than one remote pin — the executor forwards the flag, Kubo enforces the safety rule. Response: { remoteServiceName }.

remoteServiceAdd

Field	Type	Required	Default
`remoteServiceName`	text	✓ Yes	—
`remoteServiceEndpoint`	text	✓ Yes	PSA-compliant base URL
`remoteServiceApiKey`	text (sensitive)	✓ Yes	—

Validated in order: CFG_MISSING_REMOTE_SERVICE → CFG_MISSING_REMOTE_ENDPOINT → CFG_MISSING_REMOTE_API_KEY. Response: { remoteServiceName, remoteServiceEndpoint } — remoteServiceApiKey is deliberately never included in the output.

remoteServiceList

Field	Type	Required	Default
`includeStats`	bool	No	`false`

Response: array of { name, endpoint, statStatus, queuedCount, pinningCount, pinnedCount, failedCount }, plus count. API keys are never present in the listing — Kubo stores them write-only.

remoteServiceRemove

Field	Type	Required
`remoteServiceName`	text	✓ Yes

Missing service → CFG_MISSING_REMOTE_SERVICE. Response: { remoteServiceName }. De-registers the service locally — it does not unpin content already sitting on the remote provider.