REST API Reference

IPFS Cluster peers include an API component which provides HTTP-based access to the peer’s functionality. The API attempts to be REST-ful in form and behaviour. It is enabled by default, but it can be disabled by removing its section from the service.json configuration file.

We do not mantain ad-hoc API documentation, as it gets easily out of date or, at worst, is innacurate or buggy. Instead, we provide an easy way to find how to do what you need to do by using the ipfs-cluster-ctl command.

Running ipfs-cluster-service --enc=json --debug <command> will print information about the endpoint, the query options, the request body and raw responses for that command. Use it on a test cluster!

ipfs-cluster-ctl is an HTTP API client to the REST API endpoint with full feature-parity that always works with the HTTP API as offered by a cluster peer on the same version. Anything that ipfs-cluster-ctl can do is supported by the REST API. The command flags usually control different request options.

As additional resources:

The above should be enough to find out about the existing endpoints, their methods and current supported options.

As a final tip, this table provides a quick summary of methods available.

Method Endpoint Comment
GET /id Cluster peer information
GET /version Cluster version
GET /peers Cluster peers
DELETE /peers/{peerID} Remove a peer
POST /add Add content to the cluster
GET /allocations List of pins and their allocations (pinset)
GET /allocations/{cid} Show a single pin and its allocations (from the pinset)
GET /pins Local status of all tracked CIDs
POST /pins/sync Sync local status from IPFS
GET /pins/{cid} Local status of single CID
POST /pins/{cid} Pin a CID
POST /pins/{ipfs\|ipns\|ipld}/<path> Pin using an IPFS path
DELETE /pins/{cid} Unpin a CID
DELETE /pins/{ipfs\|ipns\|ipld}/<path> Unpin using an IPFS path
POST /pins/{cid}/sync Sync a CID
POST /pins/{cid}/recover Recover a CID
POST /pins/recover Recover all pins in the receiving Cluster peer
GET /health/graph Get connection graph