canonical: https://jentic.com/apis/filebase.com/filebase

# Filebase IPFS Pinning Service API

The Filebase IPFS Pinning Service API pins existing IPFS content by CID into a Filebase IPFS bucket and tracks each pin request through to completion. Pinning is asynchronous: creating or replacing a pin returns a request you poll until its status is pinned or failed, keeping the source content reachable in the meantime. A bucket-specific Bearer token authorises each call and a paid account is required. The request identifier it returns is an opaque handle, not a CID or a UUID, and any content pinned on IPFS is public to anyone who has the CID.

## For AI agents

Pin existing IPFS content by CID into a Filebase bucket, list and poll pin requests until they are pinned or failed, and replace or remove a pin. Works against the IPFS Pinning Service standard.

## Scope

Does not handle file upload, gateway serving, or IPFS content creation. Use for pinning existing IPFS content by CID into a Filebase bucket only.

## Capabilities

- Pin an existing IPFS CID into a Filebase IPFS bucket
- List pin requests and filter them by status
- Get a pin request and poll its status until it is pinned or failed
- Replace the CID behind an existing pin request
- Remove a pin request to stop pinning that content

## Use cases

### Agent-managed IPFS pinning through Jentic

An AI agent pins a CID produced elsewhere, receives a request handle, and polls it until the status turns pinned, so content stays reachable on IPFS without a person watching the queue. Because pinning is asynchronous, the agent can pin a batch, then revisit each request's status and retry any that failed.

Example prompt: Pin a given CID into a Filebase bucket, then poll the returned request until its status is pinned or failed

### Keep published content reachable

Apps that reference content by CID need that content to stay available. The API pins the CID into a Filebase bucket and reports when the pin is complete, so a publishing workflow can confirm durability before it hands a gateway link to users, and unpin content it no longer needs.

Example prompt: List pin requests filtered to failed status and replace each one with its intended CID

### Audit and clean up pins

Over time a bucket accumulates pins that are no longer referenced. The API lists pin requests and their statuses so an agent can report what is pinned, then remove the requests that are stale, freeing paid storage without touching content that is still in use.

Example prompt: List all pin requests, identify ones not in an active set, and remove each stale pin request

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/pins` | List pin requests |
| POST | `/pins` | Pin an existing CID |
| GET | `/pins/{requestid}` | Get a pin request and its status |
| POST | `/pins/{requestid}` | Replace a pin request |
| DELETE | `/pins/{requestid}` | Remove a pin request |

## Key resources

- **Pins** — Add, list, get, replace, and remove IPFS pin requests, each tracked by an opaque request handle

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 79 / 100
- **Maturity:** AI-Ready
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 85 / 100
  - AI-Readiness & Agent Experience: 69 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/filebase.com/filebase/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Filebase pinning API by hand means generating a bucket-specific Bearer token, handling the asynchronous poll until a pin is complete, and remembering the request handle is opaque rather than a CID. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** A Filebase token is already scoped to one bucket, and on top of that you choose which operations your agent may call, so it can add and list pins while the replace and remove operations stay out unless you add them.
- **Credential handling:** Your Filebase bucket token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'pin an IPFS CID' or 'check a pin's status', and Jentic returns the matching Filebase operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Pinata** — Pinata is another IPFS pinning service, an alternative to Filebase for keeping content available on IPFS.
- **Storj** — Storj offers decentralized object storage, an alternative storage layer to Filebase's IPFS pinning.
- **Backblaze B2** — Backblaze B2 stores original files that can later be pinned to IPFS through Filebase.

## FAQ

### What authentication does the Filebase IPFS Pinning Service API use?

It uses a bucket-specific Bearer token sent in the Authorization header, generated in the Filebase console, per its OpenAPI spec. Because the token is tied to one bucket, a call only ever touches that bucket's pins, and a paid account is required.

### How do I know when a pin is complete with the Filebase API?

Pinning is asynchronous. Creating or replacing a pin returns a request with an opaque identifier, and you poll that request until its status reads pinned or failed. Keep the source content reachable until the status is pinned, because the service fetches the CID during that window.

### What are the rate limits for the Filebase IPFS Pinning Service API?

The OpenAPI spec does not state a request rate limit. A paid account is required, and limits track your plan, so check the Filebase documentation for the current ceilings before pinning at scale.

### Is there a Filebase MCP server?

You don't need an MCP server to give your agent the Filebase pinning API. Jentic connects it directly from the API Directory: import it, store your bucket token once, and your agent calls the pin, status, replace, and remove operations on demand.

### Can I limit what my agent is allowed to do with the Filebase API?

Yes. A Filebase token is already scoped to one bucket, and on top of that you can write a rule that allows only the add-pin and list operations, leaving the replace and remove operations off unless you add them, so an agent can pin and report without unpinning anything. Every call it makes is recorded in your Jentic One audit log.

### How do I pin a CID with the Filebase API through Jentic?

Search Jentic for 'pin an IPFS CID', add the Filebase IPFS Pinning Service API from the directory, and store your bucket token once; your agent then pins the CID and polls the returned request until it is complete. To run it on your own infrastructure, install Jentic One from its GitHub repo.