IPFS Pinning Service API: What It Is, Why It Matters

The IPFS Pinning Service API is an open specification that defines one set of HTTP endpoints for adding, checking, and removing pins on any provider. Because AIOZ Pin implements it at api.aiozpin.network/api/psa/, your own Kubo node can pin to AIOZ Pin with the built-in ipfs pin remote commands.

TL;DR:

• The spec (version 1.0.0) defines 5 operations on /pins and /pins/{requestid}, authenticated with a bearer token.
• AIOZ Pin's endpoint is https://api.aiozpin.network/api/psa/. The token is a JWT from AIOZ Pin's email login, not a pinning API key.
• Kubo adds it with ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_JWT, as the AIOZ Pin docs show.
• Pinata implements the same spec at api.pinata.cloud/psa, so basic pin code moves between the two.

Updated Oct 19, 2026: corrected the token type to the JWT the AIOZ Pin docs require. Added the documented login calls, the full ipfs pin remote command set, the PSA rate limit, and a request-flow diagram.

What is the IPFS Pinning Service API?

It's an OpenAPI document kept at github.com/ipfs/pinning-services-api-spec, currently version 1.0.0. The spec calls itself an "implementation-agnostic API" for two audiences: pinning providers who implement it, and IPFS nodes or apps that call it as clients. Since it's machine-readable, client libraries can be generated from it directly.

It defines 5 operations:

Every request carries Authorization: Bearer <access-token>. The spec says the token should be generated per device, and that you should be able to revoke each token on its own.

A pin request holds the cid you want kept, plus optional name, origins, and meta fields. The origins list tells the provider which peers already have the data, so it can connect to them directly instead of searching the DHT first.

What do the pin statuses mean?

Pinning isn't instant, because the provider may have to fetch every block of your CID from the network first. So each pin you add returns a requestid and one of four statuses:

• queued: the request is in line, and the provider isn't spending resources on it yet.
• pinning: the provider is finding peers that hold the blocks and downloading them.
• pinned: every block is stored.
• failed: the provider couldn't retrieve the data.

You poll GET /pins/{requestid} until the status is pinned or failed. A pin that sits in pinning for a long time usually means no reachable peer has the blocks. Our guide to stuck pins covers the usual causes.

Why Kubo depends on the standard

The standard is what makes one built-in command work with every provider. Kubo, the reference IPFS implementation, ships ipfs pin remote, and the IPFS docs show the generic form:

ipfs pin remote service add <nickname> <endpoint> <accessToken>

The IPFS docs put it plainly: "Your service must use the IPFS Pinning Service API in order to be interoperable with clients using ipfs pin remote commands." Without the spec, you'd need a separate plugin or script for each provider. With it, you add a nickname, an endpoint, and a token, and your node can pin anywhere that speaks the API.

How do you add AIOZ Pin as a remote pinning service?

You need two things: a JWT access token and the endpoint https://api.aiozpin.network/api/psa/. The token matters here. The pinning API key and secret you use with the REST API won't work, because the PSA endpoint expects the JWT from AIOZ Pin's email login.

Getting the JWT takes two calls. First you request a login code by email, then you exchange the code for an access token. This is the example from the AIOZ Pin Pinning Services API docs:

async function requestLoginCode(email: string) {
  const res = await fetch(`https://api.aiozpin.network/api/auth/email_login/${encodeURIComponent(email)}`)
  return res.json()
}

async function login(email: string, code: string) {
  const res = await fetch('https://api.aiozpin.network/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, code })
  })
  return res.json()
}

const result = await login('[email protected]', '123456')
// result.access_token  - JWT for PSA and admin operations
// result.refresh_token

With the token, you add AIOZ Pin to Kubo and use the standard commands. These are exactly as the AIOZ Pin docs show them. We didn't run them for this article, since this machine has no IPFS binary.

# Add AIOZ Pin as a remote service
ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_JWT

# Pin a CID
ipfs pin remote add --service=pin --name=my-file QmYourCIDHere

# List successful pins
ipfs pin remote ls --service=pin

# List pending pins
ipfs pin remote ls --service=pin --status=queued,pinning,failed

# Help
ipfs pin remote --help

Here pin is the nickname you give the service, and you can pick any name. Swap QmYourCIDHere for your own CID, and add --background to ipfs pin remote add if you don't want the command to wait for pinned.

Other providers that implement it

Pinata runs its implementation at api.pinata.cloud/psa. Both providers use a psa path because both implement the same Pinning Service API. The AIOZ Pin vs Pinata comparison covers where they differ: pricing, gateways, and NFT tooling. On the base pinning calls, they're interchangeable.

That matters most when you migrate. If you used a provider that shut down, code written against the spec needs a new endpoint and token, not new pinning logic. The NFT.storage alternatives roundup walks through that case.

How AIOZ Pin handles the Pinning Service API

We expose the spec at https://api.aiozpin.network/api/psa/, next to our own REST API at https://api.aiozpin.network/api. The two use different credentials. PSA calls take the JWT from email login, while REST pinning calls take the pinning_api_key and pinning_secret_key headers.

The PSA list endpoint is limited to 60 requests per minute, according to the AIOZ Pin limit page. Most other API calls get 180 per minute. If you script ipfs pin remote ls in a loop, keep it under that.

Use the REST API or the Node.js SDK when you need AIOZ-specific features: the NFT endpoint, image parameters on the gateway, or billing data. Use PSA when you already run Kubo and want your node to hand pins to us. How AIOZ Pin works shows where each piece fits, and the developer guide compares the API, SDK, and CLI.

The docs show the Kubo commands and the login calls. They don't list which optional spec fields, such as origins or meta, AIOZ Pin acts on.

Next step: read the AIOZ Pin Pinning Services API docs and add the service to your node.

Frequently Asked Questions

What is the IPFS Pinning Service API? It's an open OpenAPI specification, version 1.0.0, that defines 5 endpoints to list, add, get, replace, and remove pins. Any provider can implement it, so clients pin to different services through one interface.

Does AIOZ Pin support the IPFS Pinning Service API? Yes. The AIOZ Pin docs give the endpoint as https://api.aiozpin.network/api/psa/ and show it working with the Kubo ipfs pin remote commands.

How do I add AIOZ Pin as a remote pinning service? Get a JWT through AIOZ Pin's email login, then run ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_JWT. After that, ipfs pin remote add --service=pin pins a CID.

Can I use my AIOZ Pin API key as the PSA token? No. The docs say PSA requires a JWT access token from the email login flow. The API key and secret are for the REST pinning endpoints.

Does Pinata use the same standard? Yes. Pinata's implementation runs at api.pinata.cloud/psa, following the same spec.

What authentication does the Pinning Service API use? A bearer token in the Authorization header. The spec recommends one token per device, so you can revoke each one separately.

Related Reading

• How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - the three components behind the PSA endpoint
• AIOZ Pin vs Pinata - where the two providers differ beyond the shared base API
• Best NFT.storage Alternatives - portability in practice, for anyone leaving a discontinued provider
• Understanding IPFS Pinning Services - what a pinning service does before you get to the API layer
• AIOZ Pin for Developers: API, SDK, and CLI Explained - where PSA fits in the full API surface
• IPFS Pin Stuck on Pinning? What Each Pin Status Means - the status values in more depth

References

• IPFS Pinning Service API spec (GitHub)
• Work with remote pinning services (IPFS Docs)
• AIOZ Pin Pinning Services API documentation
• AIOZ Pin Limit documentation
• Pinata Pinning Service API documentation