> ## Documentation Index
> Fetch the complete documentation index at: https://pinata-mintlify-5df45191.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize uploads with file groups

> Use Pinata groups to organize your uploads through the app, SDK, or API, add and remove files, and keep track of what each set of CIDs is for.

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](/sdk/groups/public), you can create groups, add files to groups, list details about a group, and more! You can also manage groups using the [API](/api-reference/endpoint/create-group).

### Create a Group

To create a group you can use the [create](/sdk/groups/public/create) method and passing in the `name` you want to give a group.

<CodeGroup>
  ```typescript SDK theme={null}
  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",
  });
  ```

  ```typescript API theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {

      const payload = JSON.stringify({
        name: "My New Group",
      })

      const request = await fetch("https://api.pinata.cloud/v3/groups/public", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${JWT}`,
        },
        body: payload,
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

This will return the Group info

<CodeGroup>
  ```typescript SDK theme={null}
  {
    id: "01919976-955f-7d06-bd59-72e80743fb95",
    name: "Test Private Group",
    created_at: "2024-08-28T14:49:31.246596Z"
  }
  ```

  ```json API theme={null}
  {
    "data": {
      "id": "01919976-955f-7d06-bd59-72e80743fb95",
      "name": "Test Private Group",
      "created_at": "2024-08-28T14:49:31.246596Z"
    }
  }
  ```
</CodeGroup>

### 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](/sdk/upload/public/file).

<CodeGroup>
  ```typescript SDK {3} theme={null}
  const upload = await pinata.upload.public
    .file(file)
    .group("b07da1ff-efa4-49af-bdea-9d95d8881103")
  ```

  ```typescript API {13} theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function upload() {
    try {
      const formData = new FormData();

      const file = new File(["hello"], "Testing.txt", { type: "text/plain" });

      formData.append("file", file);

      formData.append("network", "public")

      formData.append("group", "b07da1ff-efa4-49af-bdea-9d95d8881103")

      const request = await fetch("https://uploads.pinata.cloud/v3/files", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${JWT}`,
        },
        body: formData,
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

Another option is to add files after the fact using the [addFiles](/sdk/groups/public/add-files) method.

<CodeGroup>
  ```typescript SDK theme={null}
  const upload = await pinata.groups.public.addFiles({
    groupId: "b07da1ff-efa4-49af-bdea-9d95d8881103",
    files: [
      "0ed5738f-07e7-4587-81fb-f04f8be15d77",
      "a277dc29-2ca3-4dfb-aeb9-3f2b23e956f7"
    ]
  })
  ```

  ```typescript API {6,8,11} theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {

      const groupId = "e0b102e9-d481-4192-ab44-b8f7ff010e9a"

      const fileId = "521f23f3-2749-4611-b757-3155b40ff570"

      const request = await fetch(
        `https://api.pinata.cloud/v3/groups/public/${groupId}/ids/${fileId}`,
      {
        method: "PUT",
        headers: {
          Authorization: `Bearer ${JWT}`,
        }
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

Removing files can be done the exact same way with the [removeFiles](/sdk/groups/public/remove-files) method.

<CodeGroup>
  ```typescript SDK theme={null}
  const upload = await pinata.groups.public.removeFiles({
    groupId: "b07da1ff-efa4-49af-bdea-9d95d8881103",
    files: [
      "0ed5738f-07e7-4587-81fb-f04f8be15d77",
      "a277dc29-2ca3-4dfb-aeb9-3f2b23e956f7"
    ]
  })
  ```

  ```typescript API {6,8,11} theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {

      const groupId = "e0b102e9-d481-4192-ab44-b8f7ff010e9a"

      const fileId = "521f23f3-2749-4611-b757-3155b40ff570"

      const request = await fetch(
        `https://api.pinata.cloud/v3/groups/public/${groupId}/ids/${fileId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${JWT}`,
        }
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

### Get a Group

To fetch details of an already existing group you can use the [get](/sdk/groups/public/get) and pass in the `groupId`.

<CodeGroup>
  ```typescript SDK theme={null}
  const groups = await pinata.groups.public.get({
  	groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
  });
  ```

  ```typescript API {6,8,11} theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {

      const groupId = "e0b102e9-d481-4192-ab44-b8f7ff010e9a"

      const request = await fetch(
        `https://api.pinata.cloud/v3/groups/public/${groupId}`,
      {
        method: "GET",
        headers: {
          Authorization: `Bearer ${JWT}`,
        }
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

This will return the same group info received upon creation.

<CodeGroup>
  ```typescript SDK theme={null}
  {
    id: "0191997b-ca28-79e8-9dbc-a8044ad3e547",
    name: "My New Group 5",
    created_at: "2024-08-28T14:55:12.448504Z",
  }
  ```

  ```json APi theme={null}
  {
    "data": {
      "id": "0191997b-ca28-79e8-9dbc-a8044ad3e547",
      "name": "My New Group 5",
      "created_at": "2024-08-28T14:55:12.448504Z"
    }
  }
  ```
</CodeGroup>

### List All Groups

If you want to get all Groups or filter through them, you can use the [list](/sdk/groups/public/list) method.

<CodeGroup>
  ```typescript SDK theme={null}
  const groups = await pinata.groups.public.list()
  ```

  ```typescript API theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {
      const url = "https://api.pinata.cloud/v3/groups/public"
      const request = await fetch(url, {
        method: "GET",
        headers: {
          Authorization: `Bearer ${JWT}`,
        }
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

Results can be filtered with the following queries.

#### name

* Type: `boolean`

Filters groups based on the group name

<CodeGroup>
  ```typescript SDK theme={null}
  const groups = await pinata.groups.public
      .list()
      .name("SDK")
  ```

  ```typescript API theme={null}
  const url = "https://api.pinata.cloud/v3/groups/public?name=SDK"
  ```
</CodeGroup>

#### limit

* Type: `number`

Limits the number of results

<CodeGroup>
  ```typescript SDK theme={null}
  const groups = await pinata.groups.public
      .list()
      .limit(10)
  ```

  ```typescript API theme={null}
  const url = "https://api.pinata.cloud/v3/groups/public?limit=10"
  ```
</CodeGroup>

This will return an array of Groups and their respective info:

<CodeGroup>
  ```typescript SDK theme={null}
  {
    groups: [
      {
        id: "0191997b-ca28-79e8-9dbc-a8044ad3e547",
        name: "My New Group 5",
        created_at: "2024-08-28T14:55:12.448504Z",
      }
    ],
    next_page_token: "MDE5MWIzNGMtMWNmNy03MzExLThmMjYtZmZlZDMzYTVlY"
  }
  ```

  ```json API theme={null}
  {
    "groups": [
      {
        "id": "0191997b-ca28-79e8-9dbc-a8044ad3e547",
        "name": "My New Group 5",
        "created_at": "2024-08-28T14:55:12.448504Z"
      }
    ],
    "next_page_token": "MDE5MWIzNGMtMWNmNy03MzExLThmMjYtZmZlZDMzYTVlY"
  }
  ```
</CodeGroup>

### Updating a Group

You can update the name of a group using either the SDK or the API.

<CodeGroup>
  ```typescript SDK theme={null}
  const groups = await pinata.groups.public.update({
  	groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
  	name: "My New Group 2",
  });
  ```

  ```typescript API theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {

      const groupId = "e0b102e9-d481-4192-ab44-b8f7ff010e9a"

      const payload = JSON.stringify({
        name: "My New Group 2",
      })

      const request = await fetch(
        `https://api.pinata.cloud/v3/groups/public/${groupId}`,
      {
        method: "PUT",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${JWT}`,
        },
        body: payload
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

This will return the updated Group info.

<CodeGroup>
  ```typescript SDK theme={null}
  {
    id: "3778c10d-452e-4def-8299-ee6bc548bdb0",
    name: "My New Group 2",
    created_at: "2024-08-28T20:58:46.96779Z"
  }
  ```

  ```json API theme={null}
  {
    "data": {
      "id": "01919ac8-a6f5-7e8e-a8a2-6cfe00122b90",
      "name": "Updated Name",
      "created_at": "2024-08-28T20:58:46.96779Z"
    }
  }
  ```
</CodeGroup>

### Delete a Group

<Note>
  Deleting a Group that has CIDs inside of it will not unpin/delete the files. Please use the [delete](/sdk/files/public/delete) method to actually delete a file from your account
</Note>

To delete a Group you can use the [delete](/sdk/groups/public/delete) method and pass in the `groupId`.

<CodeGroup>
  ```typescript SDK theme={null}
  const groups = await pinata.groups.public.delete({
  	groupId: "3778c10d-452e-4def-8299-ee6bc548bdb0",
  });
  ```

  ```typescript API theme={null}
  const JWT = "YOUR_PINATA_JWT";

  async function group() {
    try {

      const groupId = "e0b102e9-d481-4192-ab44-b8f7ff010e9a"

      const request = await fetch(
        `https://api.pinata.cloud/v3/groups/public/${groupId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${JWT}`,
        }
      });
      const response = await request.json();
      console.log(response);
    } catch (error) {
      console.log(error);
    }
  }
  ```
</CodeGroup>

If successful the endpoint will return an `OK` response.