How to Include Metadata with Your IPFS Uploads

A deep dive into how Pinata’s IPFS metadata functionality allows you to easily index and search for your content on IPFS.

The Problem

Currently, when uploading and pinning content to IPFS, it’s hard to keep track of your data. While IPFS is a great tool for storing your content in a verifiable and tamper-proof way, it doesn’t provide much in terms of discoverability.

The IPFS network doesn’t offer the querying functionality we’ve become accustomed to with modern databases. Developers can’t query the IPFS network and say “find me all of the legal agreements that I’ve signed” or “find me all the JSON objects my service has uploaded pertaining to this userID”.

So, this leaves us in a scenario where decentralized products have all of this data being pinned on IPFS, but at the same time have a very limited view into what’s actually being stored.

Introducing Pinata metadata support

With the newest release of Pinata Cloud, we’ve given developers the option to associate metadata with their IPFS uploads.

From this point onward, when adding content to IPFS through Pinata’s API, developers can optionally include:

A custom name for the content being added

Up to 10 custom key / value pairs

If included in an API request, Pinata will associate these pieces of metadata with whatever you’re uploading to allow for easy querying of your IPFS content through our userPinList API endpoint.

What’s an API request look like?

Please see our pinFileToIPFS documentation for more thorough explanations and code examples.

When uploading files to Pinata via our pinFileToIPFS endpoint, if you wish to include metadata about your upload, you’ll need to include the following “pinataMetadata” object with your multipart/form-data body.

pinataMetadata

The value for this object will take the following format:

{

"name": "aCustomNameForYourUpload",

"keyvalues": {

"customKey": "customValue",

"customKey2": "customValue2"

}

}

Please note that while both “name” and “keyvalues” are optional, if you include the “pinataMetadata” object in your API request, you need to include at least ONE of the two pieces of metadata inside the “pinataMetadata” object*

Please also note that if you do not provide a custom “name” for your file, the “name” value will automatically be set to the original name of the file being uploaded

The custom “keyvalue” entries can be any of the following types:

A string of alphanumeric characters

An number (in the form of an integer or decimal)

An ISO_8601 date (this is still a string, but we can actually query on dates in this format)

An Example

Let’s pretend you’re building a service for lawyers and want to tag every IPFS upload with the Layer’s ID, the ID for the Lawyer’s client, a charge code, and the cost of the service being provided.

Your metadata object may look like this: