Groups
Groups allow you to organize your Pinata content through the Pinata App or through the Pinata API, giving you a clearer picture of what your files are being used for.
Pinata API
With the SDK, you can create groups, add files to groups, list details about a group, and more! You can also mange groups using the Pinata API.
Create a Group
To create a group you can use the create method and passing in the name
you want to give a group.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const group = await pinata.groups.create({
name: "My New Group",
});
This will return the Group info
{
"id": "61a4a882-1591-462e-bcb7-fa0eee5f3c51",
"user_id": "ec50a085-a746-428d-b01d-167ac379fbd4",
"name": "NFT-Project",
"updatedAt": "2024-07-03T18:09:33.610Z",
"createdAt": "2024-07-03T18:09:33.610Z"
}
Get a Group
To fetch details of an already existing group you can use the get and pass in the groupId
.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const groups = await pinata.groups.get({
groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
});
This will return the same group info received upon creation.
[
{
"id": "61a4a882-1591-462e-bcb7-fa0eee5f3c51",
"name": "NFT-Project-updated",
"user_id": "ec50a085-a746-428d-b01d-167ac379fbd4",
"createdAt": "2024-07-03T18:09:33.610Z",
"updatedAt": "2024-07-03T18:15:17.440Z"
}
]
List All Groups
If you want to get all Groups or filter through them, you can use the list method.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const groups = await pinata.groups
.list()
.name("Greetings");
Results can be filtered with the following queries.
Filter by name of the group
Paginate through next series of groups
Limit the number of results
This will return an array of Groups and their respective info:
[
{
"id": "61a4a882-1591-462e-bcb7-fa0eee5f3c51",
"name": "NFT-Project-updated",
"user_id": "ec50a085-a746-428d-b01d-167ac379fbd4",
"createdAt": "2024-07-03T18:09:33.610Z",
"updatedAt": "2024-07-03T18:15:17.440Z"
}
]
Listing Files in a Group
To list all the files that are part of a group you can use the listFiles method and the group
filter.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const files = await pinata
.listFiles()
.group('648767d5-0a80-4b3a-9669-93693e4a0519')
This will return an array of PinListItem objects.
{
"rows": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"ipfs_pin_hash": "<string>",
"size": 123,
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"date_pinned": "2023-11-07T05:31:56Z",
"date_unpinned": "2023-11-07T05:31:56Z",
"metadata": {
"name": "<string>",
"keyvalues": {}
},
"regions": [
{
"regionId": "<string>",
"currentReplicationCount": 123,
"desiredReplicationCount": 123
}
],
"mime_type": "<string>",
"number_of_files": 123
}
]
}
Updating the Name of a Group
You can update the name of a group using the update method and passing in the groupId
and the new name
you want to use.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const groups = await pinata.groups.update({
groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
name: "My New Group 2"
});
This will return the updated Group info.
{
"id": "3778c10d-452e-4def-8299-ee6bc548bdb0",
"name": "My New Group 2",
"user_id": "ec50a085-a746-428d-b01d-167ac379fbd4",
"createdAt": "2024-07-03T18:09:33.610Z",
"updatedAt": "2024-07-03T18:12:46.930Z"
}
Add CIDs to a Group
At this time, CIDs can only belong to one group at a time. If a CID is added to a Group while already being part of another, it will move the CID to the latest requested Group.
After a Group is created you can add CIDs to it using the addCids method. Just pass in the groupId
and an array of cids
.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const group = await pinata.groups.addCids({
groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
cids: ["QmVLwvmGehsrNEvhcCnnsw5RQNseohgEkFNN1848zNzdng"],
});
If successful, the endpoint will return an OK
response.
Removing CIDs from a Group
To remove CIDs from a Group, you would follow the same pattern as addCids
except using the removeCids method instead.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const group = await pinata.groups.removeCids({
groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
cids: ["QmVLwvmGehsrNEvhcCnnsw5RQNseohgEkFNN1848zNzdng"],
});
If successful, the endpoint will return an OK
response.
Delete a Group
Deleting a Group that has CIDs inside of it will not unpin/delete the CIDs. Please use the unpin method to actually delete a file from your account
To delete a Group you can use the delete method and pass in the groupId
.
import { PinataSDK } from "pinata-web3";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const groups = await pinata.groups.delete({
groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
});
If successful, the endpoint will return an OK
response.
Pinata App
If you just need to organize your files through a web interface, then the Pinata Web App can do just that!
Create a Group
Navigate to the Groups tab, click “New” in the top right corner, give it a name, then click “Create.” If you open the new Group in the web app, then the Group ID is in the URL path.
Add Files to Groups
At this time, CIDs can only belong to one group at a time. If a CID is added to a Group while already being part of another, it will move the CID to the latest requested Group.
There are a few ways you can add files to a Group after you have created one.
Upload Directly
After creating a group, you can click on it, then click the “Add” button in the top right to add files directly to the group.
File Details
If you already have files uploaded and you just need to add it to a Group, you can click on the file details button on the far right and select “Add to Group”
Bulk Add
To add lots of files at once, you can select multiple files from the Files page then click the “Add to Group” button from the toolbar.
Remove Files from Group
While inside the Group view, you can remove files from a group by either clicking on the file detail for a single file or by using the multi-select tool.
Deleting Groups
Deleting a Group that has CIDs inside of it will not unpin/delete the CIDs. Please follow the unpin guide to actually delete a file from your account
To delete a Group, navigate to the Groups page, click on the details of the Group, and select the “Delete Group” from the dropdown.