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
Filter results based on name
const files = await pinata.files.public
.list()
.name("pinnie")
group
Filter results based on group ID
const files = await pinata.files.public
.list()
.group("5b56981c-7e5b-4dff-aeca-de784728dddb")
noGroup
Filter results to only show files that are not part of a group
const files = await pinata.files.public
.list()
.noGroup(true)
cid
Filter results based on CID
const files = await pinata.files.public
.list()
.cid("bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4")
mimeType
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
Order results either ascending or descending by created date
const files = await pinata.files
.list()
.order("ASC")
limit
Limit the number of results
const files = await pinata.files
.list()
.limit(10)
cidPending
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 ✨