Logo

API Documentation

IPFS Pinning Service API - Spec-compliant and fully compatible with IPFS CLI

Real-World Applications

See how developers and organisations are using IPFS for gaming, music, scientific research, and more

Explore Use Cases

Pinning Service API

Spec-compliant IPFS Pinning Service API for seamless integration

IPFS CLI

Native IPFS CLI support with remote pinning service integration

Gateway Access

On-demand pinning with automatic content retrieval

Quick Start Guide

Get started with our IPFS pinning service in three simple steps:

1

Create an Account

Sign up for a free account to get started. 1 GB storage included.

2

Generate API Key

Create an API key from your Developer page. Keep it secure and never share it publicly.

3

Start Pinning

Use the IPFS CLI, REST API, or web interface to pin your content to IPFS.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorisation header:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your Developer page. Each key can be assigned specific permissions.

IPFS CLI Setup

Our service is fully compatible with the native IPFS CLI (Kubo 0.8+). Add the service as a remote pinning service:

Add Service

ipfs pin remote service add pinning \
  https://your-service.com/api/pinning \
  YOUR_API_KEY

Common Commands

Pin content:

ipfs pin remote add --service=pinning --name="my-file" QmXxx...

List pins:

ipfs pin remote ls --service=pinning --status=pinned

Remove pin:

ipfs pin remote rm --service=pinning --cid=QmXxx...

Pinning Service API

We implement the official IPFS Pinning Service API specification, ensuring full compatibility with standard IPFS tools.

Base URL: /api/pinning

Native IPFS CLI compatibility

Works seamlessly with ipfs pin remote commands

CID-based pinning

Pin existing CIDs from the IPFS network without re-uploading

Flexible upload options

Upload via local IPFS node, web interface, or directly to cluster

On-demand pinning

Content automatically pinned to IPFS when first accessed via gateway

List Pins

GET/api/pinning/pins

List pin objects with optional filtering and pagination

Query Parameters

ParameterTypeDescription
cidstring[]Filter by CID (can specify multiple)
statusStatus[]Filter by status: queued, pinning, pinned, failed
namestringFilter by exact name
limitnumberMax results (default: 10, max: 1000)

Request

curl "https://your-service.com/api/pinning/pins?status=pinned&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add Pin

POST/api/pinning/pins

Create a new pin request for a CID already in the IPFS network

Request Body

{
  "cid": "QmXxx...",
  "name": "my-document.pdf",
  "origins": [
    "/ip4/203.0.113.1/tcp/4001/p2p/QmSourcePeerId"
  ],
  "meta": {
    "app": "my-app"
  }
}

Response 201 Created

{
  "requestid": "clxyz456",
  "status": "queued",
  "created": "2025-10-13T12:05:00Z",
  "pin": {
    "cid": "QmXxx...",
    "name": "my-document.pdf"
  },
  "delegates": ["/dns4/cluster.example.com/tcp/4001/p2p/QmPeerId"]
}

Get Pin Status

GET/api/pinning/pins/{requestid}

Get the status and details of a specific pin request

Request

curl "https://your-service.com/api/pinning/pins/clxyz123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status Values

  • queued - Pin request received, waiting to start
  • pinning - Currently fetching and pinning content
  • pinned - Successfully pinned on all replicas
  • failed - Pin operation failed

Update Pin

POST/api/pinning/pins/{requestid}

Replace pin metadata (name, origins, meta). The CID cannot be changed.

Request Body

{
  "cid": "QmXxx...",
  "name": "updated-name.jpg",
  "meta": {
    "app": "my-app",
    "tag": "updated"
  }
}

Delete Pin

DELETE/api/pinning/pins/{requestid}

Remove a pin and unpin content from the cluster

Request

curl -X DELETE "https://your-service.com/api/pinning/pins/clxyz123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 202 Accepted

Unpins from cluster immediately and updates storage quota

On-Demand Pinning

Files are automatically pinned to IPFS when first accessed through our gateway. This eliminates the need for manual pinning of uploaded content.

How It Works

  1. 1

    File Upload

    Upload files via web interface or API, stored in MinIO

  2. 2

    First Access

    When accessed via gateway, file is automatically pinned to IPFS

  3. 3

    Cluster Distribution

    File is distributed across cluster nodes for redundancy

Benefit: Reduces bandwidth waste and speeds up uploads. Files are pinned only when actually needed.

Gateway Access

Access your pinned content through our IPFS gateway. Files are served with on-demand pinning support.

Gateway URL

/api/gateway/{cid}

Features

  • Automatic on-demand pinning when file is accessed
  • Access metrics tracking (view count, last accessed)
  • Redirects to IPFS gateway for actual content delivery
  • Seamless integration with dashboard file links

Pin from CID

Pin existing content from the IPFS network without re-uploading. Perfect for pinning content from other IPFS nodes or gateways.

Upload Options

Local IPFS Node

Upload to your local IPFS node, then pin to our service:

ipfs add file.jpg
ipfs pin remote add --service=pinning --name="file.jpg" QmXxx...

Web Interface

Use the "Pin from CID" feature on the Files page to pin existing CIDs.

Direct Upload

Upload directly via our web interface or API endpoints for seamless integration.