Pinata Getting Started: Pinning Content to IPFS (2026)

Getting started overview

This guide provides a rapid onboarding path for developers to begin using Pinata's services for IPFS content management. It covers the essential steps from account setup and API key generation to making an initial API request to pin a file. The process assumes a basic understanding of RESTful APIs and command-line tools like curl, or familiarity with JavaScript for programmatic interaction.

Pinata offers a free Starter tier that includes 1GB of storage and 100GB of bandwidth, suitable for initial development and testing. Paid plans, such as the Picasso plan, offer increased capacity starting at $10 per month for 50GB storage and 250GB bandwidth. Pinata's services are designed to simplify the process of adding content to IPFS, ensuring availability and accessibility through pinning services and dedicated gateways.

The following table outlines the key steps to get started with Pinata:

Create an account and get keys

To begin using Pinata, you must first create an account and generate your API keys. These keys are essential for authenticating your requests to the Pinata API.

1. Sign up for a Pinata account

1. Navigate to the Pinata signup page.
2. Enter your email address and create a password.
3. Complete any additional registration steps as prompted.
4. Verify your email address if required.

Upon successful registration, you will be redirected to your Pinata dashboard.

2. Generate API Keys

API keys are used to authenticate your requests to the Pinata API. You will need both an API Key and a Secret API Key.

1. From your Pinata dashboard, navigate to the API Keys section.
2. Click the "New Key" button.
3. Provide a descriptive name for your API key (e.g., "MyFirstAppKey").
4. Pinata will generate an API Key, a Secret API Key, and a JWT (JSON Web Token).
5. Important: Copy and securely store your Secret API Key immediately. It will only be displayed once. If you lose it, you will need to generate a new key pair. The JWT can also be used for authentication, offering a different method for securing API calls, as described in the Pinata authentication documentation.

These credentials will be used in the authorization header of your API requests.

Your first request

With your API keys in hand, you can now make your first request to Pinata to pin a file to IPFS. This example demonstrates how to upload a small text file.

Prepare a sample file

Create a simple text file named hello.txt with the content "Hello, Pinata!" in a directory you can access from your command line.

Using cURL to pin a file

The following curl command uploads your hello.txt file to Pinata. Replace YOUR_API_KEY and YOUR_SECRET_API_KEY with the keys you generated.

curl -X POST \ 
     -H "pinata_api_key: YOUR_API_KEY" \ 
     -H "pinata_secret_api_key: YOUR_SECRET_API_KEY" \ 
     -F file=@./hello.txt \ 
     https://api.pinata.cloud/pinning/pinFileToIPFS

A successful response will include the IPFS hash (IpfsHash), the file size (PinSize), and a timestamp (Timestamp) of the pinned content. This hash uniquely identifies your content on the IPFS network, as explained in the IPFS content addressing documentation.

{
  "IpfsHash": "QmVq4pDq...",
  "PinSize": 16,
  "Timestamp": "2023-10-27T10:00:00.000Z"
}

Using JavaScript to pin a file (with fetch API)

For JavaScript environments (Node.js or browser), you can use the fetch API. First, ensure you have the form-data package installed if you are in Node.js for handling multipart/form-data requests. In a browser, FormData is globally available.

Node.js example (requires npm install form-data node-fetch)

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const API_KEY = 'YOUR_API_KEY';
const SECRET_API_KEY = 'YOUR_SECRET_API_KEY';

const pinFileToIPFS = async () => {
  const formData = new FormData();
  const fileStream = fs.createReadStream('./hello.txt');
  formData.append('file', fileStream);

  try {
    const response = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {
      method: 'POST',
      headers: {
        'pinata_api_key': API_KEY,
        'pinata_secret_api_key': SECRET_API_KEY
      },
      body: formData
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('File pinned successfully:', data);
  } catch (error) {
    console.error('Error pinning file:', error);
  }
};

pinFileToIPFS();

Browser example

In a browser environment, you would typically get the file from a user input (e.g., an <input type="file"> element).

const API_KEY = 'YOUR_API_KEY';
const SECRET_API_KEY = 'YOUR_SECRET_API_KEY';

const pinFileFromBrowser = async (file) => {
  const formData = new FormData();
  formData.append('file', file);

  try {
    const response = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {
      method: 'POST',
      headers: {
        'pinata_api_key': API_KEY,
        'pinata_secret_api_key': SECRET_API_KEY
      },
      body: formData
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('File pinned successfully:', data);
  } catch (error) {
    console.error('Error pinning file:', error);
  }
};

// Example usage (assuming 'fileInput' is an <input type="file"> element)
// const fileInput = document.getElementById('fileInput');
// fileInput.addEventListener('change', (event) => {
//   const selectedFile = event.target.files[0];
//   if (selectedFile) {
//     pinFileFromBrowser(selectedFile);
//   }
// });

Common next steps

After successfully pinning your first file, consider these common next steps to further integrate Pinata into your projects:

• Retrieve Pinned Content: Use the returned IpfsHash to access your content via a public IPFS gateway or your dedicated Pinata gateway. For instance, https://gateway.pinata.cloud/ipfs/YOUR_IPFS_HASH will typically resolve your content. More details are in the Pinata API reference for IPFS hashes.
• Manage Pinned Files: Explore the Pinata API documentation for pinning to learn how to list, unpin, and update your pinned content programmatically.
• Dedicated Gateways: For production applications, especially those requiring faster and more reliable content delivery, set up a Pinata Dedicated Gateway. This provides a custom domain for your IPFS content, bypassing public gateway limitations.
• Submarine "Gated" Content: If you need to restrict access to your IPFS content, investigate Pinata Submarine. This feature allows you to gate access to your content, commonly used for NFTs or exclusive digital assets.
• Utilize the JavaScript SDK: For a more abstract and developer-friendly experience in JavaScript environments, consider using the Pinata JavaScript SDK, which wraps the REST API for common operations.
• Explore Webhooks: Integrate Pinata webhooks to receive notifications about important events, such as when content is successfully pinned or when a pin fails. This can be useful for automating workflows in your application.
• Monitor Usage: Regularly check your Pinata dashboard usage statistics to monitor your storage and bandwidth consumption, especially if you are on the free tier or managing multiple projects.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check API Keys: Double-check that your pinata_api_key and pinata_secret_api_key are correct and have not been truncated or mistyped. Remember that the secret key is only shown once upon generation. If you suspect it's incorrect, generate a new key pair from your Pinata API Keys page.
• Authentication Errors (401 Unauthorized): This almost always indicates an issue with your API keys. Verify they are correctly placed in the HTTP headers. Ensure no extra spaces or characters are included.
• File Path Errors: For curl -F file=@./hello.txt, ensure that ./hello.txt is the correct path to your file from where you are executing the command. Use an absolute path if unsure.
• Network Issues: Verify your internet connection. Proxy settings or firewalls might also block outgoing requests to api.pinata.cloud.
• Content Type for pinFileToIPFS: Ensure you are sending the file as multipart/form-data. The -F file=@./hello.txt in curl handles this automatically. In JavaScript, ensure your FormData object is correctly constructed.
• Review Pinata Documentation: Consult the Pinata REST API reference for specific endpoint requirements and error codes. The documentation provides detailed examples and explanations for each API call.
• Check Pinata Status Page: Occasionally, service outages can occur. Check the Pinata status page to see if there are any ongoing incidents affecting the API.
• Small File Test: If you are trying to upload a large file and encountering issues, try with a very small text file (like hello.txt) first to rule out size-related problems.
• Contact Support: If you have exhausted these troubleshooting steps, reach out to Pinata support for assistance, providing details of your request and any error messages received.