{"id":14956140,"url":"https://github.com/ipfs/pinning-services-api-spec","last_synced_at":"2025-10-01T17:30:42.110Z","repository":{"id":37585880,"uuid":"274403393","full_name":"ipfs/pinning-services-api-spec","owner":"ipfs","description":"Standalone, vendor-agnostic Pinning Service API for IPFS ecosystem","archived":false,"fork":false,"pushed_at":"2024-03-27T16:15:23.000Z","size":169,"stargazers_count":101,"open_issues_count":26,"forks_count":26,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-10-29T12:11:34.640Z","etag":null,"topics":["ipfs","pinning","pinning-commands","pinning-services"],"latest_commit_sha":null,"homepage":"https://ipfs.github.io/pinning-services-api-spec/","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-23T12:45:13.000Z","updated_at":"2024-10-27T18:40:26.000Z","dependencies_parsed_at":"2024-08-05T16:11:38.380Z","dependency_job_id":null,"html_url":"https://github.com/ipfs/pinning-services-api-spec","commit_stats":{"total_commits":100,"total_committers":8,"mean_commits":12.5,"dds":"0.19999999999999996","last_synced_commit":"8b271b6f90c87f29276b1e4402df01b48081061d"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fpinning-services-api-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fpinning-services-api-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fpinning-services-api-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fpinning-services-api-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/pinning-services-api-spec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222073989,"owners_count":16926420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ipfs","pinning","pinning-commands","pinning-services"],"created_at":"2024-09-24T13:12:22.541Z","updated_at":"2025-10-01T17:30:41.815Z","avatar_url":"https://github.com/ipfs.png","language":"Makefile","readme":"# Pinning Service API Spec\n\n[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://protocol.ai)\n[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.io/)\n[![](https://github.com/ipfs/pinning-services-api-spec/workflows/Lint/badge.svg?branch=main)](https://github.com/ipfs/pinning-services-api-spec/actions?query=workflow%3ALint+branch%3Amain)\n[![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square)](https://github.com/ipfs/specs/#understanding-the-meaning-of-the-spec-badges-and-their-lifecycle)\n\n\u003e This repository contains the specs for the vendor-agnostic pinning service API for the IPFS ecosystem\n\n[![pinning-services-api-contex.png](https://user-images.githubusercontent.com/157609/108572745-438fc300-7313-11eb-93c3-c8b29c0da988.png)](#about)\n\n- [About](#about)\n- [Specification](#specification)\n  - [Code generation](#code-generation) (client/server)\n- [Adoption](#adoption)\n  - [Client libraries](#client-libraries)\n  - [Server implementations](#server-implementations)\n  - [Online services](#online-services)\n- [Contribute](#contribute)\n\n## About\n\nA **pinning service** is a service that accepts [CIDs](https://github.com/ipld/cid/) from a user in order to host the data associated with them.\n\nThe rationale behind defining a generic pinning service API is to have a baseline functionality and interface that can be provided by pinning services, so that tools can be built on top of a common base of functionality. \n\nIn [this presentation](https://youtu.be/Pcv8Bt4HMVU), IPFS creator Juan Benet discusses current and potential pinning use cases, and how a standardized IPFS pinning API can meet these envisioned needs. \n\nThe API spec in this repo is the first step towards that future.\n\n## Specification \n\nThis API is defined as an OpenAPI spec in YAML format:\n\n* **[ipfs-pinning-service.yaml](./ipfs-pinning-service.yaml)** ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square)\n\n\n### Documentation\n\nYou can find human-readable API documentation generated from the YAML file here:\n\n- **[https://ipfs.github.io/pinning-services-api-spec](https://ipfs.github.io/pinning-services-api-spec/)** ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square)\n\n### Code generation\n\nhttps://openapi-generator.tech allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically, given the OpenAPI spec at [ipfs-pinning-service.yaml](./ipfs-pinning-service.yaml).\n\nGive it a try before you resort to implementing things from scratch.\n\n## Adoption\n\nBuilt-in support for pinning services exposing this API is coming to IPFS tooling: \n  - [go-ipfs](https://github.com/ipfs/go-ipfs)  ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) (since [v0.8.0](https://github.com/ipfs/go-ipfs/releases/v0.8.0): `ipfs pin remote --help`, see how to [work with remote pinning services](https://docs.ipfs.io/how-to/work-with-pinning-services/))\n  - [js-ipfs-http-client](https://www.npmjs.com/package/ipfs-http-client) ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) (`ipfs.pin.remote.*` JS APIs)\n  - [ipfs-cluster](https://cluster.ipfs.io) ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) ([issue](https://github.com/ipfs/ipfs-cluster/issues/1213))\n  - [js-ipfs](https://github.com/ipfs/js-ipfs#readme) – ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) ([js-ipfs/pull/3588](https://github.com/ipfs/js-ipfs/pull/3588))\n  - [ipfs-webui](https://github.com/ipfs-shipyard/ipfs-webui) ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square)  (remote pin support since [v2.12.0](https://github.com/ipfs/ipfs-webui/releases/v2.12.0))\n  - [ipfs-desktop](https://github.com/ipfs-shipyard/ipfs-desktop) ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) (\u003e0.20.x)\n\n### Client libraries\n- [js-pinning-service-http-client](https://github.com/ipfs-shipyard/js-pinning-service-http-client/)  ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)  \n  An IPFS Pinning Service HTTP Client library for JS, used in [compliance test suite](https://github.com/ipfs/pinning-services-api-spec/issues/64).\n- [go-pinning-service-http-client](https://github.com/ipfs/go-pinning-service-http-client)  ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square)  \n  An IPFS Pinning Service HTTP Client library for Go, used by go-ipfs internally in `ipfs pin remote --help` commands.\n- https://openapi-generator.tech/docs/generators#client-generators ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square)  \n  Use [YAML file](./ipfs-pinning-service.yaml) to generate client for your language  \n- [auspinner](https://github.com/2color/auspinner)\n  A stateless CLI tool to pin and serve CAR files to IPFS pinning services using HTTP and Bitswap.\n\n### Server implementations\n- https://github.com/ipfs/ipfs-cluster ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)\n   Pinset orchestration for IPFS  – [tracking issue](https://github.com/ipfs/ipfs-cluster/issues/1213)\n- https://github.com/ipfs-shipyard/js-mock-ipfs-pinning-service ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square)  \n  Implementation of in-memory service for testing purposes\n- https://github.com/ipfs-shipyard/rb-pinning-service-api ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square)  \n  A Rails app that implements the IPFS Pinning Service API\n- https://openapi-generator.tech/docs/generators#server-generators ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square)  \n  Use [YAML file](./ipfs-pinning-service.yaml) to generate server boilerplate for your language\n\n### CI/CD\n\n- https://github.com/marketplace/actions/ipfs-remote-pinning  \n  IPFS Pinning GitHub Action that adds data to IPFS and pins it to any `ENDPOINT` compatible with Pinning Service API\n\n### Online services\n\n- https://pinata.cloud – ([documentation](https://pinata.cloud/documentation#PinningServicesAPI))\n  - `ipfs pin remote service add pinata https://api.pinata.cloud/psa YOUR_JWT`\n- https://nft.storage\n  - `ipfs pin remote service add nft-storage https://nft.storage/api YOUR_API_KEY`\n- https://filebase.com - ([documentation](https://docs.filebase.com/storage-networks/ipfs/ipfs-pinning) + [IPFS Pin Sync](https://docs.filebase.com/ipfs/ipfs-pin-sync))\n  - `ipfs pin remote service add filebase https://api.filebase.io/v1/ipfs SECRET-ACCESS-TOKEN`\n- `{your project could be here}` – open a PR!\n\n### Timeline\n\n- 2022 Q3\n  - [IPFS Pin Sync](https://docs.filebase.com/ipfs/ipfs-pin-sync) is announced by Filebase\n- 2022 Q1\n  - [web3.storage](https://web3.storage) API support: https://docs.web3.storage/how-tos/pinning-services-api\n  - [estuary.tech](https://estuary.tech) API support: https://docs.estuary.tech/pinning-list\n  - Mock server for local development: https://github.com/ipfs-shipyard/js-mock-ipfs-pinning-service\n  - WIP official API client for JS: https://github.com/ipfs-shipyard/js-pinning-service-http-client/\n  - WIP compliance test suite: https://github.com/ipfs/pinning-services-api-spec/issues/64\n  - WIP ipfs-cluster support ([commit](https://github.com/ipfs/ipfs-cluster/commit/9549e0c86e500a0b15020f6e5d48664d1f3ab37d))\n- 2021 Q1\n  - [go-ipfs 0.8.0](https://github.com/ipfs/go-ipfs/releases/v0.8.0) shipped with built-in client for v1.0.0 of this API\n  - Pinata announces endpoint compatible with this spec: https://pinata.cloud/documentation#PinningServicesAPI\n  - ipfs-webui [v2.12.0](https://github.com/ipfs/ipfs-webui/releases/v2.12.0) provides UI based on `pin remote` commands\n  - Textile is [working on Bucket Pinning API](https://github.com/textileio/textile/discussions/499)\n- 2020 Q3\n  - IPFS GUI WG working on adding support for pinning services into IPFS Desktop/Web UI:\n    - [Epic: Pinning service integration · Issue #91 · ipfs/ipfs-gui](https://github.com/ipfs/ipfs-gui/issues/91)\n    - [Analysis of remote pinning services vs the needs of IPFS Web UI](https://docs.google.com/document/d/1f0R7woLtW_YTv9P9IOrUNK6QafgctJ7qTggEUdepD_c/)\n  - [ipfs/pinning-services-api-specs](https://github.com/ipfs/pinning-services-api-specs) is created as a place for stakeholders to collaborate and finalize the API\n    - 2020-07-14: Spec in draft status is ready for implementation\n    - 2020-08: Addressing feedback from early implementers\n    - 2020-09: End-to-end testing\n- 2020 Q2\n  - Pinning Summit 2020 ([website](https://ipfspinningsummit.com/), [recorded talks](https://www.youtube.com/watch?v=rYD2lfuatJM\u0026list=PLuhRWgmPaHtTvsxuZ9T-tMlu_v0lja6v5))\n- 2019 Q2 \n  - Creation of a generic pinning service API proposed in [ipfs/notes/issues/378](https://github.com/ipfs/notes/issues/378)\n\n## Contribute\n\nSuggestions, contributions, and criticisms are welcome! However, please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows.\n\nThis repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).\n\n### Spec lifecycle\n\nWe use the following label system to identify the state of aspects of this spec:\n\n- ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) — A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec\n- ![](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) — A draft that is ready to review, and should be implementable\n- ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) — A spec that has been adopted (implemented) and can be used as a reference to learn how the system works\n- ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) — We consider this spec to close to final; it might be improved, but the system it specifies should not fundamentally change\n- ![](https://img.shields.io/badge/status-permanent-blue.svg?style=flat-square) — This spec will not change\n- ![](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) — This spec is no longer in use\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fpinning-services-api-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Fpinning-services-api-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fpinning-services-api-spec/lists"}