Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

Pinning Service API Spec

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



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.

The API spec in this repo is the first step towards that future.


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


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

Code generation 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.


Built-in support for pinning services exposing this API is coming to IPFS tooling:

Client libraries

Server implementations


Online services



Suggestions, contributions, and criticisms are welcome! However, please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows.

This repository falls under the IPFS Code of Conduct.

Spec lifecycle

We use the following label system 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