Important

This repository is archived. The spec is frozen and will not change.

Use it as-is: ipfs-pinning-service.yaml is unchanged since 2022, several services still speak it, and Kubo still ships a client for it. But work on it has stopped and should not be resumed here. The API has ossified past the point where a revision is worth the effort. If you want a better remote pinning API, design it fresh and propose it as an IPIP in ipfs/specs. See Why this is frozen.

Pinning Service API Spec

This repository contains the specs for the vendor-agnostic pinning service API for the IPFS ecosystem

• About
• Why this is frozen
• Specification
  • Code generation (client/server)
• Adoption
  • Client libraries
  • Server implementations
  • Online services
• Contribute

About

A pinning service is a service that accepts CIDs from a user in order to host the data associated with them.

The 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.

In this presentation, IPFS creator Juan Benet discusses current and potential pinning use cases, and how a standardized IPFS pinning API can meet these envisioned needs.

Why this is frozen

The spec reached v1.0.0 in 2020 and stopped changing in 2022. What is here works and is still deployed, so nothing is being taken away. What is not going to happen is further development, in this repo or anywhere else under this name.

The reasons are worth stating plainly, so nobody spends months rediscovering them:

• The API is ossified. Deployed servers, generated clients, and third-party integrations all pinned themselves to the 2020 shape of the requests and responses. Any change worth making is a breaking change, and a breaking change to a spec with this much deployed surface is a new spec wearing an old name.
• The tooling around it aged out. js-ipfs and ipfs-http-client are deprecated in favour of Helia, and go-pinning-service-http-client is archived. Some implementations are still maintained, but the set of things that would have to move together for a v2 no longer moves together.
• The problem moved. The design assumes a client that hands CIDs to a server and polls for status. Newer work on providing, retrieval, and verifiable transfer sits elsewhere, and a modern remote pinning API should be designed against that, not retrofitted onto this.

If you want to build a better API, do it. Start a new repository, and take the design through the IPIP process in ipfs/specs so it gets reviewed alongside the rest of the IPFS specifications. Please do not open pull requests here.

Specification

This API is defined as an OpenAPI spec in YAML format:

• ipfs-pinning-service.yaml

Documentation

You can find human-readable API documentation generated from the YAML file here:

• https://ipfs.github.io/pinning-services-api-spec

Code generation

https://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.

Give it a try before you resort to implementing things from scratch.

Adoption

The lists below record what implemented this API. They are a snapshot, not a maintained directory, and some entries have since been archived or shut down.

Support in IPFS tooling:

• Kubo (since v0.8.0: ipfs pin remote --help, see how to work with remote pinning services)
• ipfs-cluster (pinsvcapi component)
• ipfs-webui (remote pin support since v2.12.0)
• ipfs-desktop (>0.20.x)
• js-ipfs and ipfs-http-client shipped ipfs.pin.remote.* APIs. Both are deprecated; Helia replaced js-ipfs, and remote pinning for Helia lives in helia-remote-pinning.

Client libraries

• @helia/remote-pinning Remote pinning for Helia. This is the maintained JS client.
• @ipfs-shipyard/pinning-service-client Generated JS client, used in the compliance test suite.
• go-pinning-service-http-client (archived) Go client, vendored into Kubo for ipfs pin remote commands.
• https://openapi-generator.tech/docs/generators#client-generators Use the YAML file to generate a client for your language.
• auspinner A stateless CLI tool to pin and serve CAR files to IPFS pinning services using HTTP and Bitswap.

Server implementations

• @helia/pinning-service-api-server Server implementation powered by Helia.
• ipfs-cluster Pinset orchestration for IPFS. Exposes this API through its pinsvcapi component.
• js-mock-ipfs-pinning-service In-memory service for testing purposes.
• rb-pinning-service-api A Rails app that implements the IPFS Pinning Service API.
• https://openapi-generator.tech/docs/generators#server-generators Use the YAML file to generate server boilerplate for your language.

CI/CD

• https://github.com/marketplace/actions/ipfs-remote-pinning IPFS Pinning GitHub Action that adds data to IPFS and pins it to any ENDPOINT compatible with Pinning Service API

Online services

Services that exposed a compatible endpoint. Check with the provider before relying on any of these; this list is no longer being updated.

• https://pinata.cloud (documentation)
  • ipfs pin remote service add pinata https://api.pinata.cloud/psa YOUR_JWT
• https://filebase.com (documentation)
  • ipfs pin remote service add filebase https://api.filebase.io/v1/ipfs SECRET-ACCESS-TOKEN
• nft.storage, web3.storage, and estuary.tech offered compatible endpoints in 2022. Those endpoints are gone.

Timeline

• 2022 Q3
  • IPFS Pin Sync is announced by Filebase
  • Last substantive change to the spec
• 2022 Q1
  • web3.storage API support
  • estuary.tech API support
  • Mock server for local development: https://github.com/ipfs-shipyard/js-mock-ipfs-pinning-service
  • WIP official API client for JS: https://github.com/ipfs-shipyard/js-pinning-service-http-client/
  • WIP compliance test suite: #64
  • ipfs-cluster support (commit)
• 2021 Q1
  • go-ipfs 0.8.0 shipped with built-in client for v1.0.0 of this API
  • Pinata announces endpoint compatible with this spec
  • ipfs-webui v2.12.0 provides UI based on pin remote commands
  • Textile is working on Bucket Pinning API
• 2020 Q3
  • IPFS GUI WG working on adding support for pinning services into IPFS Desktop/Web UI:
    • Epic: Pinning service integration · Issue #91 · ipfs/ipfs-gui
    • Analysis of remote pinning services vs the needs of IPFS Web UI
  • ipfs/pinning-services-api-specs is created as a place for stakeholders to collaborate and finalize the API
    • 2020-07-14: Spec in draft status is ready for implementation
    • 2020-08: Addressing feedback from early implementers
    • 2020-09: End-to-end testing
• 2020 Q2
  • Pinning Summit 2020 (recorded talks)
• 2019 Q2
  • Creation of a generic pinning service API proposed in ipfs/notes/issues/378

Contribute

This repository is archived and is not accepting contributions. Nothing here is going to be revised, including typo fixes and link rot, because publishing a new version of a frozen spec is worse than leaving it exactly where implementers found it.

To propose a new or better remote pinning API, open an IPIP in ipfs/specs and build it in a new repository.

The IPFS Code of Conduct applies there as it did here.

Spec lifecycle

The label system used to identify the state of aspects of this spec:

• — A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec
• — A draft that is ready to review, and should be implementable
• — A spec that has been adopted (implemented) and can be used as a reference to learn how the system works
• — We consider this spec to close to final; it might be improved, but the system it specifies should not fundamentally change
• — This spec will not change
• — This spec is no longer in use

This spec is permanent.

If you are an AI coding assistant working in this repo, read AGENTS.md first.