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.

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.