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. 
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()
This will return an array of file objects 
{
  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 
const files = await pinata.files.public
  .list()
  .name("pinnie")

​
group

  • Type: string
Filter results based on group ID 
const files = await pinata.files.public
  .list()
  .group("5b56981c-7e5b-4dff-aeca-de784728dddb")

​
noGroup

  • Type: boolean
Filter results to only show files that are not part of a group 
const files = await pinata.files.public
		.list()
		.noGroup(true)

​
cid

  • Type: string
Filter results based on CID 
const files = await pinata.files.public
  .list()
  .cid("bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4")

​
mimeType

  • Type: string
Filter results based on mime type 
const files = await pinata.files.public
  .list()
  .mimeType("image/png")

​
keyvalues

  • Type: Record<string | string>
Filter results based on keyvalue pairs in metadata 
const files = await pinata.files.public
  .list()
  .keyvalues({
    env: "prod"
  })

​
order

  • Type: "ASC" | "DESC"
Order results either ascending or descending by created date 
const files = await pinata.files
  .list()
  .order("ASC")

​
limit

  • Type: number
Limit the number of results 
const files = await pinata.files
  .list()
  .limit(10)

​
cidPending

  • Type: boolean
Filters results and only returns files where cid is still pending 
const files = await pinata.files
  .list()
  .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 ✨