This article summarizes the pitfalls and solutions when using the group feature with Pinata’s Files API v3.
Background
There are cases where you want to manage files uploaded to Pinata by groups and retrieve only files belonging to a specific group. For example, storing input images used in an NFT registration form in an “input” group and allowing image selection only from that group.
Pitfalls
1. Legacy API and V3 API File Management Are Separate
Problem: Files uploaded with the legacy API (pinFileToIPFS) cannot be retrieved with the V3 API (/v3/files). The reverse is also true.
Solution: Unify on one API. When migrating to V3 API, use V3 for new uploads and consider manually adding existing files to groups or performing a migration.
2. V3 API Endpoints Require the {network} Parameter
Problem: V3 API endpoints require the {network} parameter (public or private).
Solution: Use public for regular IPFS files.
3. Group Filter Parameter Names Differ
Problem: Parameter names differ between upload and list retrieval.
| Operation | Parameter Name |
|---|---|
| Upload | group_id |
| List Retrieval | group |
4. Authentication Differences by JWT Type
Problem: JWTs generated with Scoped Keys may not work with the V3 API.
Solution: Generate a new API Key with Admin permissions from the Pinata dashboard.
Implementation Examples
Environment Variables
Upload API (V3)
List Retrieval API (V3)
V3 API Endpoint List
| Operation | Method | Endpoint |
|---|---|---|
| File Upload | POST | https://uploads.pinata.cloud/v3/files |
| File List | GET | https://api.pinata.cloud/v3/files/{network} |
| Create Group | POST | https://api.pinata.cloud/v3/groups/{network} |
| Add File to Group | PUT | https://api.pinata.cloud/v3/groups/{network}/{group_id}/ids/{file_id} |
How to Find the Group ID
When you select a group in the Pinata dashboard, the group ID is displayed in the URL:
Alternatively, when retrieving files via the V3 API, you can find it in the group_id field of each file:
Debugging Tips
- First retrieve the list without a group filter: Confirm that files exist
- Check the
group_idin the response: Confirm files belong to the expected group - Check the endpoint URL: Confirm it includes
/publicor/private
Summary
| Item | Legacy API | V3 API |
|---|---|---|
| Upload | api.pinata.cloud/pinning/pinFileToIPFS | uploads.pinata.cloud/v3/files |
| List | api.pinata.cloud/data/pinList | api.pinata.cloud/v3/files/{network} |
| Group Parameter (Upload) | None | group_id |
| Group Parameter (List) | groupId | group |
| Getting CID | response.IpfsHash | response.data.cid |
When migrating to the V3 API, be mindful of these differences during implementation.