Pinata API

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