Pinning Service

IPFS Pinning Service API Documentation

Overview

The Pinning Service API allows you to manage and persist content on IPFS by "pinning" CID objects. Pinning ensures that specific data remains available and is not garbage-collected by IPFS nodes.

This API is compatible with the IPFS Pinning Service API specification v1.0.0.

Base URL

Authentication

All endpoints require authentication using a Bearer token.

Authorization: Bearer <API_TOKEN>

To create or manage API tokens, visit your Account Settings.

Endpoints

List Pins

Retrieve a list of pinned or pinning requests.

Query Parameters

Response

{
  "count": 1,
  "results": [
    {
      "requestid": "a7b3f77e-...-4fae",
      "status": "pinned",
      "created": "2025-10-27T00:00:00Z",
      "pin": {
        "cid": "bafybeigdyrztp...",
        "name": "my-photo",
        "origins": ["/ip4/203.0.113.1/tcp/4001/p2p/QmExample"],
        "meta": {"source": "user-upload"}
      },
      "delegates": ["/ip4/203.0.113.2/tcp/4001/p2p/QmDelegateNode"]
    }
  ]
}

Add a Pin

Create a new pin request.

Request Body

{
  "cid": "bafybeigdyrztp...",
  "name": "project-backup",
  "origins": ["/ip4/203.0.113.10/tcp/4001/p2p/QmOrigin"],
  "meta": {"environment": "production"}
}

Response

{
  "requestid": "8f3e4dc1-...-9ef1",
  "status": "queued",
  "pin": {
    "cid": "bafybeigdyrztp...",
    "name": "project-backup",
    "origins": ["/ip4/203.0.113.10/tcp/4001/p2p/QmOrigin"],
    "meta": {"environment": "production"}
  },
  "delegates": [],
  "created": "2025-10-27T00:00:00Z"
}

Get Pin by ID

Retrieve metadata and status for a specific pin request.

Response

{
  "requestid": "8f3e4dc1-...-9ef1",
  "status": "pinned",
  "pin": {
    "cid": "bafybeigdyrztp...",
    "name": "project-backup",
    "origins": [],
    "meta": {"environment": "production"}
  },
  "delegates": [
    "/ip4/198.51.100.22/tcp/4001/p2p/QmDelegateNode"
  ],
  "created": "2025-10-27T00:00:00Z"
}

Replace a Pin

Replace the pin for a given request ID with a new CID or metadata.

Request Body

{
  "cid": "bafybeicx...",
  "name": "project-backup-v2"
}

Response

{
  "requestid": "8f3e4dc1-...-9ef1",
  "status": "queued",
  "pin": {
    "cid": "bafybeicx...",
    "name": "project-backup-v2"
  },
  "created": "2025-10-27T00:00:00Z"
}

Remove a Pin

Remove the pin request. This unpins the corresponding CID from the service's nodes.

Response

Status Codes

Data Model

Pin Object

PinStatus Object

Examples

Pin a File with curl

curl -X POST https://api.pinion.io/pins \
  -H "Authorization: Bearer $PINION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "cid": "bafybeigdyrztp...",
        "name": "my-data"
      }'

List All Pinned CIDs

curl -H "Authorization: Bearer $PINION_TOKEN" \
     https://api.pinion.io/pins?status=pinned

Webhooks (Optional Feature)

If configured, the service can notify your endpoint whenever pin status changes.

POST to your webhook URL with payload:

{
  "requestid": "8f3e4dc1-...-9ef1",
  "status": "pinned",
  "cid": "bafybeigdyrztp..."
}

Rate Limits

When the rate limit is exceeded, the service returns:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests, please wait before retrying."
}

Errors

Gateway API

IPFS Gateway API Documentation

Overview

The IPFS Gateway API provides HTTP access to content stored on the InterPlanetary File System (IPFS). It allows clients to retrieve content by its CID or path and supports both raw data streaming and browser-friendly delivery.

The API follows the IPFS Gateway specification and supports immutable (/ipfs/) and mutable (/ipns/) namespaces.

Base URL

Authentication

Public gateways may not require authentication. For private or usage-limited gateways, authenticate using a Bearer token:

Endpoints

Retrieve by CID

Fetch immutable content identified by the CID.

Example

GET /ipfs/bafybeigdyrztp... HTTP/1.1
Host: gateway.pinion.io
Accept: */*

Response

Returns the raw file or block associated with the CID. Content-Type depends on the data (e.g. application/octet-stream, text/html, application/json, etc.)

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 14

Hello, IPFS!

Retrieve by Path

Retrieve a specific file or subdirectory inside a DAG or UnixFS directory.

Example

Returns the content of logo.png as stored within the directory DAG.

Mutable Namespace (IPNS)

Resolve mutable content published via IPNS.

Example

Resolves to the latest content published under that key.

Metadata Only

Retrieve only headers and metadata about a CID, without downloading the body.

Example

Response

HTTP/1.1 200 OK
Content-Type: application/octet-stream
X-Ipfs-Path: /ipfs/bafybeigdyrztp...
X-Ipfs-Size: 12345

Range Requests

Supports HTTP Range requests for partial retrieval.

Example

GET /ipfs/bafybeigdyrztp... HTTP/1.1
Range: bytes=0-1023

Response

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/4096

Directory Listings

When the CID references a directory DAG, the gateway returns an HTML or JSON directory listing.

Example

Response (HTML)

<!DOCTYPE html>
<html>
  <head><title>Index of /ipfs/bafybeigdyrztp...</title></head>
  <body>
    <h1>Index of /ipfs/bafybeigdyrztp...</h1>
    <ul>
      <li><a href="file.txt">file.txt</a></li>
      <li><a href="images/">images/</a></li>
    </ul>
  </body>
</html>

Response (JSON)

Add header Accept: application/json:

{
  "type": "directory",
  "cid": "bafybeigdyrztp...",
  "entries": [
    {"Name": "file.txt", "CID": "bafybeib...", "Size": 1024, "Type": "file"},
    {"Name": "images", "CID": "bafybeid...", "Type": "directory"}
  ]
}

Content-Type Negotiation

Pinning via Gateway (Optional Feature)

If the gateway is linked with your Pinning Service account, you may request on-demand pinning via query parameter:

GET /ipfs/bafybeigdyrztp...?pin=true
Authorization: Bearer <API_TOKEN>

Response headers will include:

Status Codes

Response Headers

Caching

Pinion Gateway caches content on first access. Subsequent requests for the same CID are served directly from cache if available.

Errors

Examples

Retrieve File

Retrieve as JSON DAG

curl -H "Accept: application/json" \
     https://gateway.pinion.io/ipfs/bafybeigdyrztp...

Retrieve via IPNS

Partial Download

Rate Limits

When rate limit exceeded:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests, please wait before retrying."
}

Upload Service

Pinion Upload API v1

Overview

The Pinion Upload API allows clients to upload files or CAR (Content Addressable Archive) files, pin them to IPFS, and receive pin status updates. Each upload request may produce one or multiple pins, each with a unique status.

Base URL

Endpoint: POST /

Uploads a file or CAR archive for pinning.

Request

Headers

Content-Type (required):

• For a CAR file: application/vnd.ipld.car
• For regular files: any other valid MIME type (e.g., application/octet-stream)

Query Parameters

Body

The raw file data to pin. Either a single file or a CAR archive, depending on Content-Type or format.

Authentication

Requests must be authenticated. The server identifies the user via context, typically through cookies or an Authorization header (see your account service integration). Unauthorized requests will return 401 Unauthorized.

Response

Successful Response (200 OK)

Returns the status of the pinned content.

Single root pinned:

{
  "requestid": "uuid-string",
  "status": "PINNING",
  "created": "2025-10-27T01:23:45.678Z",
  "pin": {
    "cid": "bafybeib...",
    "name": "myfile"
  }
}

Multiple roots pinned:

Returns an array of pin statuses:

[
  {
    "requestid": "uuid-string-1",
    "status": "PINNING",
    "created": "2025-10-27T01:23:45.678Z",
    "pin": {
      "cid": "bafybeib1...",
      "name": "myfile-root-0"
    }
  },
  {
    "requestid": "uuid-string-2",
    "status": "PINNING",
    "created": "2025-10-27T01:23:45.678Z",
    "pin": {
      "cid": "bafybeib2...",
      "name": "myfile-root-1"
    }
  }
]

Error Responses

Behavior

• The server processes the uploaded data and extracts one or more root CIDs.
• Each root receives a unique requestid and initial status of PINNING.
• Pin statuses are stored in the internal datastore (docstore) for tracking.
• Each pin status is encoded and published to a Pub/Sub topic to notify other services.
• The API returns all pin statuses in the response.

Notes

• If multiple roots are generated from a single upload, the server automatically appends -root-N to the provided name for clarity.
• The requestid can be used to query pin status from downstream services or dashboards.
• All timestamps are returned in ISO 8601 UTC format.

GitHub Integration

GitHub Integration with Pinion

Overview

Pinion's GitHub integration allows developers to automatically upload build artifacts and host decentralized application (dApp) frontends on IPFS directly from GitHub Actions or workflows. This enables seamless CI/CD for static sites, frontends, and other assets, while ensuring persistence and availability via Pinion's pinning service.

Base Pinion API URL

Features

Automatic artifact pinning

Upload build outputs (e.g., dist/, build/) from GitHub workflows directly to Pinion.

dApp frontend hosting

Pinion hosts pinned frontend files and provides a content-addressable URL for accessing the application.

Multi-root support

Handles multi-file builds (like Webpack or Vite outputs) by pinning each root CID separately.

Status tracking

Each upload produces pin status messages for monitoring via Pinion's dashboard or webhooks.

Prerequisites

• A Pinion account with an API token or credentials.
• A GitHub repository for your project.
• Optional: GitHub Secrets configured with your Pinion API token.

Example Workflow: Upload Build Artifacts

Create a .github/workflows/pinion-upload.yml in your repository:

name: Pinion Upload

on:
  push:
    branches:
      - main

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Build project
        run: |
          npm install
          npm run build  # Outputs files to ./dist

      - name: Upload artifacts to Pinion
        uses: actions/http-client@v1
        with:
          url: http://pinion.build/upload/api/v1/
          method: POST
          headers: |
            Content-Type: application/octet-stream
            Authorization: Bearer ${{ secrets.PINION_API_TOKEN }}
          body: ./dist  # Path to your build output

Note: Replace ./dist with the folder containing your frontend build artifacts.

Parameters

Hosting dApp Frontends

After pinning, Pinion provides a content-addressable URL for your frontend:

<root-cid> corresponds to the root CID returned in the pin status JSON.

Each time you push a new build, a new root CID is generated. Use your workflow to update references automatically.

Handling Multiple Roots

• If your build produces multiple roots, Pinion will append -root-N to each pin name for clarity.
• Your workflow should capture each root CID to generate URLs for hosted assets.

Monitoring Pin Status

• Each upload returns a JSON object (or array for multiple roots) with requestid, status, and pin.cid.
• Use the requestid to track pin progress or trigger downstream workflows.

Recommended Workflow Enhancements

• CAR upload: For large builds, package your files as a CAR file to ensure deterministic pinning.
• Caching: Store previous root CIDs in workflow artifacts to skip re-uploading unchanged files.
• Notifications: Subscribe to Pinion Pub/Sub messages for automated deployment triggers.

This integration enables fully automated, GitHub-native deployment of dApps and pinned assets with IPFS persistence, reducing manual upload overhead and simplifying CI/CD pipelines.