Pinning operations with Scaleway CLI

Reviewed on 27 November 2023 • Published on 30 May 2023

Created by Protocol Labs, InterPlanetary File System (IPFS) is a decentralized protocol used to store and share content.

Scaleway IPFS Pinning allows you to permanently store a copy of your data from the public IPFS network on a Scaleway-owned node, thus providing you with an added layer of performance in the region of your choice. That way, your data remains available and accessible, even when your local machine is offline.

With your content now available on both your local node and our resilient and reliable external nodes, you drastically minimize the risk of disruptions thanks to redundancy. You can also enhance your data storage efficiency by pinning your content to your Scaleway node, and then remove it from your local node.

In this page we show you how you can manage your pin operations via both the Scaleway Command Line Interface and Scaleway API.

Scaleway Command Line Interface overview

The Scaleway Command Line Interface (CLI) allows you to create and interact with your volumes & pins. You will be able to create, add/delete content and manage volumes.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console
Owner status or IAM permissions allowing you to perform actions in the intended Organization
A valid API key
Downloaded and installed the Scaleway CLI
Added data to your own local node and retrieved its CID

Pinning a content using its CID

This operation allows you to add content to a volume using its CID. The CID is an identifier that is made up of a string of characters pointing to a content.

Enter the following CLI command to pin content to a volume using its CID. Just make sure to replace the example values with your own, using the reference table below.

  scw ipfs pin create-by-cid volume-id=11111111-1111-1111-1111-111111111111 cid=Qmdi7ERksspfxWXfU8ATRUt7iCjZJbEbDrUoMDtjnbdTwo name=MyNewPinByCID

You should get a response like the following, providing details about the newly created pin.

  PinID           22222222-2222-2222-2222-222222222222
  Status          queued
  CreatedAt       now
  Cid.Cid         Qmdi7ERksspfxWXfU8ATRUt7iCjZJbEbDrUoMDtjnbdTwo
  Cid.Name        MyNewPinByCID

Parameter	Description
`volume-id`	ID of the volume you wish to pin your content to. You can find it using either the Scaleway console or the Scaleway API/CLI
`cid`	CID of the content you wish to pin.
`name`	Create a pin with this given name.

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below:

curl -X POST \
  -H "X-Auth-Token: $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "QmVSfc9XFKTjH1oi5nVAkkRuJgzzosoNCkMTcLah5ZinrW",
    "name": "name-of-my-pin",
    "volume_id": "11111111-1111-1111-1111-111111111111"
  }' \
  "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/pins/create-by-cid"

Pinning a content using its URL

This operation allows you to add content to a volume using its URL.

Run the following CLI command to pin a content using its URL. Just make sure to replace the example values with your own.

Important

The URL should point to content that is publicly accessible. This means it should not require any sort of authentication, login, or special network access to reach. If the content is unreachable, the request will return a failed status.
To avoid loss of access to the pinned content, the URL should be stable and persistent.
The server hosting the content must provide certain HTTP headers in its response, such as Content-Length (the size of the content) and Content-Type (the type of content, such as pngfor images or html for text). You can verify whether your content is missing either headers by running the curl -I command, followed by the URL of the content you are trying to pin.

  scw ipfs pin create-by-url volume-id=11111111-1111-1111-1111-111111111111 url=https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png name=MyNewPinByURL

You should get a response like the following, providing details about the newly created pin.

  PinID           22222222-2222-2222-2222-222222222222
  Status          pinned_ok
  CreatedAt       now
  Cid.Cid         -
  Cid.Name        MyNewPinByUrl

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below:

  curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "MyNewPinByURL",
      "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
      "volume_id": "11111111-1111-1111-1111-111111111111"
    }' \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/pins/create-by-url"

In both cases, a CID will be provided for your newly pinned content.

Retrieving information about a pin

This operation allows you to retrieve information about a given pin. You can either retrieve the CID associated with the pin ID or discover the CID behind the URL you provided.

Run the following command to retrieve information about a pin using CLI. Just make sure to replace the example values with your own:

  scw ipfs pin get pin-id=22222222-2222-2222-2222-222222222222 volume-id=11111111-1111-1111-1111-111111111111

You should get a response like the following, providing details about the pin:

Status          pinned
CreatedAt       5 minutes ago
Cid.Cid         QmaGNR5PedL8kiTUMtsPeFFodL9HnYBMuUqAEQrv6CQH4F
Cid.Name        value:"MyNewPinByCID"

Note

If the content is successfully pinned, the response will provide the CID of your content pointed by the URL. If it fails, no CID will be returned. You will still be able to retrieve the URL of the pinned content so you can retry.

Deleting a pin

This operation allows you to delete a given pin within a volume using its pin ID.

Run the following command to delete your pin using the CLI. Just make sure to replace the example values with your own.

Note

If the operation is successful, no output will be returned.

scw ipfs pin delete pin-id=22222222-2222-2222-2222-222222222222 volume-id=11111111-1111-1111-1111-111111111111

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below.

  curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SECRET_KEY" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/pins/<pin_id>?volumes/<volume-id>"

Listing pins

This operation allows you to list all pins from a given volume.

Run the following command to list all pins from a volume using the CLI. Make sure to replace the example value with your own:

scw ipfs pin list volume-id=11111111-1111-1111-1111-111111111111

You should get a response like the following, providing a list of all pins contained within a volume.

PIN ID                                STATUS  CREATED AT
11111111-1111-1111-1111-111111111111  failed  1 week ago
22222222-2222-2222-2222-222222222222  pinned  5 hours ago
33333333-3333-3333-3333-333333333333  pinned  4 hours ago
44444444-4444-4444-4444-444444444444  pinned  4 hours ago
55555555-5555-5555-5555-555555555555  pinned  2 hours ago
66666666-6666-6666-6666-666666666666  pinned  52 minutes ago

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below:

  curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/pins?order_by=created_at_asc&volume_id=11111111-1111-1111-1111-111111111111"

API configuration table

Parameter	Description
`$SECRET_KEY`	The secret part of your API key
`$REGION_ID`	Create a volume in this given region. Possible values are `fr-par`, `pl-waw` and `nl-ams`. Default value is `fr-par`.
`$PROJECT_ID`	ID of the Project you want to create your volume in. Your Project name can only contain alphanumeric characters, spaces, dots, and dashes. To find your Project ID, you can consult the Scaleway console
`name`	Create a volume with this given name.