Pinata API

Pinata IPFS API for file storage, groups, gateways, signatures, x402 payments, and file vectorization.

Security Scan

The skill is an instruction-only wrapper for the Pinata IPFS HTTP API and its requested secrets and behavior match that purpose, with only a small documentation inconsistency about an optional env var.

Purpose & Capability

Name/description describe Pinata API access and the skill only requires a Pinata JWT and gateway URL — exactly what's needed to call the documented endpoints.

Instruction Scope

SKILL.md contains straightforward HTTP request examples for uploading, pinning, groups, signatures, gateways, and x402 payments. It references an optional PINATA_GATEWAY_KEY env var (for gateway access control) that is not listed in the required env metadata — this is a minor documentation mismatch but not scope creep. The instructions do not ask the agent to read unrelated files or system state.

Install Mechanism

No install spec and no code files; instruction-only skills are low-risk because nothing is written to disk by the skill itself.

Credentials

Required env vars (PINATA_JWT, PINATA_GATEWAY_URL) are proportionate to the claimed functionality. The SKILL.md also mentions an optional PINATA_GATEWAY_KEY, but that optional var is not included in the metadata requires.env list — this should be reconciled. No unrelated credentials are requested.

Persistence & Privilege

always is false and the skill does not request persistent system-wide changes. The skill can be invoked autonomously (platform default), which is expected for an integration skill; no additional privileges are requested.

Assessment

This skill is an instruction-only mapping of the official Pinata HTTP API and is internally consistent with that purpose. Before installing: (1) ensure you provide a properly scoped PINATA_JWT (keep it secret and limit its permissions if possible); (2) confirm your PINATA_GATEWAY_URL is correct; (3) if you need gateway key functionality, supply PINATA_GATEWAY_KEY (SKILL.md mentions it but metadata doesn't); (4) be aware the agent will make network calls using your JWT, so only install if you trust the agent environment and the skill’s origin (the skill source is listed as unknown though the homepage and sample repo point to Pinata). If you want tighter safety, create a JWT with minimal permissions for this skill rather than using a highly privileged account token.

Access the Pinata IPFS storage API. Upload files, manage groups, create gateways, add signatures, set up x402 payments, and perform AI-powered vector search.

Repo: https://github.com/PinataCloud/pinata-api-skill

Authentication

All requests require the header:

Authorization: Bearer $PINATA_JWT

Environment Variables:

• PINATA_JWT (required) - Your Pinata API JWT token. Get one at app.pinata.cloud/developers/api-keys
• PINATA_GATEWAY_URL (required) - Your Pinata gateway domain (e.g., your-gateway.mypinata.cloud). Find yours at app.pinata.cloud/gateway
• PINATA_GATEWAY_KEY (optional) - Gateway key for accessing public IPFS content not tied to your Pinata account. See Gateway Access Controls

Test Authentication

GET https://api.pinata.cloud/data/testAuthentication

Base URLs

• API: https://api.pinata.cloud
• Uploads: https://uploads.pinata.cloud

Common Parameters

• {network} - IPFS network: public (default) or private
• Pagination uses limit and pageToken query parameters

Files

Search Files

GET https://api.pinata.cloud/v3/files/{network}

Query parameters (all optional): name, cid, mimeType, limit, pageToken

Get File by ID

GET https://api.pinata.cloud/v3/files/{network}/{id}

Update File Metadata

PUT https://api.pinata.cloud/v3/files/{network}/{id}
Content-Type: application/json

Body:

{
  "name": "new-name",
  "keyvalues": {"key": "value"}
}

Both fields are optional.

Delete File

DELETE https://api.pinata.cloud/v3/files/{network}/{id}

Upload File

POST https://uploads.pinata.cloud/v3/files
Content-Type: multipart/form-data

Form fields:

• file (required) - The file to upload
• network (optional) - public or private
• group_id (optional) - Group to add the file to
• keyvalues (optional) - JSON string of key-value metadata

Groups

List Groups

GET https://api.pinata.cloud/v3/groups/{network}

Query parameters (all optional): name, limit, pageToken

Create Group

POST https://api.pinata.cloud/v3/groups/{network}
Content-Type: application/json

Body:

{
  "name": "my-group"
}

Get Group

GET https://api.pinata.cloud/v3/groups/{network}/{id}

Update Group

PUT https://api.pinata.cloud/v3/groups/{network}/{id}
Content-Type: application/json

Body:

{
  "name": "updated-name"
}

Delete Group

DELETE https://api.pinata.cloud/v3/groups/{network}/{id}

Add File to Group

PUT https://api.pinata.cloud/v3/groups/{network}/{groupId}/ids/{fileId}

Remove File from Group

DELETE https://api.pinata.cloud/v3/groups/{network}/{groupId}/ids/{fileId}

Gateway & Downloads

Create Private Download Link

POST https://api.pinata.cloud/v3/files/private/download_link
Content-Type: application/json

Creates a temporary signed URL for accessing private files.

Body:

{
  "url": "https://{PINATA_GATEWAY_URL}/files/{cid}",
  "expires": 600,
  "date": 1700000000,
  "method": "GET"
}

• url (required) - Full gateway URL using your PINATA_GATEWAY_URL and the file's CID
• expires (optional) - Seconds until expiry (default: 600)
• date (required) - Current Unix timestamp in seconds
• method (required) - HTTP method, typically GET

Create Signed Upload URL

POST https://uploads.pinata.cloud/v3/files/sign
Content-Type: application/json

Creates a pre-signed URL for client-side uploads (no JWT needed on the client).

Body:

{
  "date": 1700000000,
  "expires": 3600
}

Optional fields: max_file_size (bytes), allow_mime_types (array), group_id, filename, keyvalues

Signatures

EIP-712 signatures for verifying content authenticity.

Add Signature

POST https://api.pinata.cloud/v3/files/{network}/signature/{cid}
Content-Type: application/json

Body:

{
  "signature": "0x...",
  "address": "0x..."
}

Get Signature

GET https://api.pinata.cloud/v3/files/{network}/signature/{cid}

Delete Signature

DELETE https://api.pinata.cloud/v3/files/{network}/signature/{cid}

Pin By CID

Pin existing IPFS content by its CID (public network only).

Pin a CID

POST https://api.pinata.cloud/v3/files/public/pin_by_cid
Content-Type: application/json

Body:

{
  "cid": "bafybeig..."
}

Optional fields: name, group_id, keyvalues, host_nodes (array of multiaddrs)

Query Pin Requests

GET https://api.pinata.cloud/v3/files/public/pin_by_cid

Query parameters (all optional): order (ASC/DESC), status, cid, limit, pageToken

Cancel Pin Request

DELETE https://api.pinata.cloud/v3/files/public/pin_by_cid/{id}

x402 Payment Instructions

Create payment instructions for monetizing IPFS content using the x402 protocol with USDC on Base.

USDC Contract Addresses:

• Base mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Base Sepolia (testnet): 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Important: The amount field uses the smallest USDC unit (6 decimals). For example, $1.50 = "1500000".

Create Payment Instruction

POST https://api.pinata.cloud/v3/x402/payment_instructions
Content-Type: application/json

Body:

{
  "name": "My Payment",
  "description": "Pay to access this content",
  "payment_requirements": [
    {
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "pay_to": "0xWALLET_ADDRESS",
      "network": "base",
      "amount": "1500000"
    }
  ]
}

• name (required) - Display name
• description (optional) - Description
• payment_requirements (required) - Array with asset (USDC contract address), pay_to (wallet address), network (base or base-sepolia), amount (smallest unit as string)

List Payment Instructions

GET https://api.pinata.cloud/v3/x402/payment_instructions

Query parameters (all optional): limit, pageToken, cid, name, id

Get Payment Instruction

GET https://api.pinata.cloud/v3/x402/payment_instructions/{id}

Delete Payment Instruction

DELETE https://api.pinata.cloud/v3/x402/payment_instructions/{id}

Associate CID with Payment

PUT https://api.pinata.cloud/v3/x402/payment_instructions/{id}/cids/{cid}

Remove CID from Payment

DELETE https://api.pinata.cloud/v3/x402/payment_instructions/{id}/cids/{cid}

Vectorize (AI Search)

Generate vector embeddings for files and perform semantic search across groups.

Vectorize a File

POST https://uploads.pinata.cloud/v3/vectorize/files/{file_id}

Delete File Vectors

DELETE https://uploads.pinata.cloud/v3/vectorize/files/{file_id}

Query Vectors (Semantic Search)

POST https://uploads.pinata.cloud/v3/vectorize/groups/{group_id}/query
Content-Type: application/json

Body:

{
  "text": "search query here"
}

Notes

• All JSON endpoints require Content-Type: application/json
• File uploads use multipart/form-data — do not set Content-Type manually
• Pagination: use pageToken from the previous response to get the next page
• Network defaults to public if not specified
• Gateway URLs follow the pattern https://{PINATA_GATEWAY_URL}/files/{cid}

Resources

• Pinata Documentation
• API Keys
• Gateway Setup
• x402 Protocol
• Source (GitHub)