Filebase
HomepageFilebase DashboardDiscordBlog
  • 👋Welcome to Filebase!
  • Getting Started
    • FAQ
    • Service Limits
    • Getting Started Guides
      • Pin Your First File To IPFS
      • Developer Quick Start Guide
  • IPFS Concepts
    • What is IPFS?
    • What is an IPFS CID?
    • What is IPFS Pinning?
    • What is an IPFS Gateway?
  • IPFS Pinning
    • Pinning Files
    • Listing Files
    • Deleting Files
    • Event Notifications
  • IPNS Names
    • Managing Names
  • Dedicated IPFS Gateways
    • Managing Dedicated Gateways
    • Access Controls
    • Image Optimizations
    • Adding a Custom Domain
  • API Documentation
    • S3-Compatible API
      • Cross Origin Resource Sharing (CORS)
        • Create and Apply a CORS Rule to a Filebase Bucket
        • Deep Dive: Cross Origin Resource Sharing (CORS)
      • Pre-Signed URLs
    • Filebase Platform APIs
    • IPFS Pinning Service API
  • Code Development + SDKs
    • Code Development
      • Apache Libcloud - Python
      • Apostrophe CMS
      • AWS Lambda - NodeJS
      • AWS Lambda - Python
      • AWS SDK - Go (Golang)
      • AWS SDK - Java
      • AWS SDK - JavaScript
      • AWS SDK - .NET
      • AWS SDK - PHP
      • AWS SDK - Python
      • AWS SDK - Ruby
      • Code Examples
        • How To Utilize Filebase with NodeJS
      • DataCamp
      • Dart / Flutter
      • Django
      • Docker
        • Docker Volume Backup
      • Elixir Phoenix
      • Filebase NPM Package
      • Fog.io - Ruby
      • Google App Scripts
      • Integrated Haskell Platform
      • Laravel
      • Nuxt
      • Paperspace
      • Postman
      • Reading a JSON File
      • UNA
      • Unity
      • Uppy AWS S3 Plugin
      • Vue
      • Watcher for NodeJS
      • Webpack S3 Plugin
      • Xamarin
    • SDK Examples: Pinning Files and Folders to IPFS
      • AWS SDK for .NET
      • AWS SDK for Go
      • AWS SDK for JavaScript
      • AWS SDK for PHP
      • AWS SDK for Python
      • AWS SDK for Ruby
  • Archive
    • Content Archive
      • IPFS Getting Started Guide
      • Web Console Getting Started Guide
      • IPFS Tools
        • IPFS CLI
        • IPFS Desktop
        • IPFS Pin Sync
        • IPFS Pinning Service API
        • IPFS3up
      • Third Party Tools and Clients
        • Backup Client Configurations
          • AhsayCBS
          • BackupAssist Classic
          • BackupAssist ER
          • BackupNinja
          • BackupSheep
          • Bacula Enterprise Edition
          • CloudBacko
          • CloudBerry Backup
          • Cloudron
          • cPanel
          • Comet
          • Commvault
          • Duplicacy
          • Ghost IPFS Storage Adapter
          • IPFS Pinning GitHub Action
          • JetBackup
          • Kopia
          • MoveBot
          • MSP360 Online Backup
          • oDrive
          • Photos+ Cloud Library
          • qBackup
          • S3 Uploader for GitHub Actions
          • SimpleBackups
          • SnapShooter
          • Strapi Provider Plugin
          • Veeam
          • Wordpress
            • Media Cloud
            • XCloner
          • Zerto
        • CLI Tools
          • Ansible
          • Apache Pulsar
          • AWS CLI
            • How To Delete Data with AWS CLI
            • What is Multipart Upload?
          • Bash
            • Backup Files to IPFS with Bash
            • Laravel Backup with Bash
            • MongoDB Backup with Bash
            • PostgreSQL Backup with Bash
            • Wordpress Backup with Bash
          • cURL
          • Elasticsearch
          • IPFS-CAR
          • IPFScrape
          • IPGet
          • Jenkins
          • JFrog Artifactory
          • Kubernetes
            • Backup and Restore InFluxDB to Filebase with TrilioVault
            • CSI-S3
            • Kasten K10
            • Kerberos Vault
            • Longhorn.io
            • Stash for Kubernetes
            • Velero
          • Litestream
          • Minty
          • MongoDB
          • MoSMB
          • MySQL
          • Next.js .CAR File Upload
          • NFT Image Generator
          • NGINX S3 Gateway
          • Pinning Docker Images to IPFS
          • Pinning Encrypted Files to IPFS
          • PowerShell
            • Calculate the Size of Filebase Buckets using PowerShell
          • Rclone
            • Backing Up DigitalOcean Spaces to Filebase using Rclone
          • Restic
          • S3cmd
          • S3Express
          • S3FS-FUSE
          • S3QL
          • S3Surfer
          • S4cmd
          • SeaweedFS
          • Tableland
        • Content Delivery Networks
          • Bunny CDN
          • CloudFront CDN
          • Fastly CDN
        • File Management Client Configurations
          • Airbyte
          • Arq
          • Astiga
          • AWS Rekognition
          • AWS S3 Manager - iOS App
          • BucketAnywhere for S3 - Android App
          • CentreStack
          • CloudFlyer
          • Cloudfser
          • Couchdrop
          • CrossFTP
          • CyberDuck
            • How To Delete Data with CyberDuck
          • Dropshare
          • Duplicati
          • FileBrowserGO
          • Flexify.IO
          • ForkLift
          • Goofys
          • Joplin
          • LucidLink
          • MASV
          • Matrix Synapse
          • MinIO Gateway for S3
          • Mountain Duck
          • NetDrive
          • Nexfs
          • NextCloud
          • Nodeum
          • ownCloud
          • Plesk
          • Pure Storage FlashBlade
          • RaiDrive
          • S3 Browser
          • ShareX
          • SmartFTP
          • StableBit Cloud Drive
          • Storage Made Easy Enterprise File Fabric
          • WinSCP
        • NAS Device Configurations
          • Buffalo TeraStation
          • Datadobi DobiProtect
          • Netapp ONTAP Select
          • OpenDrives Atlas
          • Synology Hyper Backup
          • TrueNAS CORE
      • Knowledge Base
        • Deep Dives
          • Deep Dive: Blockchains
          • Deep Dive: Decentralized Compute
          • Deep Dive: Decentralized Digital Identity
          • Deep Dive: Decentralized Storage
          • Deep Dive: Erasure Coding
          • Deep Dive: Geo-Redundancy
          • Deep Dive: Metadata
          • Deep Dive: Metaverse
          • Deep Dive: NFTs
          • Deep Dive: Web3
        • Filebase eBooks
        • Filebase One-Pagers
        • Filebase Whitepapers
        • Web3 Tutorials
          • Alchemy
            • Alchemy: Build a dApp That Provides Real-Time Ethereum Transaction Notifications
            • Alchemy: Create a Full-Stack dApp
            • Alchemy: Create a Hello World Smart Contract
            • Alchemy: Create Your Own ERC20 Cryptocurrency
            • Alchemy: Decentralized Youtube
            • Alchemy: How to Create and Mint an NFT using Filebase
            • Alchemy: How to Mint an NFT Using Web3.js
            • Alchemy: Using The Alchemy SDK with NFTs Minted Through thirdweb
          • Agoric
            • Agoric: Create a DeFi dApp Using Agoric That’s Stored on Filebase
          • AirSwap
            • AirSwap: Track NFT Contract Addresses with AirSwap CLI
          • ArcBlock
            • ArcBlock: Running an ArcBlock Blocket Server on IPFS
          • Ankr
            • Ankr: Create a Truffle Project with Ankr and Filebase
            • Ankr: Deploy a Smart Contract on Polygon using Ankr that is backed up to Filebase
          • Avalanche
            • Avalanche: How To Launch a Generative NFT Collection With Avalanche and IPFS
          • Backing Up NFTs
          • Brownie
            • Brownie: Create and Mint an NFT Using Brownie
          • Bueno
            • Bueno: How to Create a Generative NFT Collection with Bueno
          • Cardano
            • Cardano: Submit Cardano Blockchain Transactions with Embedded Metadata Stored on Filebase
          • Ceramic
            • Ceramic: How to Host a Ceramic Node Using Decentralized Storage
          • Create-IPFS-app
          • Cosmos
            • Cosmos: Storing Cosmos Chain Governance Metadata on IPFS
          • DeCommerce
          • Ethereum Name Service
            • ENS: Configure an ENS Domain to use a Filebase IPFS Dedicated Gateway
          • Figment Datahub
            • Figment Datahub and Avalanche: Make an e-Voting dApp Using Figment Datahub, Avalanche, and Filebase
            • Figment Datahub and Celo Network: Create an ERC1155 NFT on the Celo Network using Figment Datahub and Objects Stored on Filebase
          • Flow
            • Flow: How to Create an NFT Marketplace with Filebase + Flow
          • Fauna
            • Fauna: Host an Application on IPFS with IPFS Dedicated Gateways
          • Ganache
            • Ganache: Create a dApp Hosted on IPFS
          • GUN
            • GUN: Create a Decentralized Chat App with GUN and IPFS
          • Hardhat
            • Hardhat: Creating an NFT Contract using Hardhat and Setting NFT Metadata using IPFS on Filebase
          • Harmony
            • Harmony: Deploy an HRC721 NFT on Harmony with IPFS
          • Hosting a Form on IPFS
          • iExec
            • iExec: Using iExec and Tee Worker to Create Apps that Use Datasets Stored on Filebase
          • Infura
            • Infura: Build dApp Frontends with Infura, React, and IPFS
            • Infura: Create an NFT Contract Factory with Metadata stored on IPFS
          • Lens Protocol
            • Lens Protocol: Build a Decentralized Social Media Network Stored on IPFS
          • LIT Protocol
            • LIT Protocol: Create a MintLIT NFT with LIT Protocol and IPFS
          • LivePeer
            • LivePeer: Mint a Video NFT with LivePeer
          • Macrometa
            • Macrometa: Track IPFS Files with Macrometa
          • Mina Protocol
            • Mina Protocol: Create a Simple zkApp with Mina Protocol and IPFS
          • NEAR Protocol
            • NEAR Protocol: Storing Off-Chain Data on IPFS using Filebase
          • NFTPort
            • NFTPort: Create an NFT Collection with NFTPort
          • Ocean Protocol
            • Ocean Protocol: Publish Data NFTs Stored on IPFS using Ocean Protocol
          • Pin Tezos Tokens Tool
          • Polkadot
            • Polkadot: Deploy a Polkadot dApp on Decentralized Storage
          • Polygon
            • Polygon: Building an App NFT With Polygon
            • Polygon: Make a Donation App with IPFS and Polygon
          • Python
            • Generating NFT Metadata with Python
          • QuickNode
            • QuickNode: Create a Token dApp using QuickNode
          • Remix
            • Remix: Create a Web App with Remix to Upload to Decentralized Storage
          • Remix IDE
            • Remix IDE: Creating Interactive NFTs with IPFS and Remix IDE
          • Secret Network
            • Secret Network: Create an NFT on Secret Network with Data Stored on IPFS
          • Stargaze
            • Stargaze: Create an NFT Collection Using IPFS and Stargaze
          • Starknet
            • Starknet: Create a HardHat Project Using A Starknet Plugin Hosted On IPFS
          • Studio 721
            • Studio 721: Create an NFT Collection with Studio 721 and IPFS
          • Solana
            • Solana: Minting an NFT Using Sugar, Candy Machine, and Filebase
          • Subsquid
            • Subsquid: Querying NFT Data using Subsquid and a Filebase IPFS Dedicated Gateway
          • Tailwind CSS
            • Tailwind CSS: Build an Image Gallery App with IPFS and Tailwind CSS
          • Tatum
            • Tatum: How To Mint NFTs on Solana with Tatum
          • Tezos
            • Tezos: Create an NFT on the Tezos Network using IPFS on Filebase
          • thirdweb
            • thirdweb: Build an NFT Loot Box with thirdweb and IPFS
            • thirdweb: Build an NFT Minting Page with thirdweb, IPFS, RainbowKit, and WAGMI
            • thirdweb: Create a Discord Bot That Gives Roles to NFT Holders
            • thirdweb: Create a Gated Website Using NFTs and IPFS
            • thirdweb: Create an NFT Marketplace with thirdweb and IPFS
            • thirdweb: Release an NFT Drop Using thirdweb and IPFS
          • useDApp
            • useDApp: Create a dApp using useDApp and IPFS
          • Unstoppable Domains
            • Unstoppable Domains: Create a Decentralized Website Using Unstoppable Domains and IPFS Folders
            • Unstoppable Domains: Deploy a Decentralized Blog Using Unstoppable Domains, Akash, and IPFS
            • Unstoppable Domains: IPFS Configuration
          • Vultr
            • Vultr: Store Bedrock Minecraft Worlds on Decentralized Storage
            • Vultr: Store Forge Minecraft Worlds on Decentralized Storage
            • Vultr: Store PaperSpigot Minecraft Worlds on Decentralized Storage
            • Vultr: Store Vanilla Minecraft Worlds on Decentralized Storage
          • Waffle
            • Waffle: Deploy a Smart Contract with Waffle That’s Stored on IPFS
          • Walt.id
            • Walt.id: Mint an NFT with Walt.id and Filebase
          • Web3 Toolbox
            • Web3 Toolbox: Building an NFT Drop With Web3 Toolbox
Powered by GitBook
On this page
  • What is the IPFS Pinning Service API?
  • API Endpoint
  • Authentication
  • Payload
  • List pinned objects
  • Pin an object
  • Get pinned object
  • Replace pinned object
  • Remove pinned object

Was this helpful?

  1. API Documentation

IPFS Pinning Service API

Learn how to programmatically use the IPFS Pinning Service API with Filebase.

PreviousFilebase Platform APIsNextCode Development

Last updated 9 months ago

Was this helpful?

What is the IPFS Pinning Service API?

The IPFS Pinning Service API is a standardized API for re-pinning existing IPFS CIDs. It is often referred to as "remote" pinning or the IPFS "PSA". The IPFS PSA is used by both the IPFS CLI and IPFS Desktop application.

The IPFS development team tracks the compliance of each provider that supports the IPFS PSA to validate each implementation. Filebase is fully compliant with the IPFS PSA requirements. The official compliance report can be seen .

Filebase supports the IPFS Pinning Service API through our service. This API can be used to view pinned objects, add a new object to be pinned, or remove a pinned object.

The IPFS Pinning Service API has an effective rate limit of 100 RPS per IP address.

To interact with the Filebase IPFS Pinning Service API, use the following information below.

API Endpoint

https://api.filebase.io/v1/ipfs/pins

Authentication

To authenticate with the IPFS Pinning Service API, a token is required to be sent with each request in the HTTP headers, using the following format:

  • Authorization: Bearer <access-token>

The access-token can be generated by navigating to the , then viewing the IPFS Pinning Service API Endpoint. Click the drop down menu for 'Choose Bucket to Generate Token', then choose the IPFS Filebase Bucket you want to use.

Then copy the generated Secret Access Token:

Payload

Request Body Schema: application/json

To interact with the IPFS Pinning Service API, you need to send a payload in the form of JSON to the API URL. The following is an example of a POST payload:

{
  "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
  "name": "image3",
  "meta": {
    "key_name": "value_name"
  }
}

All parameters listed in the following API methods are JSON fields in the payload.

List pinned objects

GET https://api.filebase.io/v1/ipfs/pins

List all pinned objects; supports optional filters, if no filter is provided all successful pins are returned.

Query Parameters

Name
Type
Description

cid

Array

Returns pinned objets matching specified filters. Limit of 2000 characters per URL in browser contexts. Example: cid=Qm1 , bafy2 , Qm3

name

String

Return pinned objects with a specific name. Default matching strategy is case-sensitive, exact match. Example: name=ExampleObject.pdf

match

String

Customize the text matching strategy applied to the name filter. Default matching strategy is case-sensitive, exact match. Other options are partial matches, case-insensitive exact (iexact)and case-insensitive partial (ipartial) matches.

Options: "exact" "iexact" "partial" "ipartial"

Example: match=iexact

status

Array

Return pinned objects matching a specified status.

Options: "queued" "pinning" "pinned" "failed"

Example: status=queued,failed

before

String

Return pinned objects queued before the provided timestamp.

Example: before=2022-02-09T12:12:02Z

after

String

Return pinned objects queued after the provided timestamp.

Example: after=2022-02-09T12:12:02Z

limit

Integer

Maximum amount of results to return.

Default: 10

Example: limit=20

meta

Object

Return pinned objects that match specified metadata values passed using a string representation of a JSON object. If using a client library, encode the parameter to ensure secure transmission.

Example: meta={"object_id": "99999"}

{
  "count": 1,
  "results": [
    {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane",
        "name": "nft-collection",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
      }
    }
  ]
}
{
  "error": {
    "reason": "BAD_REQUEST",
    "details": "Detailed explanation of bad request"
  }
}
{
  "error": {
    "reason": "UNAUTHORIZED",
    "details": "Access token is missing or invalid"
  }
}
{
  "error": {
    "reason": "NOT_FOUND",
    "details": "The specified resource was not found"
  }
}
{
  "error": {
    "reason": "NAMING CONFLICT",
    "details": "Unable to process request due to object naming conflict."
  }
}
{
 {
  "error": {
    "reason": "INTERNAL_SERVER_ERROR",
    "details": "Detailed explanation of internal server error"
  }
}

Pin an object

POST https://api.filebase.io/v1/ipfs/pins

Add a new object to be pinned on IPFS.

Request Body

Name
Type
Description

cid*

String

CID to be pinned to IPFS.

name

String

Optional human-readable name to be associated with the pinned CID.

Less than or equal to 255 characters.

origins

Array

List of multi addresses known to provide the CID's data.

meta

Object

Optional metadata to be associated with the pinned CID.

 {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane",
        "name": "nft-collection",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
  }
{
  "error": {
    "reason": "BAD_REQUEST",
    "details": "Detailed explanation of bad request"
  }
}
{
  "error": {
    "reason": "UNAUTHORIZED",
    "details": "Access token is missing or invalid"
  }
}
{
  "error": {
    "reason": "NOT_FOUND",
    "details": "The specified resource was not found"
  }
}
{
  "error": {
    "reason": "NAMING CONFLICT",
    "details": "Unable to process request due to object naming conflict."
  }
}
{
  "error": {
    "reason": "INTERNAL_SERVER_ERROR",
    "details": "Detailed explanation of bad request"
  }
}

Get pinned object

GET https://api.filebase.io/v1/ipfs/pins/{requestid}

Get a pinned object's information and status.

Path Parameters

Name
Type
Description

requestid*

String

 {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane",
        "name": "nft-collection",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
  }
{
  "error": {
    "reason": "BAD_REQUEST",
    "details": "Detailed explanation of bad request"
  }
}
{
  "error": {
    "reason": "UNAUTHORIZED",
    "details": "Access token is missing or invalid"
  }
}
{
  "error": {
    "reason": "NOT_FOUND",
    "details": "The specified resource was not found"
  }
}
{
  "error": {
    "reason": "NAMING CONFLICT",
    "details": "Unable to process request due to object naming conflict."
  }
}
{
  "error": {
    "reason": "INTERNAL_SERVER_ERROR",
    "details": "Detailed explanation of bad request"
  }
}

Replace pinned object

POST https://api.filebase.io/v1/ipfs/pins/{requestid}

Replace an existing pinned object. This can be used as a shortcut for running remove and add operations separately for recursive pins.

Path Parameters

Name
Type
Description

requestid*

String

Request Body

Name
Type
Description

cid*

String

CID to be pinned to IPFS.

name

String

Optional human-readable name to be associated with the pinned CID.

Less than or equal to 255 characters.

origins

Array

List of multi addresses known to provide the CID's data.

meta

String

Optional metadata to be associated with the pinned CID.

 {
      "requestid": "UniqueIdOfPinRequest",
      "status": "queued",
      "created": "2022-02-09T12:12:02Z",
      "pin": {
        "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane",
        "name": "nft-collection",
        "origins": [
          "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId",
          "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId"
        ],
        "meta": {
          "object_id": "99999"
        }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": {
        "status_details": "Queue position: 1 of 1"
  }
{
  "error": {
    "reason": "BAD_REQUEST",
    "details": "Detailed explanation of bad request"
  }
}
{
  "error": {
    "reason": "UNAUTHORIZED",
    "details": "Access token is missing or invalid"
  }
}
{
  "error": {
    "reason": "NOT_FOUND",
    "details": "The specified resource was not found"
  }
}
{
  "error": {
    "reason": "NAMING CONFLICT",
    "details": "Unable to process request due to object naming conflict."
  }
}
{
  "error": {
    "reason": "INTERNAL_SERVER_ERROR",
    "details": "Detailed explanation of bad request"
  }
}

Remove pinned object

DELETE https://api.filebase.io/v1/ipfs/pins/{requestid}

Remove a pinned object.

Path Parameters

Name
Type
Description

requestid*

String

No body, pin is removed. 
{
  "error": {
    "reason": "BAD_REQUEST",
    "details": "Detailed explanation of bad request"
  }
}
{
  "error": {
    "reason": "UNAUTHORIZED",
    "details": "Access token is missing or invalid"
  }
}
{
  "error": {
    "reason": "NOT_FOUND",
    "details": "The specified resource was not found"
  }
}
{
  "error": {
    "reason": "NAMING CONFLICT",
    "details": "Unable to process request due to object naming conflict."
  }
}
{
  "error": {
    "reason": "INTERNAL_SERVER_ERROR",
    "details": "Detailed explanation of bad request"
  }
}
here
Filebase Access Keys page
IPFS Re-Pinning