Pinning anything other than JSON? Use our pinFileToIPFS endpoint.

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

POST

Headers

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

Similar to the pinFileToIPFS endpoint, Pinata also allows options to be included for pinning JSON.

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 read more about pin policies, please check out the Regions and Replications documentation.

To pass in a custom pin policy, pass in a "customPinPolicy" object that takes the following form:

pinataOptions: {
    customPinPolicy: {
        regions: [
            {
                id: 'FRA1',
                desiredReplicationCount: 1
            },
            {
                id: 'NYC1',
                desiredReplicationCount: 2
            }
        ]
    }
}

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:

{
    /* The "pinataMetadata" object will not be part of your content added to IPFS */
    /* Pinata simply stores the metadata provided to help you easily query your JSON object pins */
    pinataOptions: {
        cidVersion: (the integer for your desired CID version),
        customPinPolicy: (custom pin policy for this json)
    },
    pinataMetadata: {
        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,
        keyvalues: {
            customKey: customValue,
            customKey2: customValue2
        }
    },
    /* The contents of the "pinataContent" object will be added to IPFS */
    /* The hash provided back will only represent the JSON contained in this object */
    /* The JSON the returned hash links to will NOT contain the "pinataMetadata" object above */
    pinataContent: {
        Any valid JSON goes here
    }
}

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:

{
    pinataMetadata: {
        name: 'ItemStatus'
        keyvalues: {
            ItemID: 'Item001',
            CheckpointID: 'Checkpoint002',
            Source: 'CompanyA'
            WeightInKilos: 5.25
        }
    },
    pinataContent: {
        itemName: 'exampleItemName',
        inspectedBy: 'Inspector001',
        dataValues: [
            {...}
        ]
    }
​
}

For examples on how to query Pinata's database for pins based on this metadata check out the documentation for our UserPinList request.

Response

{
    IpfsHash: This is the IPFS multi-hash provided back for your content,
    PinSize: This is how large (in bytes) the content you just pinned is,
    Timestamp: This is the timestamp for your content pinning (represented in ISO 8601 format)
}

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.

const axios = require('axios');
​
export const pinJSONToIPFS = (pinataApiKey, pinataSecretApiKey, JSONBody) => {
    const url = `https://api.pinata.cloud/pinning/pinJSONToIPFS`;
    return axios
        .post(url, JSONBody, {
            headers: {
                pinata_api_key: pinataApiKey,
                pinata_secret_api_key: pinataSecretApiKey
            }
        })
        .then(function (response) {
            //handle response here
        })
        .catch(function (error) {
            //handle error here
        });
};

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.

Send us an email at [email protected] and we'll see how we can help.