How to pin to IPFS effortlessly
Using Pinata’s API as an IPFS pinning service
Co-Authored with Kyle Tut
During our time building with Ethereum and the blockchain community, we noticed a common trend: Everyone is using IPFS to store their smart contract data. Combining IPFS with blockchain applications allows developers to create web3 DApps that benefit from the tamper-proof benefits of blockchain, but without the high costs associated with storing large amounts of data on-chain.
However, deploying your own IPFS node to host files can be a bit of an effort. To combat that, we decided to build a simple API for developers around the world to pin content on the IPFS network. In this post, you can expect to learn how to upload and pin content to IPFS through Pinata’s easy to use REST API.
Signing Up!
Let’s start with the basic requirements. You’ll need an account with Pinata to start using our service. This will provide you with the API keys you’ll need for the rest of this tutorial. The sign up page can be found here: Sign Up
Your API Keys
In case you forgot your Pinata API keys (shame). These can be found on your account page found here: account page
Your “Pinata API Key” acts as your public key for our REST API. Additionally, your “Pinata Secret API Key” acts as the password for your public key. Be sure to keep your secret key private!
Connecting to the API
The base URL for Pinata requests is: https://api.pinata.cloud
All requests to the Pinata API need to include two headers:
pinata_api_key: (put your personal pinata api key here)
pinata_secret_api_key: (put your personal pinata secret api key here)
Once you have your API Keys, you’re ready to roll! Let’s try connecting to the Pinata API via the data/testAuthentication endpoint.
Postman Example:
Want to try out the API without building out all that crazy code surrounding a server? We recommend checking out Postman for easy API experimentation:
JavaScript with axios example:
At Pinata, when it comes to interacting with an API through JavaScript, we’re fans of the axios npm library: https://github.com/axios/axios.
All of our JavaScript examples will use axios, but feel free to use what you feel comfortable with!
const axios = require('axios');export const testAuthentication = () => {
const url = `https://api.pinata.cloud/data/testAuthentication`;
return axios
.get(url, {
headers: {
'pinata_api_key': "your pinata api key",
'pinata_secret_api_key': "your pinata secret api key"
}
})
.then(function (response) {
//handle your response here
})
.catch(function (error) {
//handle error here
});
};
If you receive a message back from the API that says: “Congratulations! You are communicating with the Pinata API!”, you’re authenticated!
pinFileToIPFS
This endpoint allows the sender to add / pin any File they wish to Pinata’s IPFS nodes.
ANY FILE? Yeah. Any file. Here at Pinata, you can even host photos of your Interplanetary space odyssey.
Endpoint
https://api.pinata.cloud/pinning/pinFileToIPFS
Type
POST
Headers
Content-Type: `multipart/form-data; boundary=(See JavaScript example below)`,
pinata_api_key: (put your personal pinata api key here)
pinata_secret_api_key: (put your personal pinata secret api key here)
Body
A valid form-data object for your file. The name of your object key should be “file” and the value should be your actual file.
See the examples below for how you can achieve this in both Postman & Javascript.
Response
{
IpfsHash: This is the IPFS multi-hash provided back for your content,
PinSize: This is how large (in bytes) the content you just pinned is,
Timestamp: This is the timestamp for your content pinning (represented in ISO 8601 format)
}Postman Example:
When submitting through postman, you’ll need to name your KEY field: “file” and then select the “File” type for your KEY.
Then choose your file to upload for your VALUE
JavaScript with axios example:
In the javascript example below, we pass in our API keys from elsewhere (hopefully in a secure way).
For our file, the below exaple shows what it would look like if we gathered the file from out api’s source files. However you’ll likely gather it from elsewhere.
The example shows primarily shows how we need to set up the header for this call. Note how we’re setting up the boundary, which is needed for the Pinata API to accept a file upload.
//imports needed for this function
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');export const pinFileToIPFS = (pinataApiKey, pinataSecretApiKey) => {
const url = `https://api.pinata.cloud/pinning/pinJSONToIPFS`;//we gather a local file from the API for this example, but you can gather the file from anywhere
let data = new FormData();
data.append('file', fs.createReadStream('./yourfile.png'));return axios.post(url,
data,
{
headers: {
'Content-Type': `multipart/form-data; boundary= ${data._boundary}`,
'pinata_api_key': pinataApiKey,
'pinata_secret_api_key': pinataSecretApiKey
}
}
).then(function (response) {
//handle response here
}).catch(function (error) {
//handle error here
});
};
And that’s it. Happy IPFS pinning from the team that built Pinata!
At the time of writing, Pinata is in alpha.
