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 Pinata API, you can create groups, add files to groups, list details about a group, and more! For the full reference, check out our Pinata API Reference for Groups.

Create a Group

To create a group you can send a POST request to /groups with the following JSON body that contains the name of the group:

{
  "name": "my-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, make a GET request with the id of the group as the path paramter: /group/:id. This will return the Group 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"
  }
]

List All Groups

If you want to get all Groups or filter through them, you can make a GET request to /group. This endpoint accepts the following query params:

nameContains
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"
  }
]

Updating the Name of a Group

Updating the name of a Group is done by sending a PUT request to /groups/:id where the Group ID is a path param, as well as the JSON body with the new name:

{
  "name": "NFT-Project-updated"
}

This will return the updated Group 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: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.

Once a Group is created, you can then add files to that Group by sending a PUT request to /groups/:id/cids which takes the Group ID as a path parameter, as well as a JSON body with an array of CIDs:

{
  "cids": [
    "QmVLwvmGehsrNEvhcCnnsw5RQNseohgEkFNN1848zNzdng",
    "bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4"
  ]
}

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 adding except with a DELETE request instead.

{
  "cids": [
    "QmVLwvmGehsrNEvhcCnnsw5RQNseohgEkFNN1848zNzdng",
    "bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4"
  ]
}

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 /pinning/unpin to actually delete a file from your account

To delete a Group, you can send a DELETE request to /groups/:id which takes the Group ID as a path parameter.

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

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.