How to Use the Pinata SDK

Written by: Steve Simkins

Republished from here: https://bit.ly/3DQNBeI

Since 2018, Pinata has been on a mission to make IPFS easier for blockchain and crypto developers, and we believe the Pinata SDK is a testament to our core commitments. It has evolved over the years, and its latest iteration provides the best developer experience no matter where you run it. In this post, we’ll show you the basics of getting started with the SDK, as well as some cool recipes and built-in features you may not know about!

Quickstart

Let’s get you using IPFS in no time! First, you’ll want to create a free Pinata account. Once you’re signed in, you’ll want to make an API key with admin permissions and save the longer JWT key that’s provided. Keep it somewhere safe!

Last thing we need to grab in the app is our Dedicated Gateway, which is created once you start an account. Visit the Gateways page and then copy the domain and save it with your JWT.

Now the fun part: let’s write some code! For simplicity, we’ll be using Bun to startup a new project, so if you haven’t installed it before, then check out the instructions here. In the terminal, we’ll go ahead and run the following to create a new folder, move into it, and initialize a new Bun project:

mkdir pinata-sdk
cd pinata-sdk
bun init -y
        

Once the main project files are setup, let’s install the Pinata SDK with this command:

bun add pinata
        

Now let’s open up the project in your text editor of choice.

Once you’re looking at your files, let’s make a new one in the root of the project called .env.local and put in the following contents:

PINATA_JWT=
GATEWAY_URL=
        

Here is where we’ll put the JWT API key we made earlier, as well as the Dedicated Gateway domain. Once you have those variables in there and have saved it, let’s open the index.ts file and put in the following code:

import { PinataSDK } from "pinata"

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT,
  pinataGateway: process.env.GATEWAY_URL
})

const file = new File(["Hello from the Pinata SDK!"], "hello.txt")

const upload = await pinata.upload.public.file(file)

console.log("File uploaded with CID: ", upload.cid)

const url = await pinata.gateways.public.convert(upload.cid)

console.log("Access the file at: ", url)
        

Let’s walk through each piece here. First, we’re importing the SDK and initializing it with our API key and Gateway. Then, we create a simple “hello world” text file and upload it to Public IPFS. Once it’s uploaded, we’ll log out the cid, then use that same CID to make a Gateway URL where we can access the file. Save the index.ts file then in the terminal run:

bun index.ts
        

If successful, then you should see something like this!

File uploaded with CID:  bafkreiepqvg4oi6ahq6eyfcnoabnxpmmprt3tgdzohvx5odtkmpvhtbsgi
Access the file at:  <https://lime-binding-caterpillar-737.mypinata.cloud/ipfs/bafkreiepqvg4oi6ahq6eyfcnoabnxpmmprt3tgdzohvx5odtkmpvhtbsgi>
        

You did it! You’ve upload a file to IPFS and created a link to access it in just a few lines of code. That’s how simple and easy to use the Pinata SDK is, but let’s not stop there.

Tips and Tricks

Our quick start just barely scratches the surface of what’s possible with the SDK, so now we’ll show you a few tricks it has up its sleeve!

Groups

Using folders in IPFS can be a real pain. Sometimes you want to move files around and edit a folder’s contents, but since IPFS is immutable it requires re-uploading the folder. Pinata’s Groups feature is designed to solve that! Here’s a quick snip of how you can use Groups in the SDK.

// Create the Group
const { id } = await pinata.groups.public.create({
	name: "NFT-Files"
})

// Upload files to it
const upload = await pinata.upload.public
	.file(file)
	.group(id)
	
// List all files for a group
const files = await pinata.files.public
	.list()
	.group(id)

// Add or remove existing files
const add = await pinata.groups.public.addFiles({
	groupId: "GROUP-ID",
	files: [
	  "FILE-ID",
		"ANOTHER-FILE-ID"
	],
});
        

Keyvalues

One of the more powerful features in the Pinata arsenal is Keyvalues. With this, you can upload or update files with Keyvalues and then query them, and of course the SDK makes this a breeze.

// Upload a file with a keyvalue
const upload = await pinata.upload.public
	.file(file)
	.keyvalues({
	  env: "prod"
	})

// Retrieve files for a given keyvalue
const files = await pinata.files.public
	.list()
	.keyvalues({
		env: "prod"
	})

// Update keyvalues
const update = await pinata.files.public.update({
  id: "8809812b-cd36-499f-b9b3-a37258a9cd6a",
  keyvalues: {
    env: "prod"
  }
})
        

Pre-Signed Upload URLs

The beauty of the Pinata SDK is that it can be used in client side applications, particularly uploads where it counts the most. Instead of sending a file to a server which then relays it to Pinata, you can just upload it directly from your frontend using a pre-signed upload URL.

// Create a pre-signed URL on the server and send it to the client
const signedURL = await pinata.upload.public
  .createSignedURL({
    expires: 30
  });

// Upload a file using the `signedURL` from the server
const upload = await pinata.upload.public
  .file(file)
  .url(signedURL)
        

Private IPFS

Our SDK has the ability to not only do Public IPFS, but Private as well! With Private IPFS you can upload sensitive data and only grant access on your terms. It also includes a whole separate set of classes for listing or updating files, groups, and more.

// Upload a file to Private IPFS
const upload = await pinata.upload.private.file(file)

// Create temporary access URLs that expire
const url = await pinata.gateways.private.createAccessLink({
	cid: "bafkreib4pqtikzdjlj4zigobmd63lig7u6oxlug24snlr6atjlmlza45dq",
	expires: 30,
});
        

Wrapping Up

We’ve put a lot of work into our SDK to help ensure developers only get the best experience with IPFS and Pinata, and we hope you agree! Don’t take our word for it, check out the documentation link below and try it out for yourself today!