The [email protected] package became a Private IPFS only SDK and the Public IPFS SDK was moved to pinata-web3. This was also a result of our APIs being disconnected as well. Due to this problem we’ve unified our Public and Private IPFS APIs in our V3 API, and we have also unified them in our SDK in a new V2 release. This document will walk you through how to migrate from previous versions of either pinata or pinata-web3.

​
[email protected]

The pinata package was originally just for Private IPFS but now supports both Public and Private IPFS in [email protected].

​
API Keys

If you happened to be using a scoped API key for legacy endpoints like pinFileToIPFS or pinJSONToIPFS then you will need to create a new API key for the V2 SDK which uses the new V3 endpoints. If you want to scope your endpoint for the new API you can use the API docs for key creation to do so.

​
Installation and Initialization

Install the latest version by running the following command: 
npm i pinata@latest
Initalizing the SDK works the exact same way in previous versions 
const pinata = new PinataSDK({
  pinataJwt: "PINATA_JWT",
  pinataGateway: "example-gateway.mypinata.cloud",
});

​
Public & Private Methods

In [email protected] all methods were direct. In V2 there are public and private methods for the following classes:
  • upload
  • files
  • groups
  • gateways
  • signatures
This means you can simple pass in public or private after the main class to access those specific networks. 
const upload = await pinata.upload.file(file)

​
Accessing Private IPFS Files

The method createSignedURL for accessing files on Private IPFS has been renamed to createAccessLink 
const url = await pinata.gateways.createSignedURL({
	cid: "bafkreib4pqtikzdjlj4zigobmd63lig7u6oxlug24snlr6atjlmlza45dq",
	expires: 30,
});

​
Uploads with Metadata

When uploading files the addMetadata() method has been replaced with name() and keyvalues() to better match querying and listing files with those attributes. 
const upload = await pinata.upload
  .file(file)
  .addMetadata({
    name: "hello.txt",
    keyvalues: {
      env: "prod"
    }
  })

​
[email protected]

The pinata-web3 package previously was only supporting Public IPFS, and lacked some of the more natural organization that the pinata package had. With [email protected] the SDK supprts both Public and Private IPFS and is recommended that you migrate to pinata instead of continuing to use pinata-web3. This guide will walk through the changes that will need to be made.

​
API Keys

If you happened to be using a scoped API key for legacy endpoints like pinFileToIPFS or pinJSONToIPFS then you will need to create a new API key for the V2 SDK which uses the new V3 endpoints. If you want to scope your endpoint for the new API you can use the API docs for key creation to do so.

​
Installation and Initialization

Install the latest version by running the following command: 
npm i pinata@latest
Initalizing the SDK works the exact same way in previous versions, but you will need to change your imports from pinata-web3 to pinata. 
import { PinataSDK } from "pinata-web3"

const pinata = new PinataSDK({
  pinataJwt: "PINATA_JWT",
  pinataGateway: "example-gateway.mypinata.cloud",
});

​
Public & Private Methods

In [email protected] all methods were direct. In V2 there are public and private methods for the following classes:
  • upload
  • files
  • groups
  • gateways
  • signatures
This means you can simple pass in public or private after the main class to access those specific networks. 
const upload = await pinata.upload.file(file)

​
File Management

In pinata-web3 the methods to listFiles(), updateMetadata(), unpin() under the main PinataSDK class have been moved to a separate files class for better organization.

​
listFiles() -> files.<network>.list()

const files = await pinata.listFiles()

​
updateMetadata() -> files.<network>.update()

const update = await pinata.updateMedatadata({
  cid: "bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4",
  name: "Pinnie V2",
  keyValues: {
    whimsey: 200
  }
})

​
unpin() -> files.<network>.delete()

const unpin = await pinata.unpin([
  "bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4"
])

​
pinJobs() -> files.public.queue()

To list you pending pin by CID queue you can use the queue() method. 
const queue = await pinata.pinJobs().status("prechecking")

​
Swaps are now under Files

In pinata-web3 the Hot Swap methods were under the gateways class. These have been moved to the files class instead. Some of the naming convention has been updated as well.

​
swapCid() -> addSwap()

const swap = await pinata.gateways.swapCid({
  cid: "bafkreibbvdqf5ekc2crouowv7vtjbcmbjoiysegslmmqc6jrxbaa43xske",
  swapCid: "bafkreihumyr3bgxulu45ghws33xokwjm5o7xnkkgakaz66ldtylwiecnhu"
})

​
swapHistory() -> getSwapHistory()

const history = await pinata.gateways.swapHistory({
  cid: "bafkreibbvdqf5ekc2crouowv7vtjbcmbjoiysegslmmqc6jrxbaa43xske",
  domain: "discordpinnie.mypinata.cloud"
})

​
Groups

Groups have been updated to follow the file ID paradigm that is now part of the SDK, and so has the method names for adding or removing files

​
addCids() -> addFiles()

const group = await pinata.groups.addCids({
	groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
	cids: ["QmVLwvmGehsrNEvhcCnnsw5RQNseohgEkFNN1848zNzdng"],
});
See full reference

​
Analytics

In pinata-web3 analytics was grouped under the gateways class. In [email protected] it has been moved into it’s own class. Additionally the methods inside have been completely rewired to fit needs better. 
const analytics = await pinata.gateways.topUsageAnalytics({
  domain: "docs.mypinata.cloud",
  start: "2024-08-01",
  end: "2024-08-15",
  sortBy: "requests",
  attribute: "cid"
})
.cid("QmVLwvmGehsrNEvhcCnnsw5RQNseohgEkFNN1848zNzdng");

const analytics = await pinata.gateways.dateIntervalAnalytics({
  domain: "docs.mypinata.cloud",
  start: "2024-08-01",
  end: "2024-08-15",
  interval: "day"
})
.sort("desc");
See Analytics Reference for more info

​
Usage Class Removed

The pinata.usage class in the pinata-web3 package has been removed in [email protected].