Skip to main content
Private Groups allow you to organize your Pinata content through the Pinata App, SDK, or API, giving you a clearer picture of what your files are being used for.

​
SDK and API

With the SDK, you can create groups, add files to groups, list details about a group, and more! You can also manage groups using the 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.public.create({
	name: "My New Group",
});
This will return the Group info 
{
  id: "01919976-955f-7d06-bd59-72e80743fb95",
  name: "Test Private Group",
  created_at: "2024-08-28T14:49:31.246596Z"
}

​
Add or Remove Files from a Group

There are two ways you can add files to a group. The first is to add the file to a group on upload. 
const upload = await pinata.upload.public
  .file(file)
  .group("b07da1ff-efa4-49af-bdea-9d95d8881103")
Another option is to add files after the fact using the addFiles method. 
const upload = await pinata.groups.public.addFiles({
  groupId: "b07da1ff-efa4-49af-bdea-9d95d8881103",
  files: [
    "0ed5738f-07e7-4587-81fb-f04f8be15d77",
    "a277dc29-2ca3-4dfb-aeb9-3f2b23e956f7"
  ]
})
Removing files can be done the exact same way with the removeFiles method. 
const upload = await pinata.groups.public.removeFiles({
  groupId: "b07da1ff-efa4-49af-bdea-9d95d8881103",
  files: [
    "0ed5738f-07e7-4587-81fb-f04f8be15d77",
    "a277dc29-2ca3-4dfb-aeb9-3f2b23e956f7"
  ]
})

​
Get a Group

To fetch details of an already existing group you can use the get and pass in the groupId. 
const groups = await pinata.groups.public.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",
  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. 
const groups = await pinata.groups.public.list()
Results can be filtered with the following queries.

​
name

  • Type: boolean
Filters groups based on the group name 
const groups = await pinata.groups.public
    .list()
    .name("SDK")

​
limit

  • Type: number
Limits the number of results 
const groups = await pinata.groups.public
    .list()
    .limit(10)
This will return an array of Groups and their respective info: 
{
  groups: [
    {
      id: "0191997b-ca28-79e8-9dbc-a8044ad3e547",
      name: "My New Group 5",
      created_at: "2024-08-28T14:55:12.448504Z",
    }
  ],
  next_page_token: "MDE5MWIzNGMtMWNmNy03MzExLThmMjYtZmZlZDMzYTVlY"
}

​
Updating a Group

You can update the name of a group using either the SDK or the API. 
const groups = await pinata.groups.public.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",
  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. 
const groups = await pinata.groups.public.delete({
	groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
});
If successful the endpoint will return an OK response.