Pinata API
★ Only Publicly Available OpenAPI DocumentStorageIpfsbearer45 EndpointsREST
For Agents
Upload files to IPFS, manage content through groups and metadata, retrieve files via gateways, and implement access controls for decentralized storage.
Use for: I need to upload a file to IPFS and get its CID, Store this image on IPFS and generate a gateway URL, Create a group of files for my NFT collection, List all files uploaded in the last 30 days
Not supported: Does not handle IPFS node operations, peer-to-peer networking, or direct blockchain interactions—use for managed IPFS pinning, gateway delivery, and content organization only.
Pinata is an IPFS (InterPlanetary File System) infrastructure platform that simplifies decentralized file storage and content delivery for developers. The API exposes comprehensive controls for uploading files, managing content through groups and metadata, retrieving files via dedicated IPFS gateways with custom domains, and implementing access controls. It serves as a fully-managed IPFS pinning service that eliminates infrastructure complexity while providing enterprise features like image optimization, analytics, NFT backup capabilities, and payment-gated content through the x402 protocol. Through Jentic, developers can integrate IPFS storage into AI agents and applications without managing keys, nodes, or gateway infrastructure.
Install Jentic One Beta
Connect the Pinata API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Pinata API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Pinata API.
Upload files to IPFS in multiple formats including direct files, base64, JSON, and from URLs
Organize and manage files through groups with add, remove, and bulk operations
Create and configure dedicated IPFS gateways with custom domains and CDN capabilities
Implement granular access controls including IP restrictions, host origin filtering, and API key-based permissions
Generate signed URLs for temporary file access and presigned URLs for direct uploads
Pin existing IPFS content by CID to ensure availability across the network
Query and manage file metadata, vectors, and custom key-value pairs for enhanced discoverability
Track gateway analytics including request counts, bandwidth usage, and top content metrics
Backup and sync NFT collections with automatic IPFS pinning
Implement payment-gated content delivery using the x402 cryptocurrency payment protocol
Apply image transformations and optimizations through gateway parameters
Use Cases
Patterns agents use Pinata API for, with concrete tasks.
★ Decentralized NFT Media Storage
Store NFT images, videos, and metadata on IPFS through Pinata's API to ensure permanent, decentralized availability. The API handles file uploads, generates content-addressed CIDs for immutable references in smart contracts, and provides dedicated gateways with custom domains for fast retrieval. Groups organize collections by project or drop, while the NFT backup feature automatically syncs wallet collections to prevent content loss from other pinning services going offline.
POST /v3/files to upload NFT image, capture the returned CID, then POST /groups to create a collection group and add the file ID. Use the CID in smart contract metadata and retrieve via the dedicated gateway URL.
Content-Addressable Application Storage
Build applications with verifiable, immutable file storage where content is addressed by cryptographic hash rather than location. Upload user files, documents, or media through Pinata's API and retrieve them via CID-based URLs that guarantee content authenticity. The gateway system provides global CDN distribution with optional access controls, image optimization, and custom domains. Metadata queries and group organization enable efficient content discovery without traditional database dependencies.
Upload file via POST /v3/files/public with metadata tags, store the returned CID and file ID in application database, then construct gateway URL https://{gateway-domain}/ipfs/{cid} for content delivery with optional image transformation parameters.
Private File Sharing with Time-Limited Access
Implement secure file sharing where uploaded files remain private by default and are accessed through cryptographically-signed URLs that expire after a specified duration. The API generates temporary access tokens that grant download permissions without exposing the underlying IPFS CID or requiring user authentication. Gateway access controls can further restrict retrieval to specific IP ranges or API keys, while signed URL generation handles the temporary permission logic.
Upload private file via POST /v3/files with network set to private, then call POST /v3/files/sign to generate a signed URL with expires parameter set to desired duration. Share the signed URL which grants temporary access without authentication.
Payment-Gated Content Distribution
Monetize digital content by requiring cryptocurrency micropayments for access using Pinata's x402 protocol integration. Upload files as private content, create payment instructions specifying the cryptocurrency amount and recipient address, then associate files with these payment requirements. When users attempt to retrieve content via the gateway, they must provide a payment proof that satisfies the instruction before the file is delivered. This enables pay-per-access models for media, datasets, APIs, or digital goods without subscription complexity.
Upload content via POST /v3/files with private network, create payment instruction via POST /v3/x402/payment_instructions specifying amount and crypto address, then associate file CID with payment instruction. Retrieval requests to gateway must include valid payment proof header.
Key Endpoints
45 endpoints — pinata is an ipfs (interplanetary file system) infrastructure platform that simplifies decentralized file storage and content delivery for developers.
METHOD
PATH
DESCRIPTION
POST
/v3/files
Upload a file to IPFS and receive its CID
GET
/v3/files
List files with filtering by name, group, CID, or metadata
DELETE
/v3/files/{id}
Delete a file by its unique identifier
POST
/groups
Create a new file group for organization
POST
/groups/{groupId}/files/{fileId}
Add a file to a group
POST
/v3/files/sign
Generate a signed URL for temporary file access
POST
/pinning/pinByHash
Pin an existing IPFS CID to ensure availability
GET
/data/testAuthentication
Test API authentication and verify credentials
POST
/users/generateApiKey
Create a new API key with scoped permissions
GET
/v3/ipfs/gateway_analytics
Retrieve gateway usage analytics and metrics
POST
/v3/files
Upload a file to IPFS and receive its CID
GET
/v3/files
List files with filtering by name, group, CID, or metadata
DELETE
/v3/files/{id}
Delete a file by its unique identifier
POST
/groups
Create a new file group for organization
POST
/groups/{groupId}/files/{fileId}
Add a file to a group
POST
/v3/files/sign
Generate a signed URL for temporary file access
POST
/pinning/pinByHash
Pin an existing IPFS CID to ensure availability
GET
/data/testAuthentication
Test API authentication and verify credentials
POST
/users/generateApiKey
Create a new API key with scoped permissions
GET
/v3/ipfs/gateway_analytics
Retrieve gateway usage analytics and metrics
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Pinata JWT tokens are stored encrypted in the Jentic vault and injected as the Authorization: Bearer header at execution time. Raw tokens never reach the agent's prompt or response context.
Intent-based discovery
Agents search by intent like 'upload file to IPFS' or 'create signed URL for private content', and Jentic returns the matching operation with its schema, required parameters, and gateway configuration options.
Time to first call
Direct Pinata integration: 2-3 days to implement file upload flows, gateway configuration, group management, and error handling. Through Jentic: under 1 hour—search, load schema, execute with automatic credential injection.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Alternative
Web3.Storage API
Protocol Labs' free IPFS and Filecoin storage service with similar pinning and gateway capabilities.
Choose Web3.Storage for free, permanent storage backed by Filecoin. Choose Pinata for enterprise features like dedicated gateways, access controls, analytics, and payment-gated content.
Alternative
Infura IPFS API
Ethereum infrastructure provider's IPFS service offering pinning and gateway access.
Choose Infura when already using their Ethereum RPC infrastructure and want unified billing. Choose Pinata for more specialized IPFS features, better documentation, and advanced gateway capabilities.
Complementary
NFT.Storage API
Free NFT-specific IPFS storage service optimized for NFT metadata and media with Filecoin backing.
Use NFT.Storage for free NFT-specific uploads with automatic Filecoin persistence. Use Pinata when you need dedicated gateways, custom domains, advanced access controls, or payment-gated NFT content.
FAQs
Specific to using Pinata API through Jentic.
What authentication does the Pinata API use?
Pinata uses JWT (JSON Web Token) authentication sent as a Bearer token in the Authorization header. When you create an API key in the dashboard, you receive a JWT that should be included as 'Authorization: Bearer YOUR_JWT' on every request. Through Jentic, the JWT is stored encrypted and injected at execution time so it never appears in agent context.
What is the difference between api.pinata.cloud and uploads.pinata.cloud?
api.pinata.cloud is the base URL for most API operations including authentication, groups, keys, and analytics. uploads.pinata.cloud/v3/files is the specialized endpoint for file upload operations. Both require the same JWT Bearer authentication and are part of the unified Pinata API surface.
How do I retrieve files after uploading them to Pinata?
After uploading, you receive a CID (content identifier) in the response. Files are retrieved via your dedicated gateway domain using the URL pattern: https://your-gateway.mypinata.cloud/ipfs/{CID}. You can configure custom domains, apply image transformations as query parameters, and implement access controls at the gateway level.
Can I use Pinata to pin existing IPFS content that wasn't uploaded through Pinata?
Yes. The POST /pinning/pinByHash endpoint accepts any IPFS CID and pins that content to Pinata's infrastructure. This ensures the content remains available even if the original source goes offline. This is particularly useful for backing up NFT collections or ensuring availability of content pinned elsewhere.
What are the rate limits and pricing for the Pinata API?
Pinata offers a free tier with 500 pinned files and 1GB storage. Paid plans scale based on storage capacity and bandwidth usage. The API does not publish specific rate limits in the documentation, but the service is designed to handle production workloads. Monitor your usage through the analytics endpoints and dashboard.
How does Pinata handle file privacy and access control?
Files can be uploaded as either public or private. Private files are not accessible through the gateway without signed URLs or proper authentication. You can implement IP-based restrictions, host origin filtering, API key requirements, and generate time-limited signed URLs for temporary access. The x402 payment protocol adds cryptocurrency payment gates for monetized content.
GET STARTED