Pinata Docs
Search…
General
API - User
API - Pinning
V2 API
Pin JSON
Endpoint
/pinning/pinJSONToIPFS
Description
This endpoint allows the sender to add and pin any JSON object they wish to Pinata's IPFS nodes. This endpoint is specifically optimized to only handle JSON content.
Type
POSTHeaders
pinata_api_key: (put your personal pinata api key here)pinata_secret_api_key: (put your personal pinata secret api key here)OR
Authorization: Bearer (put your pinata JWT here)Body
There are two valid formats for uploading to this endpoint
Without additional options or metadata
If you don't wish to provide additional options or metadata for your JSON, then simply pass in a valid JSON object as the request body.
With options and / or metadata
pinataOptions
The following options are currently supported:
- cidVersion - The CID Version IPFS will use when creating a hash for your content. Valid options are:_ "0" - CIDv0_ "1" - CIDv1• customPinPolicy - a custom pin policy for the piece of content being pinned.
Providing a custom pin policy as part of a request means that the content being pinned will be replicated differently from the user's default pin policy found under the Account page.
To pass in a custom pin policy, pass in a "customPinPolicy" object that takes the following form:
1
pinataOptions: {
2
customPinPolicy: {
3
regions: [
4
{
5
id: 'FRA1',
6
desiredReplicationCount: 1
7
},
8
{
9
id: 'NYC1',
10
desiredReplicationCount: 2
11
}
12
]
13
}
14
}
Copied!
The ids of currently available public regions are:
- FRA1 - Frankfurt, Germany (max 2 replications)
- NYC1 - New York City, USA (max 2 replications)
pinataMetadata
This endpoint also allows for metadata to be attached to JSON uploads.
This metadata can later be used for easy querying on what you've pinned with our userPinList request.
The key-values object allows for users to provide any custom key / value pairs they want for the JSON being uploaded. These values can be:
- Strings
- Numbers (integers or decimals)
- Dates (Provided in ISO_8601 format)
As of right now, this is limited to 10 key-value pairs, but if this is a problem for you, please let us know!
JSON Example
If you wish to include options while pinning your JSON object, and/or if you wish to have metadata associated with it, please format your request body like this:
1
{
2
/* The "pinataMetadata" object will not be part of your content added to IPFS */
3
/* Pinata simply stores the metadata provided to help you easily query your JSON object pins */
4
pinataOptions: {
5
cidVersion: (the integer for your desired CID version),
6
customPinPolicy: (custom pin policy for this json)
7
},
8
pinataMetadata: {
9
name: (optional) - This is a custom name you can have for referencing your JSON object. This will be displayed in the Pin Manager "name" column if provided,
10
keyvalues: {
11
customKey: customValue,
12
customKey2: customValue2
13
}
14
},
15
/* The contents of the "pinataContent" object will be added to IPFS */
16
/* The hash provided back will only represent the JSON contained in this object */
17
/* The JSON the returned hash links to will NOT contain the "pinataMetadata" object above */
18
pinataContent: {
19
Any valid JSON goes here
20
}
21
}
Copied!
A Real World JSON Example
As an example, let's pretend you're building a system to verifiably track items through a supply chain, and every time an item reaches a new point in the supply chain, data is uploaded in the form of JSON about the item's current status.
With our supply chain example, a JSON upload with metadata may look like this:
1
{
2
pinataMetadata: {
3
name: 'ItemStatus'
4
keyvalues: {
5
ItemID: 'Item001',
6
CheckpointID: 'Checkpoint002',
7
Source: 'CompanyA'
8
WeightInKilos: 5.25
9
}
10
},
11
pinataContent: {
12
itemName: 'exampleItemName',
13
inspectedBy: 'Inspector001',
14
dataValues: [
15
{...}
16
]
17
}
18
​
19
}
Copied!
For examples on how to query Pinata's database for pins based on this metadata check out the documentation for our UserPinList request.
Response
1
{
2
IpfsHash: This is the IPFS multi-hash provided back for your content,
3
PinSize: This is how large (in bytes) the content you just pinned is,
4
Timestamp: This is the timestamp for your content pinning (represented in ISO 8601 format)
5
}
Copied!
JavaScript With Axios Example
In the javascript example below, we pass in our API keys from elsewhere (hopefully in a secure way), and the JSON content we wish to add to IPFS.
1
const axios = require('axios');
2
​
3
export const pinJSONToIPFS = (pinataApiKey, pinataSecretApiKey, JSONBody) => {
4
const url = `https://api.pinata.cloud/pinning/pinJSONToIPFS`;
5
return axios
6
.post(url, JSONBody, {
7
headers: {
8
pinata_api_key: pinataApiKey,
9
pinata_secret_api_key: pinataSecretApiKey
10
}
11
})
12
.then(function (response) {
13
//handle response here
14
})
15
.catch(function (error) {
16
//handle error here
17
});
18
};
Copied!
We want your feedback!
Have a suggestion? Have a complaint? Confused about something in the documentation? Just want to say hi?
We want to make Pinata the best product available. That involves listening to our users and addressing their needs.
Last modified 2mo ago