{"openapi":"3.1.0","info":{"title":"Pinata (BYOK) API","version":"0.1.0","description":"Pinata (BYOK) lets an AI assistant read your own Pinata data through the Pinata API with a key you supply (API key JWT). Read-only: 8 tools (list_files, get_file, list_groups, get_group, list_pin_requests, get_hot_swap_history, list_gateways, get_top_gateway_traffic). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-pinata.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-pinata/docs"},"termsOfService":"https://connectorbay.com/byok-pinata/terms"},"servers":[{"url":"https://byok-pinata.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-pinata/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_files":{"post":{"operationId":"list_files","summary":"List files stored on Pinata (public or private IPFS network) with name, CID, size, MIME type, group and key-values, opti","description":"List files stored on Pinata (public or private IPFS network) with name, CID, size, MIME type, group and key-values, optionally filtered by name, group, MIME type or CID. Use for \"Which files have I stored on Pinata's public network\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Which IPFS network: public or private.","enum":["public","private"],"title":"Network","type":"string"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only files whose name matches this text.","title":"Name"},"group":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only files in this group id; pass 'null' for files that are in no group.","title":"Group"},"mime_type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only files of this MIME type, for example 'image/png'.","title":"Mime Type"},"cid":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the file with this CID.","title":"Cid"},"order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by creation date: ASC or DESC.","title":"Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (this connector allows 1 to 100).","title":"Limit"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: pass next_page_token from the previous answer to get the next page.","title":"Page Token"}},"required":["network"],"title":"list_filesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_file":{"post":{"operationId":"get_file","summary":"Get one stored file by its Pinata file id: name, CID, size, MIME type, group id, key-values and creation time. Use for \"","description":"Get one stored file by its Pinata file id: name, CID, size, MIME type, group id, key-values and creation time. Use for \"Show Pinata file e5323ea7-8a02-4486-9b6f-63c788810aeb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Which IPFS network: public or private.","enum":["public","private"],"title":"Network","type":"string"},"id":{"description":"Pinata file id (a UUID as shown by list_files), not the CID.","maxLength":64,"title":"Id","type":"string"}},"required":["network","id"],"title":"get_fileArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_groups":{"post":{"operationId":"list_groups","summary":"List file groups with name, visibility and creation time, optionally filtered by name or by public visibility. Use for \"","description":"List file groups with name, visibility and creation time, optionally filtered by name or by public visibility. Use for \"Which file groups do I have on Pinata\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Which IPFS network: public or private.","enum":["public","private"],"title":"Network","type":"string"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups whose name matches this text.","title":"Name"},"is_public":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for public groups only, false for private groups only.","title":"Is Public"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (this connector allows 1 to 100).","title":"Limit"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: pass next_page_token from the previous answer to get the next page.","title":"Page Token"}},"required":["network"],"title":"list_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_group":{"post":{"operationId":"get_group","summary":"Get one file group by id: name, visibility and creation time. Use for \"Show Pinata group 01919976-955f-7d06-bd59-72e8074","description":"Get one file group by id: name, visibility and creation time. Use for \"Show Pinata group 01919976-955f-7d06-bd59-72e80743fb95\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Which IPFS network: public or private.","enum":["public","private"],"title":"Network","type":"string"},"id":{"description":"Group id (a UUID as shown by list_groups).","maxLength":64,"title":"Id","type":"string"}},"required":["network","id"],"title":"get_groupArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_pin_requests":{"post":{"operationId":"list_pin_requests","summary":"List pin-by-CID requests on the public network with their status (for example searching, retrieving, backfilled or expir","description":"List pin-by-CID requests on the public network with their status (for example searching, retrieving, backfilled or expired), host nodes and queue time. Use for \"Which of my pin-by-CID requests are still searching\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["prechecking","backfilled","retreiving","expired","searching","over_free_limit","over_max_size","invalid_object","bad_host_node"],"type":"string"},{"type":"null"}],"default":null,"description":"Only requests in this status.","title":"Status"},"cid":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only requests for this CID.","title":"Cid"},"order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by queue date: ASC or DESC.","title":"Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (this connector allows 1 to 100).","title":"Limit"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: pass next_page_token from the previous answer to get the next page.","title":"Page Token"}},"title":"list_pin_requestsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_hot_swap_history":{"post":{"operationId":"get_hot_swap_history","summary":"Show the swap history of a CID on a gateway that has the Hot Swaps plugin installed: which CIDs it pointed to and when e","description":"Show the swap history of a CID on a gateway that has the Hot Swaps plugin installed: which CIDs it pointed to and when each was set. Use for \"What did CID bafkrei... point to over time on my gateway\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"network":{"description":"Which IPFS network: public or private.","enum":["public","private"],"title":"Network","type":"string"},"cid":{"description":"The original CID used in the gateway path.","maxLength":100,"title":"Cid","type":"string"},"domain":{"description":"Gateway domain that has the Hot Swaps plugin, for example 'example.mypinata.cloud'.","maxLength":200,"title":"Domain","type":"string"}},"required":["network","cid","domain"],"title":"get_hot_swap_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_gateways":{"post":{"operationId":"list_gateways","summary":"List the account's dedicated IPFS gateways with domain, restriction flag, creation time and custom domains. Use for \"Whi","description":"List the account's dedicated IPFS gateways with domain, restriction flag, creation time and custom domains. Use for \"Which dedicated gateways do I have on Pinata\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many gateways to return per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_gatewaysArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_top_gateway_traffic":{"post":{"operationId":"get_top_gateway_traffic","summary":"Rank a gateway's traffic between two dates by CID, country, region, user agent, referrer or file name, by number of requ","description":"Rank a gateway's traffic between two dates by CID, country, region, user agent, referrer or file name, by number of requests or bandwidth. Use for \"Which CIDs got the most requests on my gateway in October 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"gateway_domain":{"description":"Gateway domain, for example 'example.mypinata.cloud'.","maxLength":200,"title":"Gateway Domain","type":"string"},"start_date":{"description":"Start of the period, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"End of the period, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"},"by":{"description":"Attribute to group the ranking by.","enum":["cid","country","region","user_agent","referrer","file_name"],"title":"By","type":"string"},"sort_by":{"description":"Rank by number of requests or by bandwidth.","enum":["requests","bandwidth"],"title":"Sort By","type":"string"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many ranked rows to return (the API default is 100).","title":"Limit"}},"required":["gateway_domain","start_date","end_date","by","sort_by"],"title":"get_top_gateway_trafficArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}