HomeLabsIPFS PinningAPI/CLI
Pinning operations with Scaleway CLI
Jump toUpdate content

Pinning operations with Scaleway CLI

Reviewed on 25 May 2023Published 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.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

  • you are the Owner of the Scaleway Organization in which the actions will be carried out, or
  • you are an IAM user of the Organization, with a policy granting you the necessary permission sets
Requirements:

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.

  1. Export the following environment variable to enable the IPFS command in the Scaleway CLI:

    export SCW_ENABLE_LABS=true
  2. 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
    ParameterDescription
    volume-idID of the volume you wish to pin your content to. You can find it using either the Scaleway console or the Scaleway API/CLI
    cidCID of the content you wish to pin.
    nameCreate 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

ParameterDescription
$SECRET_KEYThe secret part of your API key
$REGION_IDCreate a volume in this given region. Possible values are fr-par, pl-waw and nl-ams. Default value is fr-par.
$PROJECT_IDID 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
nameCreate a volume with this given name.