Skip to main content

IPFS Pinning Service API

Legacy: This page documents Filebase's IPFS tier. For new deployments, use the S3-compatible object storage tier with the s3.filebase.io endpoint.

The IPFS Pinning Service API is a vendor-neutral spec for remote pinning services. Filebase is fully compliant with the spec — any tool that supports remote pinning (the IPFS CLI, IPFS Desktop, custom clients) can target Filebase as the remote.

Base URL​

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

Authentication​

Generate a per-bucket access token in the Access Keys page (look for IPFS Pinning Service API Endpoint → Choose Bucket to Generate Token).

Authorization: Bearer <access-token>

Rate limit​

100 RPS per IP address.

Endpoints​

List pins​

GET /v1/ipfs/pins

Query params: cid, name, match (exact, iexact, partial, ipartial), status (queued, pinning, pinned, failed), limit, before, after.

curl -H "Authorization: Bearer $TOKEN" \
  https://api.filebase.io/v1/ipfs/pins

Create a pin​

POST /v1/ipfs/pins
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "QmExample...",
    "name": "my-pin",
    "meta": { "project": "demo" }
  }' \
  https://api.filebase.io/v1/ipfs/pins

Get a pin record​

curl -H "Authorization: Bearer $TOKEN" \
  https://api.filebase.io/v1/ipfs/pins/<request-id>

Replace a pin​

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cid": "<NEW-CID>", "name": "my-pin" }' \
  https://api.filebase.io/v1/ipfs/pins/<request-id>

Delete a pin​

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://api.filebase.io/v1/ipfs/pins/<request-id>

IPFS CLI as a client​

# Add Filebase as a pinning service
ipfs pin remote service add filebase \
  https://api.filebase.io/v1/ipfs $TOKEN

# Pin a CID
ipfs pin remote add --service=filebase --name=my-pin <CID>

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

# Remove a pin
ipfs pin remote rm --service=filebase --cid=<CID>

What's next​