canonical: https://jentic.com/apis/pinata.cloud/pinata

# Pinata API

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.

## For AI agents

Upload files to IPFS, manage content through groups and metadata, retrieve files via gateways, and implement access controls for decentralized storage.

## Scope

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.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Files** — Upload, list, update, delete files with metadata and vector search capabilities
- **Groups** — Organize files into collections with add, remove, and membership management
- **Gateways** — Dedicated IPFS retrieval endpoints with custom domains, access controls, and analytics
- **Pins** — Pin existing IPFS content by CID to ensure availability and manage pin requests
- **Keys** — Generate, list, and revoke API keys with scoped permissions and usage limits
- **Signatures** — Create signed URLs for temporary file access and presigned upload URLs
- **Analytics** — Track gateway usage, bandwidth, request counts, and top content metrics
- **NFT Backup** — Sync and backup NFT collections from connected wallets automatically
- **x402 Payments** — Implement cryptocurrency payment requirements for content access

## Why Jentic

- **Setup:** Wiring the Pinata API by hand means setting up its JWT bearer auth and coding each IPFS file upload, group, signed-URL, and pin-by-hash call yourself. Through Jentic you install once, import Pinata from the API Directory, store the JWT once, and your agent calls it.
- **Permission scoping:** Pinata puts the file and group id in the URL path (`/v3/files/{id}`, `/groups/{groupId}`), so a rule can pin your agent to one group and the files in it: it can upload files and add them to that group. You choose the operations it may call, so deleting a file or generating a new API key is not included unless you add it.
- **Credential handling:** Your Pinata JWT is stored once, encrypted, by your own Jentic One instance and injected as the bearer header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a file to IPFS' or 'create a signed URL for private content', and Jentic returns the matching Pinata operation with its input schema and gateway options so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Storj DCS S3-Compatible Gateway API** — A decentralized, S3-compatible object storage gateway from Storj DCS, offering a distributed alternative to Pinata for storing and retrieving files.
- **Backblaze B2 Cloud Storage API** — Backblaze B2 low-cost cloud object storage that pairs well with Pinata, giving you an affordable backend for archiving and serving files alongside IPFS.

## FAQ

### 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.

### Can I limit what my agent is allowed to do with the Pinata API?

Yes. Because you run Jentic One yourself, your own rules decide which Pinata operations and credentials the agent may use, and Pinata puts the file and group id right in the URL path (`/v3/files/{id}`, `/groups/{groupId}`), so you can pin the agent to a single group. With that scope it can upload files and add them to that group while operations you leave out, such as deleting a file with DELETE `/v3/files/{id}` or minting a new key via POST `/users/generateApiKey`, stay off limits until you grant them. You pick the exact endpoints it can call, and its stored JWT is injected only for those.