In part 1 of this series, we took a tour of IPFS, explored its significance, and explained how it works. Now, we'll show you how to get started with Infura’s latest IPFS service, including a tutorial on how to use our IPFS API to pin and unpin your data across the IPFS network, as well as upload and access files.

So, how do you pin your data across the IPFS network via the Infura API? It’s much easier than you think! Once you have an Infura account (sign up for free here), you will be able to upload your files to IPFS and access that data.

Our new IPFS service is currently in Private Beta and the following guide requires you to have access to the Beta. To sign up, click here!

First, let’s get a file uploaded to IPFS.

There are many ways to upload a file to IPFS, including going directly through IPFS locally installed on your machine or through the Infura API. For this tutorial, let’s go through how to add, access, pin, and unpin your file using Python and the Infura API. There are a couple ways to do this - in this tutorial, we’ll go through the manual step-by-step, and will provide you with some resources for using the API wrapper for when your IPFS needs get more complicated.

The first thing you need to do is make sure Python is downloaded on your machine (you can download it here), as our script is written in Python. Next, you’ll want to ensure you import requests:

import requests

Next, we want to identify the file we are uploading, as well as its contents, to be uploaded to IPFS. For our example, let’s do something simple and easy to check to make sure it’s working correctly:

import requests
files = {
'file': '<full_path_to_your_file>'
}
response = requests.post('https://ipfs.infura.io:5001/api/v0/add', files=files, auth=(<project_id>,<project_secret>))
print(response.text)

When you run `python3 <filename.py>, you should get a printout of information for the file you just added to IPFS, like the below:

You can see that we have been given the hash that was generated so we can easily reference this file to see it later. Keep an eye on that one - we’re going to use it later!

Lastly, note that in the parameters, we have one called `pin`, which is defaulted to “true” - this means that when you upload your file, it does pin it by default so you don’t have to worry about it. Pinned data will be persisted by Infura until manually removed by the uploader whereas added files that are not pinned will not have any access guarantees.

If you want to go the API wrapper route, you have a few choices, all with great documentation that should help you get set up quickly. Again, these wrappers allow you to complete more complex tasks more efficiently than using the above code, once you’re at that point:

Now we'll show you how to actually access your file.

We’re going to try to access the file we just uploaded to IPFS, so to do that, we will need to declare our parameters, which in this case is the hash we found in the last step:

import requests
params = (
('arg','QmeY7x2rEzyUxh2uwhXMqgBnPvcxzgNcQcUQWJG94Hv9ki'),
)

This allows us to put the hash in the proper location in our request we’re about to call to download the file and its contents. The next bit of code is very similar to what we did to add our file to IPFS, but note that we are using cat instead of add in our response:

import requests
params = (
('arg','QmeY7x2rEzyUxh2uwhXMqgBnPvcxzgNcQcUQWJG94Hv9ki'),
)
response = requests.post('https://ipfs.infura.io:5001/api/v0/cat', params=params, auth=(<project_id>,<project_secret>))
print(response)

At this point, if we print out our response, we’ll see a 200 status code, which tells us that we have successfully completed the request and can access the data contained in the response we have:

<Response [200]>


If you want to read your file, you can simply `print(response.text)` instead of just `print(response)` and you’ll be able to see the text!

Congrats! You added this file to IPFS!

You’ve now successfully uploaded and downloaded/read a file through the Infura IPFS API - congrats!

What if I want to keep my current data I’ve uploaded to IPFS?

With this new update, content that was previously uploaded to the Infura IPFS services via the unauthenticated API will need to be migrated to the new version of the service. We will announce a deprecation period for any unauthenticated pins very soon but don’t worry, you'll have ample time to move your data over. Luckily, moving your data to the new IPFS version is very easy with our new pinning option! Here’s a great blog post on how to migrate your data.

How do I pin an object to IPFS now?

Pinning an object basically allows you to tell IPFS to always keep a given object. Pinning your file will prevent the IPFS service from garbage collecting your object, in other words, it’ll prevent your object from disappearing automatically via garbage collection until you explicitly unpin it. We’ll go through an example of each pinning command located in our documentation:

To pin your file, you will want to use the `pin_add` command. Note: if you upload your file with the above instructions, your file will be automatically pinned and you do not need to do this step!

import requests
params = (
(‘arg’, ‘QmeY7x2rEzyUxh2uwhXMqgBnPvcxzgNcQcUQWJG94Hv9ki’),
)
response = requests.post('https://ipfs.infura.io:5001/api/v0/pin/add', params=params, auth=(<project_id>,<project_secret>))
print(response.json())

When you run this, you should see the something like the following with your pin’s information:

{'Pins': ['QmeY7x2rEzyUxh2uwhXMqgBnPvcxzgNcQcUQWJG94Hv9ki']}

I don't need my object anymore - can I unpin it?

As we mentioned, your object will stay pinned until you unpin it. To unpin an object, you’ll need to remove it from local storage by running `pin_rm`.

import requests
params = (
('arg','QmeY7x2rEzyUxh2uwhXMqgBnPvcxzgNcQcUQWJG94Hv9ki')
)
response = requests.post('https://ipfs.dev.infura.org:5001/api/v0/pin/rm',params=params, auth=(<project_id>,<project_secret>)
print(response.json())

Again, if you just want confirmation that your unpin worked, you can run `print(response)`, or if you want to see the printout, simply run the above command and you’ll get the below (which looks exactly like the printout from pinning your file):

{'Pins': ['QmeY7x2rEzyUxh2uwhXMqgBnPvcxzgNcQcUQWJG94Hv9ki']}

And that’s it! You now know how to add, pin, and unpin files to IPFS using Infura. Have fun! Check out our documentation for a full list of our current supported functionality and the associated urls you can use to implement the call of your choice:

What’s next?

Subscribe to our newsletter so you can be the first to know when new products launch. As always, if you have questions or feature requests, you can join our community or reach out to us directly.