Pin By Hash

Need to upload content to IPFS for the first time? Try uploading it through our pinFileToIPFS endpoint.
Endpoint
/pinning/pinByHash
Description
This endpoint allows you to add a hash to Pinata for asynchronous pinning. Content added through this endpoint is pinned in the background and will show up in your pinned items once the content has been found/pinned. For this operation to succeed, the content for the hash you provide must already be pinned by another node on the IPFS network.
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
The formats for uploading to this endpoint are:
Basic Request
{
    hashToPin: (ExampleHash)
}
Request with metadata
Similar to other endpoints, Pinata also allows metadata to be attached to when pinning content by hash.
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 hash being pinned. 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!
If you wish for your hash's content 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 the content you've pinned with Pinata */
    pinataMetadata: {
        name: (optional) - This is a custom name you can have for referencing your pinned content. This will be displayed in the Pin Manager "name" column if provided,
        keyvalues: {
            customKey: customValue,
            customKey2: customValue2
        }
    },
    hashToPin: (ExampleHash)
}
For examples on how to query Pinata's database for pins based on this metadata check out the documentation for our UserPinList request.
pinataOptions (OPTIONAL)
Pinata supports adding additional options when pinning by hash. The following options are currently supported for this endpoint:
hostNodes - multiaddresses of nodes your content is already stored on. To help Pinata find your content faster, optionally provide us with the "multiaddresses" up to five host nodes that your content already resides on.
To find the multiaddresses of your nodes, simply run the following on your node's command line:
ipfs id
In the response, you'll want to focus on the "Addresses" array that's returned. Here you'll find the multiaddresses of your node. These multiaddresses are what other IPFS nodes use to connect to your node.
In the "Addresses" array, take note of the multiaddress that contains your external IP address. Not the local ipv4 "127.0.0.1" address or the local ipv6 "::1" address.
Here's an example of a full external ipv4 multiaddress (your IP address and node ID will differ):
/ip4/123.456.78.90/tcp/4001/ipfs/QmAbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIjKlMnOpQr
Once you've grabbed the full multiaddress for every node that already has your content pinned, simply add the "host_nodes" property to your request body like so:
{
    hashToPin: (ExampleHash),
    pinataOptions: {
        hostNodes: [
            /ip4/hostNode1ExternalIP/tcp/4001/ipfs/hostNode1PeerId,
            /ip4/hostNode2ExternalIP/tcp/4001/ipfs/hostNode2PeerId
            .
            .
            .
        ]
    }
}
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:
{
    hashToPin: (ExampleHash),
    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)
Response
{
    id: This is Pinata's ID for the pin job,
    ipfsHash: This is the IPFS multi-hash provided to Pinata to pin,
    status: The current status of the pin job. If the request was successful the status should be 'searching'.
    name: The name of the pin (if provided initially)
}
Troubleshooting
To check the status of hashes you currently have in the queue, use our pinJobs endpoint.
What do I do if the status of my pin is "expired"?
First, make sure that your content is on the network (see below). Once you're ready to try again, simply just submit a new request to this endpoint and Pinata will start attempting to pin your content again.
If your content is taking a while to be found or isn't being found at all. These are possible reasons:
The node pinning your content is currently offline.- If the node hosting your content is currently offline, then other nodes (including Pinata's) won't be able to find it!
The node pinning your content is currently "online", but the node is misconfigured - If the node your content is hosted on is misconfigured or stuck behind a firewall, then other nodes (including Pinata's) won't be able to find it!
The node pinning your content has very few peers. - If the node hosting your content isn't connected to very many peers, Pinata will eventually find it, but it may take quite a bit of time.
Pinata periodically scans the network for hashes in the pinning queue and attempts to pin them. Just make sure your content is available on the network and Pinata will find it! Once the content is found and pinned, it will be added to the list of actively pinned content.
Postman Example
JavaScript With Axios Example
In the javascript example below, we pass in our API keys from elsewhere (hopefully in a secure way), and the hash we wish to add to IPFS.
const axios = require('axios');
​
export const pinByHash = (pinataApiKey, pinataSecretApiKey, hashToPin) => {
    const url = `{{ apiBaseURL }}/pinning/pinByHash`;
    const body = {
        hashToPin: hashToPin,
        hostNodes: [
            '/ip4/hostNode1ExternalIP/tcp/4001/ipfs/hostNode1PeerId',
            '/ip4/hostNode2ExternalIP/tcp/4001/ipfs/hostNode2PeerId'
        ],
        pinataMetadata: {
            name: MyCustomName,
            keyvalues: {
                customKey: 'customValue',
                customKey2: 'customValue2'
            }
        }
    };
    return axios
        .post(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.
API - Pinning - Previous
Pin JSON
Next - API - Pinning
Unpin
Last updated 2 months ago