IPFS Pinning Service API

The IPFS Pinning Service API is a standardized, vendor-neutral API for re-pinning existing IPFS CIDs. It's often called "remote" pinning, or the IPFS "PSA", and is used by both the IPFS CLI and the IPFS Desktop application.

The IPFS team tracks the compliance of every provider that implements the PSA. Filebase is fully compliant — the official compliance report is published for api.filebase.io. Use this API to list pinned objects, add a new object to pin, replace a pin, or remove one.

Base URL

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

info

When registering Filebase as a remote pinning service in the IPFS CLI or IPFS Desktop, use the service root https://api.filebase.io/v1/ipfs — the client appends /pins itself. See IPFS Desktop and CLI integration.

Authentication

The API uses token-based authentication. Generate a per-bucket access token, then send it as a Bearer token on every request:

Authorization: Bearer <access-token>

To generate a token:

1. Log in to the Filebase Console.
2. Open the Access Keys page.
3. Find the IPFS RPC API endpoint section.
4. Select Choose Bucket to Generate Token and pick the bucket to pin to.
5. Copy the generated Secret Access Token.

The examples below use a $TOKEN shell variable in place of your access token:

export TOKEN="<your-access-token>"

Rate limit

100 requests per second.

Request payload

Request bodies are JSON (Content-Type: application/json). All parameters listed for the methods below are JSON fields in the payload, for example:

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

Endpoints

List pins

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

GET /v1/ipfs/pins

Query parameters:

Parameter	Type	Description
cid	array	Filter by one or more CIDs, comma-separated (limit 2000 characters per URL in browser contexts). Example: cid=Qm1,bafy2,Qm3.
name	string	Filter by pin name. Default matching is case-sensitive and exact. Example: name=ExampleObject.pdf.
match	string	Name match strategy: exact, iexact, partial, ipartial. Example: match=iexact.
status	array	Filter by status: queued, pinning, pinned, failed. Example: status=queued,failed.
before	string	Return pins queued before this ISO 8601 timestamp. Example: before=2022-02-09T12:12:02Z.
after	string	Return pins queued after this ISO 8601 timestamp. Example: after=2022-02-09T12:12:02Z.
limit	integer	Maximum number of results to return. Default: 10. Example: limit=20.
meta	object	Filter by metadata, passed as a JSON string. Encode the value if using a client library. Example: meta={"object_id":"99999"}.

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

A 200 OK response returns a PinResults object:

{
  "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"
        ],
        "meta": { "object_id": "99999" }
      },
      "delegates": [
        "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
      ],
      "info": { "status_details": "Queue position: 1 of 1" }
    }
  ]
}

Create a pin

Add a new object to be pinned on IPFS.

POST /v1/ipfs/pins

Request body:

Field	Type	Required	Description
cid	string	Yes	CID to pin to IPFS.
name	string	No	Human-readable name for the pin (≤ 255 characters).
origins	array	No	List of multiaddrs known to provide the CID's data.
meta	object	No	Metadata key-value pairs to associate with the pin.

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"

A 202 Accepted response returns a PinStatus object:

{
  "requestid": "UniqueIdOfPinRequest",
  "status": "queued",
  "created": "2022-02-09T12:12:02Z",
  "pin": {
    "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane",
    "name": "my-pin",
    "origins": [],
    "meta": { "project": "demo" }
  },
  "delegates": [
    "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId"
  ],
  "info": { "status_details": "Queue position: 1 of 1" }
}

Get a pin record

Get a pinned object's information and status by its request ID.

GET /v1/ipfs/pins/{requestid}

Path parameter: requestid (string, required) — the ID returned when the pin was created.

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

Returns a PinStatus object (same shape as the Create a pin response).

Replace a pin

Replace an existing pinned object. This is a shortcut for removing and re-adding a recursive pin in one call — the original pin is removed once the new CID is pinned.

POST /v1/ipfs/pins/{requestid}

Path parameter: requestid (string, required).

Request body:

Field	Type	Required	Description
cid	string	Yes	New CID to pin to IPFS.
name	string	No	Human-readable name for the pin (≤ 255 characters).
origins	array	No	List of multiaddrs known to provide the CID's data.
meta	object	No	Metadata key-value pairs to associate with the 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>"

A 202 Accepted response returns the updated PinStatus object.

Delete a pin

Remove a pinned object by its request ID.

DELETE /v1/ipfs/pins/{requestid}

Path parameter: requestid (string, required).

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

A 202 Accepted response has no body — the pin is removed.

Error responses

Errors return the appropriate HTTP status code and a JSON body describing the failure:

{
  "error": {
    "reason": "BAD_REQUEST",
    "details": "Detailed explanation of the error"
  }
}

Status	Reason	Meaning
400	BAD_REQUEST	The request was malformed.
401	UNAUTHORIZED	The access token is missing or invalid.
404	NOT_FOUND	The specified resource was not found.
409	NAMING CONFLICT	The request conflicts with an existing object name.
500	INTERNAL_SERVER_ERROR	An unexpected server error occurred.

Pinning metadata

The meta object lets you attach arbitrary key-value pairs to a pin when creating or replacing it — useful for tracking the project, environment, or any other context a pin belongs to. You can later filter List pins results by metadata using the meta query parameter.

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

IPFS Desktop and CLI integration

Use Filebase as a remote pinning service from IPFS Desktop or the IPFS CLI. Register the service with the service root URL and your access token:

# 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

• IPFS RPC API
• Pinning files