File 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";
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: "01919976-955f-7d06-bd59-72e80743fb95",
name: "Test Private Group",
is_public: false,
created_at: "2024-08-28T14:49:31.246596Z"
}
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";
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: "0191997b-ca28-79e8-9dbc-a8044ad3e547",
name: "My New Group 5",
is_public: false,
created_at: "2024-08-28T14:55:12.448504Z",
}
List All Groups
If you want to get all Groups or filter through them, you can use the list method.
import { PinataSDK } from "pinata";
const pinata = new PinataSDK({
pinataJwt: process.env.PINATA_JWT!,
pinataGateway: "example-gateway.mypinata.cloud",
});
const groups = await pinata.groups.list()
Results can be filtered with the following queries.
name
- Type:
boolean
Filters groups based on the group name
const groups = await pinata.groups
.list()
.name("SDK")
isPublic
- Type:
boolean
Filters groups based on whether they are public or not
const groups = await pinata.groups
.list()
.isPublic(true)
limit
- Type:
number
Limits the number of results
const groups = await pinata.groups
.list()
.limit(10)
This will return an array of Groups and their respective info:
[
{
id: "0191997b-ca28-79e8-9dbc-a8044ad3e547",
name: "My New Group 5",
is_public: false,
created_at: "2024-08-28T14:55:12.448504Z",
}
]
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";
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",
"is_public": false,
"created_at": "2024-08-28T20:58:46.96779Z"
}
Delete a Group
Deleting a Group that has CIDs inside of it will not unpin/delete the files. Please use the delete 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";
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.