Using the Filebase IPFS Pinning Service API

To fully benefit from storing data on the IPFS network, it’s vital to pin files and folders to assure their long-term storage on the network. If a file or folder isn’t pinned once it’s uploaded to IPFS, it’ll be removed during the next run of the automatic garbage collection process that’s used to maintain resources across the nodes on the network.

Once a file has been pinned, what if you want to change pinning providers? What if you pinned the file using a local IPFS node, but you don’t have plans to maintain that node long-term yet you want the content to persist long-term?

The IPFS Pinning Service API was developed for this exact purpose. The IPFS Pinning Service API is a standardized API for re-pinning existing IPFS CIDs. The API is often referred to as the IPFS "PSA" or “remote pinning”.

Platforms that develop compliance with the IPFS Pinning Service API standard often have varying levels of compliance. The IPFS development team tracks each provider's compliance to validate each implementation.

Filebase has implemented the IPFS Pinning Service API through our IPFS Re-Pinning service. By using this API, users can view pinned objects, add a new object to be pinned, or remove a pinned object.

Filebase is validated to be fully compliant with the IPFS PSA standard’s requirements. The official compliance report can be found here.

The IPFS API Endpoint

To interact with Filebase’s implementation of the IPFS Pinning Service API, the following API endpoint is used:

https://api.filebase.io/v1/ipfs

Authentication

To authenticate with the IPFS Pinning Service API, a token is required to be sent with each request in the HTTP headers, using the following format:

• Authorization: Bearer <access-token>

The access-token can be generated by navigating to the Filebase Access Keys page, then viewing the IPFS Pinning Service API Endpoint. Click the drop down menu for 'Choose Bucket to Generate Token', then choose the IPFS Filebase Bucket you want to use.

Then copy the generated Secret Access Token:

Payload

To interact with the IPFS Pinning Service API, you need to send a payload in the form of JSON to the API URL.

Adding a Pinned CID

The following is an example of a POST payload used to pin a CID to Filebase:

{
"cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
"name": "image3",
"meta": {
"key_name": "value_name"
}

In this example, the CID value is required, and other parameters are optional. A full list of the parameters for the POST payload can be found below:‍

The expected success response for this payload is a 202 Successful Response that will resemble the following:

 {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
        "name": "image3",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
  }

Listing Pins

To list all currently pinned CIDs, you can use a GET request path:

GET https://api.filebase.io/v1/ipfs/pins

This request doesn’t require any parameters but supports optional parameters that can be used to filter results. These parameters include CID, name, status, metadata, and others. The full list of supported parameters can be found here. If no parameters are used, all currently pinned CIDs are returned.

A successful response resembles the following:

{
  "count": 1,
  "results": [
    {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
        "name": "image3",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
      }
    }
  ]
}

Getting Pinned CID Information

To retrieve information about an existing pinned CID, a GET request path can be used:

https://api.filebase.io/v1/ipfs/pins/{requestid}

In this request, the parameter requestid is required. The request ID refers to the unique identifier of the pinning request, it does not refer to the CID itself.

A successful response for this request will resemble the following:

 {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
        "name": "image3",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
  }

Replacing an Existing Pinned CID

To replace an existing pinned object, a POST request can be used. This is a shortcut to removing the CID, then reuploading the CID with two separate API requests. This helps prevent unnecessary garbage collection of blocks that are present in the recursive request.

To replace an existing CID, use the following POST request path:

https://api.filebase.io/v1/ipfs/pins/{requestid}

In this request, the parameter requestid is required. The request ID refers to the unique identifier of the pinning request, it does not refer to the CID itself.

Additionally, the following JSON payload should be used:

{
  "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
  "name": "PreciousData.pdf",
  "origins": [
    "/ip4/203.0.113.142/tcp/4001/p2p/QmSourcePeerId",
    "/ip4/203.0.113.114/udp/4001/quic/p2p/QmSourcePeerId"
  ],
  "meta": {
    "app_id": "99986338-1113-4706-8302-4420da6158aa"
  }
}

In this example, the CID value is required, and other parameters are optional. A full list of the parameters for the POST payload can be found below:

A successful response for this request will resemble the following:

 {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
        "name": "image3",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
  }

Deleting Pinned CIDs

To remove a pinned object, a DEL request with the following path can be used:

https://api.filebase.io/v1/ipfs/pins/{requestid}

In this request, the parameter requestid is required. The request ID refers to the unique identifier of the pinning request, it does not refer to the CID itself.

A successful response to this request will return no result and the pinned CID will be removed.

For a full list of supported parameters and error responses for the IPFS Pinning Service API, check out our full documentation here.

You can sign up for a free Filebase account to get started with your IPFS journey today.

If you have any questions, please join our Discord server, or send us an email at hello@filebase.com.