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 IPFS 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.

name
string
default: "none"

Filter by name of the group

offset
integer
default: "none"

Paginate through next series of groups

limit
integer
default: "none"

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.

Pinning FilesListing Files