IPFS RPC API

Filebase exposes a subset of the Kubo IPFS HTTP RPC API, letting tools that target the Kubo daemon talk to Filebase directly. It's complementary to the S3-compatible API and simplifies integration with the IPFS CLI, IPFS-compatible libraries, and other standard HTTP clients.

Base URL

https://rpc.filebase.io

Every endpoint is called with POST and requires a Bearer token.

Authentication

Generate an IPFS RPC API token in the Access Keys console — tokens are bucket-specific. Pass it as a Bearer token:

Authorization: Bearer <access-token>

The runnable examples below use a $TOKEN shell variable for your token:

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

IPFS CLI integration

Use the IPFS CLI directly with Filebase by passing the --api flag:

ipfs --api="/dns4/rpc.filebase.io/tcp/443/https" \
  --api-auth="$TOKEN" \
  add ./file.txt

Endpoints

Path	Method	Description
/api/v0/add	POST	Add (and pin) a file.
/api/v0/cat	POST	Stream a file's bytes by CID.
/api/v0/block/get	POST	Retrieve a raw block by CID.
/api/v0/dag/import	POST	Import a CAR file.
/api/v0/pin/add	POST	Pin a CID.
/api/v0/pin/rm	POST	Unpin a CID.
/api/v0/pin/ls	POST	List pinned CIDs.
/api/v0/files/cp	POST	Copy a file into the bucket.
/api/v0/files/flush	POST	Flush the bucket and return its CID.
/api/v0/files/ls	POST	List files in the bucket.
/api/v0/files/mkdir	POST	Create a directory.
/api/v0/files/mv	POST	Move/rename a file.
/api/v0/files/read	POST	Read a file's bytes.
/api/v0/files/rm	POST	Remove a file.
/api/v0/files/stat	POST	Stat a file.
/api/v0/key/gen	POST	Create a new keypair.
/api/v0/key/import	POST	Import a private key.
/api/v0/key/list	POST	List keychain keys.
/api/v0/key/rename	POST	Rename a key.
/api/v0/key/rm	POST	Remove a key.
/api/v0/name/publish	POST	Publish a CID to IPNS.
/api/v0/name/resolve	POST	Resolve an IPNS name.
/api/v0/version	POST	Daemon version info.

Adding and retrieving data

/api/v0/add

Add (and pin) a file to IPFS.

Method: POST

Form field: file (multipart/form-data) — the file to upload.

Query parameters:

Parameter	Type	Description
wrap-with-directory	Boolean	Wrap the uploaded file in a directory. Default: false.
cid-version	Integer	CID version to use (0 or 1). Default: 0.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/add" \
  -F "file=@file1"

Wrap multiple files in a directory and return a v1 CID:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/add?wrap-with-directory=true&cid-version=1" \
  -F "file=@file1" -F "file=@file2"

tip

When wrap-with-directory=true, the returned CID represents a directory containing the file rather than the file directly.

/api/v0/cat

Fetch and return the contents of a file by CID.

Method: POST

Query parameter: arg (string) — CID of the file.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/cat?arg=Qm..."

/api/v0/block/get

Retrieve a raw block by CID.

Method: POST

Query parameter: arg (string) — CID of the block.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/block/get?arg=Qm..."

/api/v0/dag/import

Import a CAR file containing DAG data.

Method: POST

Form field: file (multipart/form-data) — the CAR file to import.

Query parameters:

Parameter	Type	Description
pin-roots	Boolean	Pin the roots of the imported DAG. Default: true.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/dag/import" \
  -F "file=@archive.car"

Import without pinning the roots:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/dag/import?pin-roots=false" \
  -F "file=@archive.car"

tip

CAR (Content Addressable aRchive) files are a serialization format for IPFS DAGs. Use this endpoint to import pre-built CAR files directly into Filebase.

Pinning

/api/v0/pin/add

Pin a CID to ensure it remains stored.

Method: POST

Query parameter: arg (string) — CID to pin.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/pin/add?arg=Qm..."

/api/v0/pin/rm

Unpin a CID to remove it from persistent storage.

Method: POST

Query parameter: arg (string) — CID to unpin.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/pin/rm?arg=Qm..."

/api/v0/pin/ls

List all pinned objects.

Method: POST

Optional query parameters:

• arg (string) — filter to a specific CID (repeat to filter by several).
• stream (boolean) — stream results as newline-delimited JSON instead of a single response.
• names (boolean) — include each pin's Name in the output.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/pin/ls"

Mutable File System (MFS)

These endpoints expose a bucket as a mutable file system, mirroring Kubo's ipfs files commands. Paths are object names within the bucket and must start with a leading /.

/api/v0/files/cp

Copy a file to a new path in the bucket. The source can be an existing bucket path or an external /ipfs/ or /ipns/ path.

Method: POST

Query parameters:

• arg (string) — source path (first arg): a bucket path, or an external /ipfs/... or /ipns/... path.
• arg (string) — destination path (second arg). Must start with a leading /.
• force (boolean, optional) — overwrite an existing file at the destination.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/cp?arg=/source.txt&arg=/copy.txt"

info

Copying from an external /ipfs/ or /ipns/ source imports an existing CID and requires a paid plan.

/api/v0/files/flush

Flush the bucket and return its current root CID.

Method: POST

Query parameter: arg (string, optional) — must be / (the root) if provided.

Returns { "Cid": "<bucket-cid>" }.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/flush"

/api/v0/files/ls

List files in the bucket, optionally under a path prefix.

Method: POST

Query parameter: arg (string, optional) — path prefix to list under. Omit to list from the root.

Returns { "Entries": [...] }, where each entry has Name, Type, Size, and Hash.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/ls?arg=/"

/api/v0/files/mkdir

Create a directory in the bucket.

Method: POST

Query parameter: arg (string) — directory path to create.

Optional query parameter: cid-version (integer) — CID version to use (0 or 1). Default: 0.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/mkdir?arg=/my-dir"

warning

The parents flag is not supported — requests with parents=true return a 400 error.

/api/v0/files/mv

Move or rename a file within the bucket.

Method: POST

Query parameters:

• arg (string) — source path (first arg).
• arg (string) — destination path (second arg).

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/mv?arg=/old.txt&arg=/new.txt"

/api/v0/files/read

Read the contents of a file in the bucket.

Method: POST

Query parameter: arg (string) — file path (must start with a leading /).

Optional query parameters:

• offset (integer) — byte offset to begin reading from.
• count (integer) — number of bytes to read.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/read?arg=/file.txt"

/api/v0/files/rm

Remove a file from the bucket.

Method: POST

Query parameter: arg (string) — file path (must start with a leading /).

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/rm?arg=/file.txt"

warning

The recursive and force flags are not supported — requests setting either to true return a 400 error.

/api/v0/files/stat

Return stat information for a file in the bucket.

Method: POST

Query parameter: arg (string) — file path (must start with a leading /).

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/files/stat?arg=/file.txt"

Keys

Keys are IPNS keypairs used to publish and update IPNS records. See IPNS names for the bigger picture.

/api/v0/key/gen

Create a new keypair.

Method: POST

Query parameter: arg (string) — name of the key to create.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/key/gen?arg=my-key"

/api/v0/key/import

Import a private key into the keychain.

Method: POST

Query parameter: arg (string) — name to associate with the key.

Form field: file (multipart/form-data) — private key file to import.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/key/import?arg=my-key" \
  -F "file=@my-key.pem"

/api/v0/key/list

List all keys in the keychain.

Method: POST

No parameters.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/key/list"

/api/v0/key/rename

Rename an existing key.

Method: POST

Query parameters:

• arg (string) — current key name.
• arg (string) — new key name.

Optional query parameters:

• force (boolean) — overwrite an existing key name.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/key/rename?arg=old-key&arg=new-key"

/api/v0/key/rm

Remove a key from the keychain.

Method: POST

Query parameter: arg (string) — name of the key to remove.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/key/rm?arg=my-key"

IPNS names

/api/v0/name/publish

Publish a CID to IPNS.

Method: POST

Query parameter: arg (string) — IPFS path or CID to publish.

Optional query parameters:

• key (string) — key name to publish with.
• validity (string) — record validity duration (e.g. 24h). Default: 48h.
• ttl (string) — cache TTL for resolvers (e.g. 5m). Default: 5m.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/name/publish?arg=/ipfs/Qm...&key=my-key"

/api/v0/name/resolve

Resolve an IPNS name to an IPFS path.

Method: POST

Query parameter: arg (string) — IPNS name or /ipns/ path.

Optional query parameters:

• recursive (boolean) — resolve until the result is not an IPNS name. Default: true.
• nocache (boolean) — do not use cached entries. Default: false.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/name/resolve?arg=/ipns/k51qzi5uqu5d..."

Daemon

/api/v0/version

Get the version of the IPFS daemon.

Method: POST

No parameters.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://rpc.filebase.io/api/v0/version"

What's next

• Pinning Service API
• IPNS names
• Pinning files