llms.txt
Compare with other sites' llms.txt files →# Filebase
> Filebase provides IPFS storage and pinning, dedicated IPFS gateways and CDN delivery, IPNS names, static website hosting on IPFS, NFT Backup, and general-purpose S3-compatible object storage. Use the guidance below to choose an interface, configure authentication, and find the relevant Filebase documentation.
Use `https://s3.filebase.io` with region `auto` for all S3 workflows, including IPFS-backed buckets. This is the recommended S3 configuration even where older documentation examples differ. The bucket type determines the storage behavior: choose an IPFS bucket for CIDs and pinning, or an object-storage bucket for general-purpose storage and private application data.
**When to use Filebase**
- Store application files, backups, or private data with the S3 API and an object-storage bucket. Use server-generated presigned URLs for direct browser uploads and downloads.
- Upload new content that needs an IPFS CID with S3 and an IPFS bucket. Filebase automatically pins the upload; retrieve its CID from object metadata.
- Retain content that already has a CID with the Pinning Service API. Submit a pin request, then poll its request ID until it is pinned or failed.
- Import a CAR, upload a directory, manage MFS paths, or use Kubo-compatible key and name operations with the supported IPFS RPC methods.
- Publish changing content under one stable address with IPNS. Pin the new content first, then update the name using the Platform API or RPC.
- Deliver IPFS or IPNS content to web clients through a gateway. Use a dedicated gateway for production delivery, custom domains, access controls, and image optimization.
- Host a static website on IPFS with Filebase Sites. Use its deployment workflow and custom-domain support; Sites does not run a server-side application.
**Interfaces and authentication**
| Interface | Endpoint | Authentication and purpose |
| --- | --- | --- |
| S3 API | `https://s3.filebase.io` | AWS Signature Version 4 (SigV4), region `auto`, and a Filebase access key ID / secret access key. Upload, download, list, and manage objects using AWS SDKs or S3-compatible tools. |
| IPFS Pinning Service API | `https://api.filebase.io/v1/ipfs/pins` | `Authorization: Bearer <bucket-access-token>`. Pin existing CIDs and manage asynchronous pin requests. |
| IPFS RPC API | `https://rpc.filebase.io/api/v0/` | `Authorization: Bearer <bucket-access-token>`. Every supported RPC method uses POST. Upload files, import CAR archives, work with the Mutable File System (MFS), manage keys, and publish or resolve IPNS. |
| Platform API | `https://api.filebase.io/v1/` | `Authorization: Bearer <base64-of-access-key:secret-key>`. Account usage, managed IPNS names, and gateway management. This account-derived credential is different from a bucket's IPFS access token. |
| Public IPFS gateway | `https://ipfs.filebase.io` | HTTP retrieval at `/ipfs/<CID>/<optional-path>` or `/ipns/<IPNS-name>/<optional-path>`. Intended for testing and light usage; use a dedicated gateway for production delivery. |
| Dedicated IPFS gateway | `https://<gateway-name>.myfilebase.com` | HTTP retrieval with the gateway's configured scope and access controls. Supports custom domains. |
Get Filebase access keys from the console. For pinning and RPC, generate an IPFS token for the destination bucket in the console's Access Keys page. S3 clients sign requests with the access key pair; do not substitute an IPFS Bearer token for S3 credentials. Keep credentials in environment variables or a secrets manager and generate presigned URLs on the server for browser clients.
**IPFS concepts and operational behavior**
- A CID identifies immutable content. A directory has a root CID and paths beneath it. Use `ipfs://<CID>/<path>` for native IPFS references or an HTTP gateway for ordinary browsers.
- CID generation depends on the content and its directed acyclic graph (DAG) encoding, including chunking and directory wrapping. A CID is not generally the SHA256 of the original file bytes. Prefer CIDv1 for new integrations, especially subdomain gateways.
- Pinning retains content on Filebase's IPFS nodes. Uploads to an IPFS bucket are automatically pinned. To retain an existing CID, use the Pinning Service API or a supported RPC pin operation; a gateway fetch alone is not a pin request.
- Treat IPFS content as public to anyone who has its CID. A private S3 bucket ACL or a restricted gateway controls that access path, not access through other IPFS peers. Gateway private mode means it serves only content pinned to your account; it does not make the underlying content confidential.
- Deleting an IPFS object unpins it from Filebase. Other peers may retain copies; unpinning is not network-wide deletion.
- IPNS provides a stable name whose signed record can point to a new CID. Updates are subject to resolver caching and propagation, so clients may briefly see an older value. Preserve the key associated with the name across updates.
- Filebase supports a documented subset of Kubo RPC. Check the RPC reference before assuming a Kubo command or flag is available.
- Bitswap exchanges blocks with other IPFS peers. Trustless gateway responses allow clients to verify returned blocks against the requested CID.
- IPFS bandwidth is accounted for separately from general object storage, despite the shared recommended S3 endpoint. IPFS S3 reads, dedicated and public gateways, Bitswap, trustless retrieval, RPC, and Sites contribute to IPFS outbound usage. Consult current pricing and plan limits; do not apply general object-storage free-egress claims to IPFS.
**Upload a new file and retrieve its CID**
Select an IPFS bucket and configure the AWS CLI with your Filebase access key pair (for example through `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`). Replace `YOUR_IPFS_BUCKET` with that bucket's name:
```bash
aws --endpoint-url https://s3.filebase.io --region auto \
s3 cp ./hello.txt s3://YOUR_IPFS_BUCKET/hello.txt
aws --endpoint-url https://s3.filebase.io --region auto \
s3api head-object --bucket YOUR_IPFS_BUCKET --key hello.txt \
--query 'Metadata.cid' --output text
```
The IPFS CID is exposed in the `x-amz-meta-cid` response header (the SDK's `Metadata.cid`). Retrieve it with `HeadObject` after upload, then fetch `https://ipfs.filebase.io/ipfs/<CID>` or your dedicated gateway URL. General object-storage buckets expose SHA256 checksums instead of IPFS CIDs.
To upload through RPC, use `POST /api/v0/add` with multipart form field `file`. Request `cid-version=1` when needed and `wrap-with-directory=true` when the result should be a directory containing the uploaded files.
**Pin an existing CID and wait for completion**
Set `FILEBASE_IPFS_TOKEN` to the destination bucket's IPFS access token. Replace `<CID>` with an existing CID whose content is available from IPFS peers:
```bash
curl --fail-with-body --silent --show-error \
-X POST https://api.filebase.io/v1/ipfs/pins \
-H "Authorization: Bearer $FILEBASE_IPFS_TOKEN" \
-H "Content-Type: application/json" \
--data '{"cid":"<CID>","name":"my-pin"}'
```
The API returns `202 Accepted` with a `requestid` and status. Acceptance does not mean the pin is complete. Use the returned request ID, not the CID, to check its status:
```bash
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $FILEBASE_IPFS_TOKEN" \
"https://api.filebase.io/v1/ipfs/pins/<REQUEST_ID>"
```
Wait through `queued` and `pinning` until `pinned`; handle `failed` as a failure and inspect the returned details. Keep the source content reachable while pinning. The optional `origins` field can identify source peers. List pins with `GET /pins`, using the documented status filters and pagination rather than assuming the first response is complete. Replace a pin with `POST /pins/<REQUEST_ID>` and delete it with `DELETE /pins/<REQUEST_ID>` under the same `/v1/ipfs` base. Pin lifecycle notifications are also available.
When registering Filebase with IPFS Desktop or the IPFS CLI, use the service root `https://api.filebase.io/v1/ipfs`; the client appends `/pins` itself:
```bash
ipfs pin remote service add filebase \
https://api.filebase.io/v1/ipfs "$FILEBASE_IPFS_TOKEN"
```
**Import a directory or CAR archive**
Package a directory as a CAR (Content Addressable aRchive) with an IPFS-aware tool. Import its DAG into an IPFS bucket rather than storing the archive as an ordinary file:
```bash
aws --endpoint-url https://s3.filebase.io --region auto \
s3 cp ./site.car s3://YOUR_IPFS_BUCKET/site.car --metadata 'import=car'
```
Read the imported root CID from the object's CID metadata. Alternatively, use `POST https://rpc.filebase.io/api/v0/dag/import` with the bucket token and multipart form field `file`; `pin-roots` defaults to `true`. For mutable bucket paths, the supported MFS `files/*` RPC methods manage files and directories, and `files/flush` returns the bucket's current root CID. Consult the RPC reference for supported flags and path rules.
**Publish and update an IPNS name**
Use a managed name through the Platform API (`/v1/names`) or the RPC key/name methods. For the RPC workflow, create a named key once, then publish the pinned content's CID with that same key on each update:
```bash
curl --fail-with-body --silent --show-error -X POST \
-H "Authorization: Bearer $FILEBASE_IPFS_TOKEN" \
"https://rpc.filebase.io/api/v0/key/gen?arg=my-app"
curl --fail-with-body --silent --show-error -X POST \
-H "Authorization: Bearer $FILEBASE_IPFS_TOKEN" \
"https://rpc.filebase.io/api/v0/name/publish?arg=/ipfs/<CID>&key=my-app"
curl --fail-with-body --silent --show-error -X POST \
-H "Authorization: Bearer $FILEBASE_IPFS_TOKEN" \
"https://rpc.filebase.io/api/v0/name/resolve?arg=/ipns/<IPNS_NAME>"
```
Replace `<IPNS_NAME>` with the public network name returned by the API, not the local key label `my-app`. Publish a new CID using the existing key to keep the same public name. Read the content at `https://ipfs.filebase.io/ipns/<IPNS_NAME>`. Consult the IPNS and RPC references for TTL, record validity, key import, and supported options.
**Create a dedicated gateway and deliver content**
Create a gateway in the console or through the Platform API. The following example uses the account access key pair from `FILEBASE_KEY` and `FILEBASE_SECRET`, not the bucket IPFS token. Replace `YOUR_GATEWAY_NAME` with a valid, globally unique gateway name:
```bash
FILEBASE_PLATFORM_TOKEN=$(printf '%s' "$FILEBASE_KEY:$FILEBASE_SECRET" | base64 | tr -d '\r\n')
curl --fail-with-body --silent --show-error \
-X POST https://api.filebase.io/v1/gateways \
-H "Authorization: Bearer $FILEBASE_PLATFORM_TOKEN" \
-H "Content-Type: application/json" \
--data '{"name":"YOUR_GATEWAY_NAME","private":true,"enabled":true}'
```
This gateway serves your account's pinned content at `https://<gateway-name>.myfilebase.com/ipfs/<CID>`. Public mode can retrieve other IPFS content; scope controls can restrict served CIDs. Configure custom domains, authentication, image transformations, and activity logging through the documented gateway features. CIDv1 subdomain gateways provide separate browser origins per CID. For a static website with a stable address across deployments, use Filebase Sites and its managed IPNS name.
**Use general object storage and browser uploads**
Use an object-storage bucket with the same S3 endpoint and region. Keep private data in private buckets; general object-storage public access is controlled at the bucket level. Generate a `PutObject` presigned URL on a trusted server for a browser upload, send the file with HTTP PUT using the signed headers, and configure bucket CORS for the application's origin and required methods. Use a `GetObject` presigned URL for time-limited downloads. Never put the account secret in frontend code.
Use multipart upload for large files, consume all listing pages, and retain normal SDK retries with exponential backoff and jitter for transient errors and `503 SlowDown`. Check the compatibility matrix before relying on AWS-specific functionality: S3 compatibility does not imply support for every AWS S3 operation or IAM feature. General object-storage SHA256 checksums and IPFS CID metadata are different integrity mechanisms.
## Start here
- [Filebase documentation](https://filebase.com/docs/): Main documentation hub for storage, APIs, integrations, and account management.
- [Sign up](https://filebase.com/docs/get-started/sign-up): Create an account and access the console.
- [Filebase Console](https://console.filebase.com): Manage buckets, IPFS pins, gateways, IPNS names, Sites, and NFT backups.
- [Create a bucket](https://filebase.com/docs/get-started/create-a-bucket): Bucket creation, naming, and access levels; select an IPFS bucket when CIDs are required.
- [Generate access keys](https://filebase.com/docs/get-started/access-keys): Obtain and manage the key pair used by S3 clients.
- [Access Keys console](https://console.filebase.com/keys): Access key management and bucket-specific IPFS RPC / Pinning Service API tokens.
- [AWS CLI quickstart](https://filebase.com/docs/get-started/quickstart-aws-cli): Configure a Filebase S3 client and perform initial uploads and downloads.
## IPFS concepts and storage
- [IPFS storage overview](https://filebase.com/docs/ipfs/overview): IPFS-backed buckets and the IPFS product family. Use this guide's unified S3 configuration for client setup.
- [What is IPFS?](https://filebase.com/docs/ipfs/concepts/what-is-ipfs): Peer-to-peer content distribution, content addressing, native IPFS URLs, and HTTP access.
- [What is an IPFS CID?](https://filebase.com/docs/ipfs/concepts/what-is-an-ipfs-cid): Content identifiers, CIDv0 and CIDv1, directory addressing, and gateway usage.
- [What is IPFS pinning?](https://filebase.com/docs/ipfs/concepts/what-is-ipfs-pinning): Retention, garbage collection, automatic pinning, and remote pinning.
- [What is an IPFS gateway?](https://filebase.com/docs/ipfs/concepts/what-is-an-ipfs-gateway): HTTP retrieval, path and subdomain addressing, and public versus dedicated gateways.
- [IPFS bandwidth usage](https://filebase.com/docs/ipfs/bandwidth-usage): S3, Gateway, Public GW, Bitswap, Trustless, RPC, and Sites bandwidth categories and IPFS egress accounting.
## IPFS pinning and APIs
- [Pinning OpenAPI specification](https://filebase.com/openapi.json): Self-contained OpenAPI 3.0.3 contract for Filebase's five pinning operations, bucket-token authentication, typed requests and responses, and Filebase-specific errors and replacement behavior. Suitable for API clients and agent tool import.
- [Pinning files and folders](https://filebase.com/docs/ipfs/pinning/pinning-files): Console and S3 uploads, CAR imports with `import=car`, and re-pinning existing CIDs.
- [Listing files](https://filebase.com/docs/ipfs/pinning/listing-files): List bucket objects or pin records and read CID metadata with `HeadObject`.
- [Deleting files](https://filebase.com/docs/ipfs/pinning/deleting-files): Delete objects or pin records and understand what unpinning means.
- [Pinning event notifications](https://filebase.com/docs/ipfs/pinning/event-notifications): Pin lifecycle webhooks, event payloads, and signature verification.
- [IPFS Pinning Service API](https://filebase.com/docs/ipfs/pinning-service-api): Bearer authentication, create/list/get/replace/delete operations, request IDs, statuses, filters, metadata, pagination, errors, and remote service registration.
- [IPFS RPC API](https://filebase.com/docs/ipfs/rpc-api): Supported POST endpoints for add/cat, raw block retrieval, CAR DAG import, pinning, MFS, IPNS key management, and name publishing/resolution. Includes Filebase-specific limitations.
## IPNS names
- [IPNS names](https://filebase.com/docs/ipfs/ipns-names): Stable mutable pointers to CIDs; managed-name creation, listing, updates, deletion, public network keys, TTL, and validity.
## IPFS gateways and CDN
- [Managing dedicated gateways](https://filebase.com/docs/ipfs/gateways/managing-dedicated-gateways): Provision, list, configure, disable, and delete gateways through the console or Platform API.
- [Gateway access controls](https://filebase.com/docs/ipfs/gateways/access-controls): Public, account-pinned-only private, and scoped CID modes, plus gateway authentication.
- [Gateway custom domains](https://filebase.com/docs/ipfs/gateways/custom-domain): DNS setup and automatic TLS for dedicated gateways on your own hostname.
- [Gateway image optimizations](https://filebase.com/docs/ipfs/gateways/image-optimizations): Resize, crop, compress, and convert images through gateway URL parameters and cached transformations.
- [Gateway activity streams](https://filebase.com/docs/ipfs/gateways/activity-streams): Inspect requests, debug delivery, and query per-gateway bandwidth usage.
- [Filebase IPFS CDN](https://filebase.com/ipfs-cdn/): Product overview of CDN delivery for IPFS content.
## Filebase Sites
- [Sites overview](https://filebase.com/docs/ipfs/sites/overview): Static website hosting on IPFS with automatic IPNS names and stable `myfilebase.site` URLs.
- [Managing Sites](https://filebase.com/docs/ipfs/sites/managing-sites): Create a site, deploy updated CIDs, import CAR builds, and remove sites.
- [Sites custom domains](https://filebase.com/docs/ipfs/sites/custom-domains): Connect a custom hostname, configure DNS, and provision TLS; consult current plan availability.
## NFT Backup
- [NFT Backup overview](https://filebase.com/docs/ipfs/nft-backup/overview): Preserve NFT media and metadata in IPFS buckets using on-chain references.
- [Supported NFT chains](https://filebase.com/docs/ipfs/nft-backup/supported-chains): Current blockchain coverage for NFT Backup.
- [Backing up NFTs](https://filebase.com/docs/ipfs/nft-backup/backing-up-nfts): Configure collection backups, choose a destination bucket, monitor progress, and use one-time or continuous backup modes.
## General S3-compatible object storage
- [S3 API overview](https://filebase.com/docs/s3-api/overview): Endpoint, region, addressing styles, request signing, and API behavior.
- [S3 authentication](https://filebase.com/docs/s3-api/authentication): AWS SigV4, credentials, signing, and authentication troubleshooting.
- [Supported S3 operations](https://filebase.com/docs/s3-api/supported-operations): Bucket, object, listing, and multipart operations.
- [S3 compatibility matrix](https://filebase.com/docs/s3-api/compatibility-matrix): Supported, partial, and unsupported behavior, including ACLs, policies, versioning, lifecycle rules, and checksums.
- [Multipart upload](https://filebase.com/docs/s3-api/multipart-upload): Initiate, upload parts, complete, and abort large uploads.
- [Presigned URLs](https://filebase.com/docs/s3-api/presigned-urls): Temporary access for uploads, downloads, and supported operations without sharing account credentials.
- [CORS](https://filebase.com/docs/s3-api/cors): Cross-origin browser access, allowed methods/origins, and exposed headers.
- [Server-side encryption](https://filebase.com/docs/s3-api/server-side-encryption): General object-storage encryption behavior and supported compatibility headers.
- [Object checksums](https://filebase.com/docs/s3-api/object-checksums): Read and verify full-object SHA256 checksums, handle multipart objects, and distinguish checksums from IPFS CIDs.
- [S3 error codes](https://filebase.com/docs/s3-api/error-codes): Error response format, diagnosis, and request IDs for support.
- [S3 rate limits](https://filebase.com/docs/s3-api/rate-limits): Current throttling behavior, concurrency guidance, and exponential backoff.
- [Buckets and objects](https://filebase.com/docs/concepts/buckets-and-objects): Bucket naming, object keys, metadata, and storage organization.
- [Public versus private buckets](https://filebase.com/docs/concepts/public-vs-private-buckets): General object-storage bucket ACLs, public URLs, and private access.
- [Access keys and authenti