IPFS Pinning Service API: What It Is, Why It Matters
The IPFS Pinning Service API is a specification, not a product, and that's exactly why it matters. It defines a fixed set of endpoints that any pinning provider can implement, so a client that speaks the standard can pin files to AIOZ Pin, Pinata, or any other compliant service without custom integration code for each one. AIOZ Pin implements it fully. This article covers what the spec actually defines, why the official IPFS tooling was built around it, and the exact command you'd run to add AIOZ Pin as a remote pinning service on your own node.
TL;DR:
- The IPFS Pinning Service API defines 5 endpoints for adding, checking, and removing pins, secured with a bearer token
- AIOZ Pin implements it at
api.aiozpin.network/api/psa/ - Pinata implements the same standard at
api.pinata.cloud/psa - IPFS's own Kubo client can talk to either through the same built-in command
What the IPFS Pinning Service API Actually Defines
The spec's own repository describes it as a "standalone, vendor-agnostic Pinning Service API for IPFS ecosystem," maintained at github.com/ipfs/pinning-services-api-spec and currently at version 1.0.0. It's an OpenAPI specification, meaning it's a formal, machine-readable contract, not just a style guide. The spec's own description calls it "an implementation-agnostic API for use and implementation by pinning service providers and client mode by IPFS nodes and GUI-based applications."
Concretely, it defines 5 operations:
| Endpoint | Method | Purpose |
|---|---|---|
/pins |
GET | List your current pins |
/pins |
POST | Add a new pin |
/pins/{requestid} |
GET | Check a specific pin's status |
/pins/{requestid} |
POST | Replace a pin |
/pins/{requestid} |
DELETE | Remove a pin |
Every request authenticates with a bearer token in the header, Authorization: Bearer <access-token>, and the spec explicitly recommends generating a separate token per device so you can revoke access individually rather than rotating one shared secret everywhere.
Why It Exists: One Command, Any Provider
The standard's real purpose shows up in IPFS's own Kubo client. The official IPFS docs describe adding a remote pinning service with one command:
ipfs pin remote service add <nickname> <endpoint> <accessToken>
The docs are direct about why this only works because of the standard: "Your service must use the IPFS Pinning Service API in order to be interoperable with clients using [ipfs pin remote] commands." That's the actual value of the spec. It's not a nice-to-have compatibility layer, it's the specific mechanism that lets your local IPFS node pin to any conforming remote service through one built-in command, instead of needing a provider-specific plugin or script for each one.
How to Add AIOZ Pin as a Remote Pinning Service
AIOZ Pin's implementation of the spec lives at https://api.aiozpin.network/api/psa/. After generating an API key from the AIOZ Pin dashboard, adding it to a local Kubo node looks like this:
ipfs pin remote service add aiozpin https://api.aiozpin.network/api/psa/ <your-api-key>
From there, ipfs pin remote add and ipfs pin remote ls work against AIOZ Pin the same way they'd work against any other compliant service, no AIOZ-specific tooling required for the basic pin/list/remove operations. AIOZ Pin's own SDK and CLI (covered in How AIOZ Pin Works) add convenience methods like pinNft() on top of this, but the base pinning operations run on the same standard as everything else.
Who Else Implements This Standard
Pinata runs its own implementation at api.pinata.cloud/psa, the same psa naming AIOZ Pin uses for its endpoint, since both are pointing at the same "Pinning Services API" the path abbreviates. That's not a coincidence, it's what happens when two providers implement the same spec rather than inventing their own. The AIOZ Pin vs Pinata comparison covers where the two actually differ, pricing, gateways, NFT tooling, but on the base pinning API itself, they're deliberately interchangeable.
Portability in Practice
The practical test of a standard is whether you can actually rely on it, not whether it exists on paper. Because both AIOZ Pin and Pinata implement the same 5 endpoints and the same bearer-token auth, a script or app built against one needs an endpoint URL and an API key changed to point at the other, not new pinning logic written from scratch. That matters most if you're migrating off a discontinued service. The NFT.storage alternatives roundup covers exactly that situation, where the standard is what makes trying a new provider a low-cost decision instead of a rewrite.
Frequently Asked Questions
What is the IPFS Pinning Service API? It's a vendor-agnostic OpenAPI specification that defines 5 standard endpoints (list, add, get status, replace, and remove pins) that any pinning provider can implement, so clients can pin to different services through the same interface.
Does AIOZ Pin support the IPFS Pinning Service API? Yes, fully. AIOZ Pin's implementation is reachable at api.aiozpin.network/api/psa/ and supports all 5 standard endpoints.
How do I add AIOZ Pin as a remote pinning service in IPFS? Run ipfs pin remote service add aiozpin https://api.aiozpin.network/api/psa/ <your-api-key> from the Kubo CLI, using an API key generated from your AIOZ Pin dashboard.
Why does this standard matter? It's what lets IPFS's own built-in ipfs pin remote commands work with any compliant provider without custom code per service, and it's what makes switching providers a configuration change rather than a rewrite.
Does Pinata use the same standard as AIOZ Pin? Yes. Pinata's implementation runs at api.pinata.cloud/psa, following the same specification AIOZ Pin implements at api.aiozpin.network/api/psa/.
What authentication does the IPFS Pinning Service API use? A bearer token sent in the request header (Authorization: Bearer <access-token>), with the spec recommending a separate token per device so access can be revoked individually.
Related Reading
- How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - the full mechanics of AIOZ Pin's three components, including its SDK built on top of this standard
- AIOZ Pin vs Pinata: IPFS Pinning Service Compared 2026 - where the two providers actually differ, beyond the shared base API
- Best NFT.storage Alternatives in 2026 (Featuring AIOZ Pin) - portability in practice, for anyone migrating off a discontinued provider
References
Related Content
How IPFS Splits Files: Fixed vs. Content-Defined Chunking
IPFS defaults to 256 KiB fixed-size chunks, but also ships Rabin and Buzhash content-defined chunkers. Here is why the choice affects deduplication.
Anatomy of a CID: Decoding an IPFS Identifier
An IPFS CID is not a random string. It encodes a version, a codec, and a hash algorithm plus digest. Here is how to decode a real CID piece by piece.
How IPFS Shards Large Directories: The HAMT, Not a B-Tree
IPFS does not use a B-tree for large directories. It uses a HAMT, a Hash Array Mapped Trie. Here is exactly how it shards a folder once it outgrows one block.
How to Resize Images on AIOZ Pin Using URL Parameters
AIOZ Pin image resizing happens straight in the gateway URL, no upload step or separate service. Here is every img- parameter, with real srcset examples.
How x402 Payments Weight AI Agent Reputation on ERC-8004
x402 payments let ERC-8004 weight a paid AI agent interaction more heavily than free work in its reputation score. Here is exactly how that link works.
How to Automate NFT Pinning with the AIOZ Pin NFT API
AIOZ Pin NFT API calls pin an asset and its metadata as two tracked pins under one record. Here is how to automate it directly over REST, no SDK needed.