SDKs overview

Pinata offers Software Development Kits (SDKs) and libraries to facilitate interaction with its InterPlanetary File System (IPFS) pinning and gateway services. These tools enable developers to integrate decentralized storage functionalities directly into their applications, abstracting away the complexities of direct API calls. The primary focus of Pinata's official SDK support is JavaScript, reflecting its prevalence in web3 and dApp development. By utilizing these SDKs, developers can programmatically upload, retrieve, and manage content on IPFS through Pinata's infrastructure, ensuring content persistence and accessibility via dedicated gateways. This approach supports various use cases, from hosting NFT metadata and media to serving static website content and large datasets.

The Pinata API itself is a RESTful interface, which means it can be accessed using standard HTTP requests from any programming language. However, an SDK provides a higher-level abstraction, handling authentication, request formatting, and response parsing, which can accelerate development and reduce potential errors. For languages without an official SDK, developers typically use HTTP client libraries to interact with the Pinata REST API reference directly. The Pinata platform's developer experience emphasizes ease of use, providing clear documentation and examples for both the SDK and direct API interactions, as detailed in the Pinata developer documentation.

Official SDKs by language

Pinata currently provides one officially supported SDK, which is designed for JavaScript environments. This SDK simplifies common operations such as pinning files, managing content, and retrieving data from IPFS via Pinata's services. The official SDK is actively maintained and recommended for JavaScript-based projects, including those built with Node.js for backend services or in browser environments for frontend decentralized applications (dApps).

Language Package Name Install Command Maturity
JavaScript @pinata/sdk npm install @pinata/sdk or yarn add @pinata/sdk Stable

The JavaScript SDK is built to be compatible with both Node.js and browser environments, offering flexibility for various application architectures. It encapsulates the underlying HTTP requests to the Pinata API, providing a more idiomatic and convenient way to interact with the service. For instance, file uploads, which can involve multipart form data, are abstracted into simple function calls within the SDK. This design choice aims to lower the barrier to entry for developers building applications that require IPFS integration, aligning with the broader goal of making decentralized storage more accessible, as discussed in the MDN Web Docs on JavaScript.

Installation

Installing the Pinata JavaScript SDK is a standard procedure using common package managers like npm or Yarn. Before installation, ensure you have Node.js and a package manager installed on your system. The SDK is published to the npm registry, making it readily available for inclusion in JavaScript projects.

Prerequisites

  • Node.js (LTS version recommended)
  • npm or Yarn

Installation Steps

  1. Open your terminal or command prompt.
  2. Navigate to your project directory. For example: 
    cd my-web3-project
  3. Install the SDK using npm: 
    npm install @pinata/sdk
    Or, if you prefer Yarn: 
    yarn add @pinata/sdk
    This command downloads the @pinata/sdk package and its dependencies, adding them to your project's node_modules directory and updating your package.json file.
  4. Import the SDK into your project files. In your JavaScript or TypeScript files, you can import the SDK as follows: 
    import pinataSDK from '@pinata/sdk';
// For CommonJS (Node.js older versions)
const pinataSDK = require('@pinata/sdk');

After installation, you will need your Pinata API Key and Secret API Key to authenticate your requests. These credentials can be generated and managed from your Pinata account API Keys page. It is crucial to keep these keys secure and avoid exposing them in client-side code. For server-side applications, environment variables are recommended for storing sensitive information.

Quickstart example

This quickstart example demonstrates how to use the Pinata JavaScript SDK to authenticate with the Pinata API and pin a text string to IPFS. This is a fundamental operation, showcasing the ease of content upload. Before running this code, ensure you have installed the @pinata/sdk package as described in the installation section and have your Pinata API Key and Secret API Key ready.

File: pinata-quickstart.js

import pinataSDK from '@pinata/sdk';
import fs from 'fs';

// Replace with your actual API Key and Secret
const pinataApiKey = process.env.PINATA_API_KEY || 'YOUR_PINATA_API_KEY';
const pinataSecretApiKey = process.env.PINATA_SECRET_API_KEY || 'YOUR_PINATA_SECRET_API_KEY';

const pinata = new pinataSDK(pinataApiKey, pinataSecretApiKey);

async function testConnectionAndPin() {
  try {
    // 1. Test authentication
    const authResult = await pinata.testAuthentication();
    console.log('Authentication successful:', authResult.authenticated);

    if (!authResult.authenticated) {
      console.error('Authentication failed. Check your API keys.');
      return;
    }

    // 2. Pin a JSON object (e.g., NFT metadata)
    const jsonToPin = {
      name: 'My First Pinned NFT',
      description: 'This is a test NFT pinned via Pinata SDK.',
      image: 'ipfs://QmTfN2pYtQ...',
      attributes: [
        { trait_type: 'Color', value: 'Blue' },
        { trait_type: 'Material', value: 'Plastic' }
      ]
    };
    const options = {
      pinataMetadata: {
        name: 'My NFT Metadata',
        keyvalues: {
          customKey: 'customValue',
          environment: 'development'
        }
      },
      pinataOptions: {
        cidVersion: 0 // or 1
      }
    };

    console.log('Attempting to pin JSON...');
    const jsonPinResponse = await pinata.pinJSONToIPFS(jsonToPin, options);
    console.log('JSON Pinned successfully! IPFS Hash:', jsonPinResponse.IpfsHash);
    console.log('Gateway URL:', `https://gateway.pinata.cloud/ipfs/${jsonPinResponse.IpfsHash}`);

    // 3. Pin a local file (example: an image)
    // Create a dummy file for demonstration if it doesn't exist
    const dummyFilePath = './test-image.txt';
    if (!fs.existsSync(dummyFilePath)) {
        fs.writeFileSync(dummyFilePath, 'This is a dummy image file content.');
    }

    const readableStreamForFile = fs.createReadStream(dummyFilePath);
    const fileOptions = {
      pinataMetadata: {
        name: 'My Test Image',
        keyvalues: {
          type: 'sample',
          source: 'sdk-example'
        }
      },
      pinataOptions: {
        cidVersion: 1 // Recommended for new content
      }
    };

    console.log('Attempting to pin file...');
    const filePinResponse = await pinata.pinFileToIPFS(readableStreamForFile, fileOptions);
    console.log('File Pinned successfully! IPFS Hash:', filePinResponse.IpfsHash);
    console.log('Gateway URL:', `https://gateway.pinata.cloud/ipfs/${filePinResponse.IpfsHash}`);

  } catch (error) {
    console.error('Error during Pinata operations:', error.message);
    // Log full error for debugging if needed
    // console.error(error);
  }
}

testConnectionAndPin();

To run this example:

  1. Save the code as pinata-quickstart.js in your project directory.
  2. Create a .env file in the same directory and add your API keys: 
    PINATA_API_KEY=YOUR_PINATA_API_KEY
PINATA_SECRET_API_KEY=YOUR_PINATA_SECRET_API_KEY
    (Remember to replace YOUR_PINATA_API_KEY and YOUR_PINATA_SECRET_API_KEY with your actual keys from your Pinata API Keys page.)
  3. Install dotenv to load environment variables: 
    npm install dotenv
    Then, at the very top of your pinata-quickstart.js file, add: 
    require('dotenv').config();
  4. Execute the script from your terminal: 
    node pinata-quickstart.js

The output will show whether authentication was successful, followed by the IPFS hash (CID) of the pinned JSON object and the pinned file, along with their respective Pinata gateway URLs. You can then access this content via any IPFS gateway, including Pinata's dedicated gateways. This example demonstrates both pinJSONToIPFS for structured data and pinFileToIPFS for file streams, covering common pinning scenarios. The pinataMetadata and pinataOptions parameters allow for adding custom metadata and controlling pinning behavior, such as specifying the CID version, which is important for compatibility and future-proofing content on IPFS. Understanding CID versions (v0 vs. v1) is crucial for IPFS development, as detailed in IPFS content addressing documentation.

Community libraries

While Pinata officially supports a JavaScript SDK, the open-source nature of the IPFS ecosystem and Pinata's RESTful API design encourages the development of community-contributed libraries and integrations in various programming languages. These community efforts often emerge from developers seeking to use Pinata within their preferred language environments or to build specific tools on top of Pinata's services. These libraries may offer different levels of abstraction, feature sets, and maintenance compared to the official SDK.

Developers looking for Pinata integrations in languages other than JavaScript should consult community forums, GitHub, or package registries specific to those languages. For example, Python developers might search PyPI for packages that wrap the Pinata API, or Go developers might look at Go modules on GitHub. When using community-contributed libraries, it is advisable to:

  • Check the repository's activity: Look for recent commits, issue resolution, and pull request activity to gauge maintenance status.
  • Review documentation: Ensure the library has clear documentation and examples.
  • Examine the license: Understand the licensing terms for integrating the library into your project.
  • Verify functionality: Test critical functionalities thoroughly, especially for production applications.

As the web3 ecosystem evolves, new community libraries and integrations for Pinata may emerge. Developers can contribute to this ecosystem by building their own wrappers or contributing to existing projects, further expanding the accessibility of Pinata's decentralized storage solutions across different development stacks. The underlying HTTP/1.1 specification for REST APIs allows for this broad interoperability.