Global Pin Policy

Endpoint

/pinning/userPinPolicy

Description

This endpoint allows the sender to change the pin policy for their account.

Following a successful call of this endpoint, the new pin policy provided will be utilized for every new piece of content pinned to IPFS via Pinata.

To read more about pin policies, please check out the Regions and Replications documentation.

Type

PUT

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

{
newPinPolicy: {
regions: [
{
id: (id of a region you want your content pinned to (see available regions below)),
desiredReplicationCount: (amount of replications you want in that region)
},
{
same region format as above
},
.
.
.
]
},
migratePreviousPins: (true or false)
}

newPinPolicy

The ids of currently available public regions are:

  • FRA1 - Frankfurt, Germany (max 2 replications)

  • NYC1 - New York City, USA (max 2 replications)

migratePreviousPins (optional)

Migrating your previous pins means that all of your existing content on Pinata will be replicated to match your new pin policy.

Valid options are:

  • true

  • false

Important things to note when migratePreviousPins is set to true:

  • If you have any content-specific pin policies that don't match your account-level pin policy, these will be overridden.

  • If you have a large pinset, this endpoint may take longer to return

  • There is currently a limit of one migration per day.

Response

If the operation is successful, you will receive back an "OK" REST 200 status.

Postman Example

JavaScript With Axios Example

In the javascript example below, we pass in our API keys from elsewhere (hopefully in a secure way).

const axios = require('axios');
‚Äč
export const changeUserPinPolicy = (pinataApiKey, pinataSecretApiKey) => {
const url = `https://api.pinata.cloud/pinning/userPinPolicy`;
const body = {
newPinPolicy: {
regions: [
{
id: 'FRA1',
desiredReplicationCount: 2
},
{
id: 'NYC1',
desiredReplicationCount: 2
}
]
},
migratePreviousPins: true
};
return axios
.put(url, body, {
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.