Skip to main content

Documentation Index

Fetch the complete documentation index at: https://pinata-fix--redirect--docs-to--quickstart.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 ✨