List & Query Files

Pinata gives you the ability to query uploaded files based on different filters and attributes such as name, key-values, date, and more. This is different from retrieving the actual contents of a file, which you can learn more about here.

Basic Usage

You can either use the SDK or the API as see in the examples below.

SDK

import { PinataSDK } from "pinata";

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: "example-gateway.mypinata.cloud",
});

const files = await pinata.files.public.list()

const JWT = "YOUR_PINATA_JWT";

async function files() {
  try {
    const url = "https://api.pinata.cloud/v3/files/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);
  }
}

This will return an array of file objects

SDK

{
  files: [
    {
      id: "dd5f8888-bf15-4559-b8a2-6c626869507f",
      name: "Hello Files API",
      cid: "bafybeifq444z4b7yqzcyz4a5gspb2rpyfcdxp3mrfpigmllh52ld5tyzwm",
      size: 4861678,
      number_of_files: 1,
      mime_type: "TODO",
      group_id: null,
      created_at: "2024-08-27T14:57:51.485934Z",
    },
    {
      id: "e2057aa3-7b6c-4a45-b785-12ba297bcbd0",
      name: "Quickstart.png",
      cid: "bafkreiebavn2jzkqh3ehy4pkqkdi2otnho6gbcffkeqnunk2lw5nmnwaea",
      size: 223548,
      number_of_files: 1,
      mime_type: "TODO",
      group_id: "5f8adce6-7312-46e0-90f7-13896bed297d",
      created_at: "2024-08-28T23:46:07.823118Z",
    },
    {
      id: "ac5308a1-de49-40a3-9f5c-d20f1bb6206d",
      name: "hello.txt",
      cid: "bafkreiffsgtnic7uebaeuaixgph3pmmq2ywglpylzwrswv5so7m23hyuny",
      size: 11,
      number_of_files: 1,
      mime_type: "TODO",
      group_id: null,
      created_at: "2024-08-29T02:23:02.735018Z",
    }
  ],
  next_page_token: "MDE5MWIzNGMtMWNmNy03MzExLThmMjYtZmZlZDMzYTVlY"
}

{
	"data": {
		"files": [
			{
				"id": "dd5f8888-bf15-4559-b8a2-6c626869507f",
				"name": "Hello Files API",
				"cid": "bafybeifq444z4b7yqzcyz4a5gspb2rpyfcdxp3mrfpigmllh52ld5tyzwm",
				"size": 4861678,
				"number_of_files": 1,
				"mime_type": "TODO",
				"group_id": null,
				"created_at": "2024-08-27T14:57:51.485934Z"
			},
			{
				"id": "e2057aa3-7b6c-4a45-b785-12ba297bcbd0",
				"name": "Quickstart.png",
				"cid": "bafkreiebavn2jzkqh3ehy4pkqkdi2otnho6gbcffkeqnunk2lw5nmnwaea",
				"size": 223548,
				"number_of_files": 1,
				"mime_type": "TODO",
				"group_id": "5f8adce6-7312-46e0-90f7-13896bed297d",
				"created_at": "2024-08-28T23:46:07.823118Z"
			},
			{
				"id": "ac5308a1-de49-40a3-9f5c-d20f1bb6206d",
				"name": "hello.txt",
				"cid": "bafkreiffsgtnic7uebaeuaixgph3pmmq2ywglpylzwrswv5so7m23hyuny",
				"size": 11,
				"number_of_files": 1,
				"mime_type": "TODO",
				"group_id": null,
				"created_at": "2024-08-29T02:23:02.735018Z"
			}
		],
		"next_page_token": "MDE5MWIzNGMtMWNmNy03MzExLThmMjYtZmZlZDMzYTVlY"
	}
}

Filters

When listing files there a few ways you can filter the results

name

• Type: string

Filter results based on name

SDK

const files = await pinata.files.public
  .list()
  .name("pinnie")

const url = "https://api.pinata.cloud/v3/files/public?name=pinnie"

group

• Type: string

Filter results based on group ID

SDK

const files = await pinata.files.public
  .list()
  .group("5b56981c-7e5b-4dff-aeca-de784728dddb")

const url = "https://api.pinata.cloud/v3/files/public?group=5b56981c-7e5b-4dff-aeca-de784728dddb"

noGroup

• Type: boolean

Filter results to only show files that are not part of a group

SDK

const files = await pinata.files.public
		.list()
		.noGroup(true)

const url = "https://api.pinata.cloud/v3/files/public?group=null"

cid

• Type: string

Filter results based on CID

SDK{3}

const files = await pinata.files.public
  .list()
  .cid("bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4")

const url = "https://api.pinata.cloud/v3/files/public?cid=bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4"

mimeType

• Type: string

Filter results based on mime type

SDK

const files = await pinata.files.public
  .list()
  .mimeType("image/png")

const url = "https://api.pinata.cloud/v3/files/public?mimeType=image/png"

keyvalues

• Type: Record<string | string>

Filter results based on keyvalue pairs in metadata

SDK

const files = await pinata.files.public
  .list()
  .keyvalues({
    env: "prod"
  })

const url = "https://api.pinata.cloud/v3/files/public?keyvalues[env]=prod"

order

• Type: "ASC" | "DESC"

Order results either ascending or descending by created date

SDK

const files = await pinata.files
  .list()
  .order("ASC")

const url = "https://api.pinata.cloud/v3/files?order=ASC"

limit

• Type: number

Limit the number of results

SDK

const files = await pinata.files
  .list()
  .limit(10)

const url = "https://api.pinata.cloud/v3/files?limit=10"

cidPending

• Type: boolean

Filters results and only returns files where cid is still pending

SDK

const files = await pinata.files
  .list()
  .cidPending(true)

const url = "https://api.pinata.cloud/v3/files?cidPending=true"

Auto Paginate (SDK)

The list method has an auto pagination feature that is triggered when used inside a for await iterator

for await (const item of pinata.files.list() {
  console.log(item.id);
}

Works like magic ✨